FileSystemFileHandle

基线 2023

新可用

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

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

注意：此功能在Web Workers中可用。

FileSystemFileHandle 接口是文件系统 API 的一部分，它表示文件系统条目句柄。可以通过window.showOpenFilePicker() 方法访问该接口。

请注意，读写操作取决于文件访问权限，如果该来源的页面没有其他选项卡保持打开状态，则在页面刷新后这些权限将不会持久保留。queryPermission 方法可以用于在访问文件之前验证FileSystemHandle 接口的权限状态。

FileSystemHandle FileSystemFileHandle

实例属性

继承其父级FileSystemHandle 的属性。

实例方法

继承其父级FileSystemHandle 的方法。

getFile()

返回一个Promise 对象，该对象解析为File 对象，表示句柄所代表的条目的磁盘状态。

createSyncAccessHandle()

返回一个Promise 对象，该对象解析为一个FileSystemSyncAccessHandle 对象，可用于同步读取和写入文件。此方法的同步特性带来了性能优势，但它只能在专用Web Workers 中使用。

createWritable()

返回一个Promise 对象，该对象解析为一个新创建的FileSystemWritableFileStream 对象，可用于写入文件。

示例

读取文件

以下异步函数将显示一个文件选择器，选择文件后，将使用 getFile() 方法检索其内容。

js
async function getTheFile() {
  const pickerOpts = {
    types: [
      {
        description: "Images",
        accept: {
          "image/*": [".png", ".gif", ".jpeg", ".jpg"],
        },
      },
    ],
    excludeAcceptAllOption: true,
    multiple: false,
  };

  // open file picker
  const [fileHandle] = await window.showOpenFilePicker(pickerOpts);
  // get file contents
  const fileData = await fileHandle.getFile();
  return fileData;
}

写入文件

以下异步函数将给定的内容写入文件句柄，从而写入磁盘。

js
async function writeFile(fileHandle, contents) {
  // Create a FileSystemWritableFileStream to write to.
  const writable = await fileHandle.createWritable();

  // Write the contents of the file to the stream.
  await writable.write(contents);

  // Close the file and write the contents to disk.
  await writable.close();
}

同步读取和写入文件

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

  • 创建一个同步文件访问句柄。
  • 获取文件的大小并创建一个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-filesystemfilehandle

浏览器兼容性

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

另请参阅