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。

• 基于 Web 的集成开发环境 (IDE)，用于显示项目的文件系统树的表示法。
• 与服务器同步文件系统更改的应用。例如，SQLite 数据库文件。
• 需要从工作器或其他标签页将文件系统变更通知主线程的应用。
• 监控资源目录的应用，例如自动优化图片。
• 可从热重载中受益的体验，例如基于 HTML 的幻灯片演示文稿，其中文件更改会触发重新加载。

如何使用 File System Observer API

功能检测

如需查看是否支持文件系统观察器 API，请运行功能测试，如以下示例所示。

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

注意：如需了解通过轮询对文件系统观察器 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）：更改的类型。可能出现以下类型：
  • "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

如需在本地测试文件系统观察器 API，请在 about:flags 中设置 #file-system-observer 标志。如需使用真实用户测试该 API，请注册源试用，然后按照 Chrome 源试用指南中的说明操作。源试用将从 Chrome 129（2024 年 9 月 11 日）持续到 Chrome 134（2025 年 2 月 26 日）。

演示

您可以在嵌入的演示版中查看文件系统观察器 API 的实际运作情况。查看源代码，或在 Glitch 上对演示版代码进行混剪。该演示会在受监视的目录中随机创建、删除或修改文件，并在应用窗口的上半部分记录其活动。然后，它会在应用窗口底部发生更改时记录这些更改。如果您是在不支持 File System Observer API 的浏览器上阅读本文，请查看演示的屏幕截图。

反馈

如果您对文件系统观察器 API 的形状有任何反馈，请对 WHATWG/fs 代码库中的第 123 个问题发表评论。

相关链接

• 说明
• 代码审核
• Mozilla 标准排名
• WebKit 标准位置
• ChromeStatus
• Chromium 错误

致谢

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