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

FileSystemChangeRecord

· 52CE 我爱测

File System API 的 **`FileSystemChangeRecord`** 字典包含 FileSystemObserver 观察到的单个更改的详细信息。

File System API

File System API 的 FileSystemChangeRecord 字典包含 FileSystemObserver 观察到的单个更改的详细信息。

传递给 FileSystemObserver.FileSystemObserver 构造函数的回调函数的 records 参数是一个由 FileSystemChangeRecord 对象组成的数组。

实例属性

  • changedHandle

    • : 对观察到变化的文件系统句柄的引用。

      • 对于用户可观察的文件系统,这可以是 FileSystemFileHandle 或 FileSystemDirectoryHandle。
      • 对于源私有文件系统(OPFS),它可以是 FileSystemFileHandle、FileSystemDirectoryHandle 或 FileSystemSyncAccessHandle。

      对于 "disappeared"、"errored" 或 "unknown" 类型的记录,此属性将为 null。

  • relativePathComponents

    • : 包含从 root 到 changedHandle 的相对文件路径的路径组件的数组,其中包括 changedHandle 文件名。
  • relativePathMovedFrom

    • : 对于 "moved" 类型的观测值,此数组包含构成从 root 到 changedHandle 先前位置的相对文件路径的路径组件。如果类型不是 "moved",则此属性为 null。
  • root

    • : 对根文件系统句柄的引用,即传递给启动观察的 observe() 调用的句柄。同样,它可以是 FileSystemFileHandle、FileSystemDirectoryHandle 或 FileSystemSyncAccessHandle。
  • type

    • : 表示观察到的变化类型的字符串。可能的值包括:
      • appeared
        • : 该文件或目录已创建或移动到 root 文件结构中。
      • disappeared
        • : 文件或目录已被删除或移出 root 文件结构。要查明哪个文件或目录消失了,你可以查询 relativePathComponents 属性。
      • errored
        • : 观察到的目录中出现了错误状态。以下情况可能导致此错误:
          • 观察不再有效。当观察的句柄(即观察的 root)被删除或移动时,可能会发生这种情况。在这种情况下,系统会记录一个 "disappeared" 的观察,然后记录一个 "errored" 的观察。在这种情况下,你可能希望使用 FileSystemObserver.disconnect() 停止观察文件系统。
          • 已达到每个源的观测数量上限。此限制取决于操作系统,且无法提前知晓。如果发生这种情况,网站可能会决定重试,但无法保证操作系统是否已释放足够的资源。
          • 访问目录或文件句柄的权限已被删除。
      • modified
        • : 文件或目录已被修改。
      • moved
        • : 文件或目录已在根文件结构内移动。

          [!NOTE] 在 Windows 上,目录之间不支持 "moved" 的观察结果。它们在源目录中会被报告为 "disappeared" 的观察结果,在目标目录中则会被报告为 "appeared" 的观察结果。

      • unknown
        • : 表示部分观测数据缺失。如果你希望了解缺失观测数据中发生了哪些变化,可以回退到轮询被观测的目录。

根据操作系统的不同,并非所有观察结果都会以相同的详细程度进行报告,例如,当目录内容递归更改时。在最好的情况下,网站会收到一条详细的更改记录,其中包含更改类型和受影响路径的句柄。在最坏的情况下,网站会收到一条更通用的更改记录(即 "unknown" 类型),但仍然需要枚举目录才能确定哪个句柄发生了更改。

这仍然比轮询有所改进,因为目录枚举可以从回调函数按需启动,而无需定期轮询更改。

示例

初始化 FileSystemObserver

在开始观察文件或目录更改之前,你需要初始化一个 FileSystemObserver 来处理这些观察结果。这可以通过 FileSystemObserver.FileSystemObserver 构造函数来完成,该构造函数接受一个回调函数作为参数:

const observer = new FileSystemObserver(callback);

你可以指定回调函数主体,以任何你想要的方式返回和处理文件更改观察结果。records 数组中的每个对象都是一个 FileSystemChangeRecord 对象:

const callback = (records, observer) => {
  for (const record of records) {
    console.log("检测到的变化:", record);
    const reportContent = `观察到的变更为 ${record.changedHandle.kind} ${record.changedHandle.name}。类型:${record.type}。`;
    sendReport(reportContent); // 某种用户定义的报告函数
  }

  observer.disconnect();
};

规范

目前不属于任何规范。相关规范 PR 请参阅 https://github.com/whatwg/fs/pull/165。

参见

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

资料来源与适用范围

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

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

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