File System Observer API 源试用

Thomas Steiner

File System Access API 和 Origin Private File System API 都允许开发者访问用户设备上的文件和目录。前者允许开发者对用户可见的常规文件系统执行读写操作，而后者会打开对用户文件系统隐藏的特殊文件系统，该权限仅对每个网站的源用户可见，具有某些性能优势。在这两种情况下，开发者通过 FileSystemHandle 对象与文件和目录互动。具体来说，就是通过 FileSystemFileHandle（针对文件）和 FileSystemDirectoryHandle（针对目录）进行交互。到目前为止，获悉任一文件系统中的文件或目录更改时，需要通过某种形式的轮询和比较 lastModified 时间戳，甚至是文件内容本身。

在 Chrome 129 开始源试用期间，File System Observer API 对此进行了更改，并在发生更改时自动提醒开发者。本指南将介绍其工作原理以及如何试用此功能。

使用场景

在需要尽快获悉文件系统可能发生的更改的应用中使用 File System Observer API。

• 基于网络的集成开发环境 (IDE)，以表示项目的文件系统树。
• 将文件系统变更与服务器同步的应用。例如，SQLite 数据库文件。
• 需要从工作器或其他标签页将文件系统变更通知主线程的应用。
• 可观察资源目录的应用，例如自动优化图片。

如何使用 File System Observer API

功能检测

如需查看 File System Observer API 是否受支持，请运行功能测试，如以下示例所示。

if ('FileSystemObserver' in self) {
  // The File System Observer API is supported.
}

注意 ：如需了解通过轮询对 File System Observer API 的行为执行 polyfill 的一般方法，请参阅说明。

初始化文件系统观察器

通过调用 new FileSystemObserver() 并向其提供 callback 函数作为参数，初始化文件系统观察器。

const observer = new FileSystemObserver(callback);

开始观察文件或目录

如需开始观察文件或目录，请调用 FileSystemObserver 实例的异步 observe() 方法。为此方法提供所选文件或目录的 FileSystemHandle 作为参数。在观察目录时，有可选的 options 参数可让您选择是否以递归方式获知目录更改（即目录本身和所有包含的子目录和文件）的更改。默认选项是仅观察目录本身和直接包含的文件。

// Observe a file.
await observer.observe(fileHandle);
// Observe a directory.
await observer.observe(directoryHandle);
// Observe a directory recursively.
await observer.observe(directoryHandle, {recursive: true});

回调函数

当文件系统发生更改时，系统会使用文件系统更改 records 和 observer 本身作为其参数来调用回调函数。例如，您可以使用 observer 参数在全部删除后断开与观察器的连接（请参阅停止观察文件系统）。

const callback = (records, observer) => {
  for (const record of records) {
    console.log('Change detected', record);
  }
};

文件系统变更记录

每个文件系统变更记录都具有以下结构。所有字段均为只读字段。

• root（FileSystemHandle）：传递给 FileSystemObserver.observe() 函数的句柄。
• changedHandle（一个 FileSystemHandle）：受文件系统更改影响的句柄。
• relativePathComponents（Array）：changedHandle 相对于 root 的路径。
• type（一个 String）：更改的类型。可能出现以下类型： <ph type="x-smartling-placeholder">
  </ph>
  • "appeared"：文件或目录已创建或已移至 root。
  • "disappeared"：文件或目录已被删除或移出 root。
  • "modified"：文件或目录被修改。
  • "moved"：文件或目录在 root 中移动。
  • "unknown"：表示错过了零个或多个事件。对此，开发者应轮询所监控的目录。
  • "errored"：观察结果不再有效。在这种情况下，您可能需要停止观察文件系统。
• relativePathMovedFrom（Array，可选）：移动的句柄之前的位置。仅当 type 为 "moved" 时可用。

。

注意： 根据操作系统的不同，并非所有更改事件都会以相同的详细程度报告，例如，当目录的内容以递归方式更改时。最多情况下，网站会收到详细的更改记录，其中包含更改类型以及受影响路径的标识名。最坏的情况是，网站会收到更宽泛的变更记录（即，值为 "unknown" 的 type），而这仍然需要网站枚举目录来找出更改的子项。这仍然是与轮询相比的改进，因为目录枚举可以从回调函数按需启动，而无需轮询间隔时间的更改。

注意： 在 Windows 上，目录之间不支持 "moved" 事件。它们在源目录中报告为 "disappeared"，在目标目录中报告为 "appeared"。当源和目标位于同一目录中时，它们会报告为 "moved"。

停止观察文件或目录

如需停止观察 FileSystemHandle，请调用 unobserve() 方法，并以参数形式向其传递句柄。

observer.unobserve(fileHandle);

注意 ：在源试用期间，unobserve() 方法不受支持。请使用 disconnect() 方法作为权宜解决方法。

停止观察文件系统

如需停止观察文件系统，请按如下方式断开连接 FileSystemObserver 实例。

observer.disconnect();

试用 API

如需在本地测试 File System Observer API，请在 about:flags 中设置 #file-system-observer 标志。如需让真实用户测试此 API，请注册源试用，并按照 Chrome 源试用指南中的说明操作。源试用将从 Chrome 129（2024 年 9 月 11 日）到 Chrome 134（2025 年 2 月 26 日）结束。

演示

您可以在嵌入式演示中查看 File System Observer API 的实际应用。查看源代码，或在 Glitch 上重新混合演示代码。此演示版会在观察到的目录中随机创建、删除或修改文件，并在应用窗口的上半部分记录其活动。然后，当更改出现在应用窗口的下半部分时，它会记录这些更改。如果您在不支持 File System Observer API 的浏览器上看到此内容，请查看该演示的屏幕截图。

反馈

如果您对 File System Observer API 的形状有反馈意见，请针对 WHATWG/fs 代码库中的问题 123 添加注释。

相关链接

• 解说
• TAG 审核
• Mozilla 标准排名
• WebKit 标准位置
• ChromeStatus
• Chromium 错误

致谢

本文档由 Daseul Lee、Nathan Memmott、Etienne Noël 和 Rachel Andrew 审核。