FileSystemSyncAccessHandle

基线 2023

新可用

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

安全上下文:此功能仅在安全上下文(HTTPS)中可用,在某些或所有支持的浏览器中。

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

FileSystemSyncAccessHandle 接口是 文件系统 API 的一部分,它表示对文件系统条目进行同步操作的句柄。

此类仅可在专用Web 工作线程(以便其方法不会阻塞主线程上的执行)中访问,用于源私有文件系统中的文件,该文件对最终用户不可见。

因此,其方法不受与用户可见文件系统中的文件运行的方法相同的安全检查约束,因此性能更高。这使得它们适合进行大量、大规模的文件更新,例如SQLite 数据库修改。

可以通过 FileSystemFileHandle.createSyncAccessHandle() 方法访问该接口。

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

实例属性

无。

实例方法

close()

关闭打开的同步文件句柄,禁用对它的任何进一步操作,并释放先前对与文件句柄关联的文件施加的独占锁。

flush()

将通过 write() 方法对与句柄关联的文件所做的任何更改持久化到磁盘。

getSize()

以字节为单位返回与句柄关联的文件的大小。

read()

将与句柄关联的文件的内容读取到指定的缓冲区中,可选地指定偏移量。

truncate()

将与句柄关联的文件调整为指定字节数的大小。

write()

将指定缓冲区的内容写入与句柄关联的文件,可选地指定偏移量。

示例

以下异步事件处理程序函数包含在 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();
};

规范

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

浏览器兼容性

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

另请参阅