FileSystemChangeRecord

FileSystemChangeRecord 字典是 File System API 的一部分,其中包含由 FileSystemObserver 观察到的单个更改的详细信息。

传递给 FileSystemObserver() 构造函数的回调函数中的 records 参数是一个 FileSystemChangeRecord 对象数组。

实例属性

changedHandle

一个指向观察到更改的文件的文件系统句柄的引用。

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

relativePathComponents

一个包含路径组件的数组,这些组件构成从 rootchangedHandle 的相对文件路径,包括 changedHandle 的文件名。

relativePathMovedFrom

在类型为 "moved" 的观察情况下,一个包含路径组件的数组,这些组件构成从 rootchangedHandle 之前位置的相对文件路径。如果类型不是 "moved",则此属性将为 null

对根文件系统句柄的引用,即传递给启动观察的 observe() 调用的句柄。同样,这可以是 FileSystemFileHandleFileSystemDirectoryHandleFileSystemSyncAccessHandle

type

表示观察到的更改类型的字符串。可能的值包括:

appeared

文件或目录已在 root 文件结构中创建或移入。

disappeared

文件或目录已在 root 文件结构中删除或移出。要找出消失的文件或目录,可以查询 relativePathComponents 属性。

errored

在观察到的目录中发生了错误状态。这可能发生在

  • 观察不再有效。当被观察的句柄(即观察的 root)被删除或移动时,可能会发生这种情况。在这种情况下,将记录一条 "disappeared" 观察,然后是一条 "errored" 观察。在这种情况下,您可能希望使用 FileSystemObserver.disconnect() 停止观察文件系统。
  • 已达到每个源的观察最大限制。此限制取决于操作系统,并且无法预先知道。如果发生这种情况,网站可以尝试重试,但不能保证操作系统会释放足够的资源。
  • 对目录或文件句柄的访问权限被移除。
modified

文件或目录已修改。

moved

文件或目录已在根文件结构内移动。

注意:在 Windows 上,"moved" 观察不支持在目录之间进行。它们在源目录中报告为 "disappeared" 观察,在目标目录中报告为 "appeared" 观察。

unknown

表示某些观察被遗漏了。如果您想了解有关遗漏观察中发生了什么变化的详细信息,可以回退到轮询观察到的目录。

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

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

示例

初始化 FileSystemObserver

在您开始观察文件或目录更改之前,您需要初始化一个 FileSystemObserver 来处理这些观察。这是使用 FileSystemObserver() 构造函数完成的,该构造函数接受一个回调函数作为参数。

js
const observer = new FileSystemObserver(callback);

您可以在 records 数组中的每个对象是 FileSystemChangeRecord 对象 回调函数 体中指定以您想要的任何方式返回和处理文件更改观察。

js
const callback = (records, observer) => {
  for (const record of records) {
    console.log("Change detected:", record);
    const reportContent = `Change observed to ${record.changedHandle.kind} ${record.changedHandle.name}. Type: ${record.type}.`;
    sendReport(reportContent); // Some kind of user-defined reporting function
  }

  observer.disconnect();
};

规范

目前不是规范的一部分。请参阅 https://github.com/whatwg/fs/pull/165 以获取相关的规范 PR。

另见