FileSystemSyncAccessHandle: write() 方法

基线 2023

新可用

自 2023 年 3 月起，此功能在最新的设备和浏览器版本中均可使用。此功能可能在较旧的设备或浏览器中无法使用。

安全上下文：此功能仅在安全上下文（HTTPS）中可用，在部分或所有支持的浏览器中可用。

注意：此功能仅在专用 Web 工作线程中可用。

FileSystemSyncAccessHandle 接口的write() 方法将指定缓冲区的内容写入与句柄关联的文件，可以选择在给定偏移量处写入。

位于来源专用文件系统中的文件对最终用户不可见，因此不受对用户可见文件系统中运行的方法相同的安全检查。因此，使用 FileSystemSyncAccessHandle.write() 执行的写入性能要高得多。这使得它们适合进行重要的、大规模的文件更新，例如SQLite 数据库修改。

语法

js
write(buffer, options)

参数

buffer

一个ArrayBuffer 或 ArrayBufferView（例如 DataView），表示要写入文件的缓冲区。

options 可选

包含以下属性的选项对象

at

一个数字，表示从文件开头开始的偏移量（以字节为单位），缓冲区应写入该偏移量。

注意：您无法直接操作 ArrayBuffer 的内容。相反，您创建像 Int8Array 或 DataView 这样的类型化数组对象，它以特定格式表示缓冲区，并使用它来读写缓冲区的内容。

返回值

一个数字，表示写入文件的字节数。

异常

InvalidStateError DOMException

如果关联的访问句柄已关闭，或者如果对文件二进制数据的修改完全失败，则会抛出此异常。

QuotaExceededError DOMException

如果增加的数据容量超过浏览器的存储配额，则会抛出此异常。

TypeError

如果底层文件系统不支持从指定文件偏移量写入文件，则会抛出此异常。

示例

以下异步事件处理程序函数包含在 Web 工作线程中。在收到来自主线程的消息时，它

  • 创建一个同步文件访问句柄。
  • 获取文件的大小并创建一个ArrayBuffer 来包含它。
  • 将文件内容读取到缓冲区中。
  • 对消息进行编码并将其写入文件末尾。
  • 将更改持久化到磁盘并关闭访问句柄。
js
onmessage = async (e) => {
  // Retrieve message sent to work from main script
  const message = e.data;

  // Get handle to draft file
  const root = await navigator.storage.getDirectory();
  const draftHandle = await root.getFileHandle("draft.txt", { create: true });
  // Get sync access handle
  const accessHandle = await draftHandle.createSyncAccessHandle();

  // Get size of the file.
  const fileSize = accessHandle.getSize();
  // Read file content to a buffer.
  const buffer = new DataView(new ArrayBuffer(fileSize));
  const readBuffer = accessHandle.read(buffer, { at: 0 });

  // Write the message to the end of the file.
  const encoder = new TextEncoder();
  const encodedMessage = encoder.encode(message);
  const writeBuffer = accessHandle.write(encodedMessage, { at: readBuffer });

  // Persist changes to disk.
  accessHandle.flush();

  // Always close FileSystemSyncAccessHandle if done.
  accessHandle.close();
};

注意：在规范的早期版本中，close()、flush()、getSize() 和 truncate() 被错误地指定为异步方法，并且某些浏览器的旧版本以这种方式实现它们。但是，所有当前支持这些方法的浏览器都将它们实现为同步方法。

规范

规范
文件系统标准
# api-filesystemsyncaccesshandle-write

浏览器兼容性

BCD 表格仅在启用了 JavaScript 的浏览器中加载。

另请参阅