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）：受文件系统更改影响的句柄。对于 "errored"、"unknown" 和 "disappeared" 类型事件，此字段将为 null。如需查看哪些文件或目录已消失，请使用 relativePathComponents。
• relativePathComponents（一个 Array）：changedHandle 相对于 root 的路径。
• type（一个 String）：更改的类型。可能出现的类型如下：
  • "appeared"：文件或目录已创建或移至 root。
  • "disappeared"：文件或目录已被删除或移出 root。
  • "modified"：文件或目录已修改。
  • "moved"：文件或目录在 root 中移动。
  • "unknown"：表示错过了零个或多个事件。开发者应对此轮询所监控的目录。
  • "errored"：观察结果已失效。在这种情况下，您可能需要停止观察文件系统。当每个来源的观察值达到上限时，系统也会发送此值。此限制取决于操作系统，无法事先得知。如果发生这种情况，网站可能会决定重试，但无法保证操作系统已释放足够的资源。当被观察的句柄（即观察的根）被删除或移动时，系统也会发送此值。在这种情况下，系统会先发送 "disappeared" 事件，然后再发送 "errored" 事件，以指示观察结果已失效。最后，当目录或文件句柄的权限被移除时，系统会发送此事件。
• relativePathMovedFrom（一个 Array，可选）：移动的手柄的旧位置。仅当 type 为 "moved" 时可用。

注意 ：并非所有更改事件都可能以相同的详细级别报告，例如，当目录的内容递归更改时。网站最多会收到详细的更改记录，其中包含更改类型和对受影响路径的句柄。最糟糕的情况是，网站收到更通用的更改记录（即值为 "unknown" 的 type），但仍需要网站枚举目录以确定哪个子目录发生了更改。这仍然比轮询要好，因为目录枚举可以从回调函数中按需启动，而无需按时间间隔轮询更改。

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

停止观察文件或目录

如需停止观察 FileSystemHandle，请调用 unobserve() 方法，并将句柄作为参数传递给该方法。

observer.unobserve(fileHandle);

注意 ：不支持 unobserve() 方法。请使用 disconnect() 方法作为权宜解决方法。如果您对此功能的进展感兴趣，请为功能 bug 加星标。

停止观察文件系统

如需停止观察文件系统，请按如下所示断开 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 bug

致谢

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