大网数据广告活动
Web 标准与前端开发

FileSystemFileHandle

· 52CE 我爱测

File System API 的 **`FileSystemFileHandle`** 接口表示一个指向文件系统条目的句柄。可通过 window.showOpenFilePicker() 方法来访问此接口。

File System API

File System API 的 FileSystemFileHandle 接口表示一个指向文件系统条目的句柄。可通过 window.showOpenFilePicker() 方法来访问此接口。

注意,读写操作所依赖的文件访问权限在刷新或关闭页面并且页面所属的源没有其他标签页保持打开的情况下不会继续保有。FileSystemHandle 接口的 FileSystemHandle.queryPermission() 方法可用于在访问文件前验证权限状态。

实例属性

从父类 FileSystemHandle 继承属性。

实例方法

从父类 FileSystemHandle 继承方法。

  • FileSystemFileHandle.getFile
    • : 返回一个 Promise 对象,可兑现一个 File 对象,该对象表示句柄所代表的条目在磁盘上的状态。
  • FileSystemFileHandle.createSyncAccessHandle
    • : 返回一个 Promise 对象,可兑现一个 FileSystemSyncAccessHandle 对象,该对象可用于同步读写文件。此方法的同步特性带来了性能优势,但是只能在专用的 Web Worker 中使用。
  • FileSystemFileHandle.createWritable
    • : 返回一个 Promise 对象,可兑现一个新建的 FileSystemWritableFileStream 对象,可用于写入文件。

示例

读取文件

下面的异步函数用于显示一个文件选择器,一旦有文件被选择,便可以使用 getFile() 方法获取其内容。

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

  // 打开文件选择器
  const [fileHandle] = await window.showOpenFilePicker(pickerOpts);
  // 获取文件内容
  const fileData = await fileHandle.getFile();
  return fileData;
}

写入文件

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

async function writeFile(fileHandle, contents) {
  // 创建一个 FileSystemWritableFileStream 用来写入。
  const writable = await fileHandle.createWritable();

  // 将文件内容写入到流中。
  await writable.write(contents);

  // 关闭文件并将内容写入磁盘。
  await writable.close();
}

同步读写文件

以下异步事件处理函数处于 Web Worker 上下文,从主线程接收消息。

  • 创建一个异步文件访问句柄。
  • 获取文件大小并创建一个 ArrayBuffer 来容纳它。
  • 将文件内容读取到缓冲区中。
  • 将消息编码,并将其写入到文件末尾。
  • 将更改持久化至磁盘并关闭访问句柄。
onmessage = async (e) => {
  // 获取从主线程发往 worker 的消息
  const message = e.data;

  // 获取草稿文件的句柄
  const root = await navigator.storage.getDirectory();
  const draftHandle = await root.getFileHandle("draft.txt", { create: true });
  // 获取同步访问句柄
  const accessHandle = await draftHandle.createSyncAccessHandle();

  // 获取文件大小
  const fileSize = accessHandle.getSize();
  // 将文件内容读取到缓冲区
  const buffer = new DataView(new ArrayBuffer(fileSize));
  const readBuffer = accessHandle.read(buffer, { at: 0 });

  // 将消息写入到文件末尾
  const encoder = new TextEncoder();
  const encodedMessage = encoder.encode(message);
  const writeBuffer = accessHandle.write(encodedMessage, { at: readBuffer });

  // 将更改持久化至磁盘
  accessHandle.flush();

  // 用完 FileSystemSyncAccessHandle 记得把它关闭
  accessHandle.close();
};

[!NOTE] 在规范的早期版本中,FileSystemSyncAccessHandle.close()、FileSystemSyncAccessHandle.flush()、FileSystemSyncAccessHandle.getSize() 和 FileSystemSyncAccessHandle.truncate() 被错误地指定为异步方法,并且某些较旧版本的浏览器以这种方式实现它们。然而,当前所有支持这些方法的浏览器都将它们实现为同步方法。

规范

浏览器兼容性

参见

来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。

资料来源与适用范围

资料来源
MDN Web Docs / Mozilla 贡献者
适用范围
请按文中版本与环境说明核对
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY-SA 2.5

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。