FileSystemChangeRecord
FileSystemChangeRecord 字典是 File System API 的一部分,其中包含由 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。 根-
对根文件系统句柄的引用,即传递给启动观察的
observe()调用的句柄。同样,这可以是FileSystemFileHandle、FileSystemDirectoryHandle或FileSystemSyncAccessHandle。 type-
表示观察到的更改类型的字符串。可能的值包括:
appeared-
文件或目录已在
root文件结构中创建或移入。 disappeared-
文件或目录已在
root文件结构中删除或移出。要找出消失的文件或目录,可以查询relativePathComponents属性。 errored-
在观察到的目录中发生了错误状态。这可能发生在
- 观察不再有效。当被观察的句柄(即观察的
root)被删除或移动时,可能会发生这种情况。在这种情况下,将记录一条"disappeared"观察,然后是一条"errored"观察。在这种情况下,您可能希望使用FileSystemObserver.disconnect()停止观察文件系统。 - 已达到每个源的观察最大限制。此限制取决于操作系统,并且无法预先知道。如果发生这种情况,网站可以尝试重试,但不能保证操作系统会释放足够的资源。
- 对目录或文件句柄的访问权限被移除。
- 观察不再有效。当被观察的句柄(即观察的
modified-
文件或目录已修改。
moved-
文件或目录已在根文件结构内移动。
注意:在 Windows 上,
"moved"观察不支持在目录之间进行。它们在源目录中报告为"disappeared"观察,在目标目录中报告为"appeared"观察。 unknown-
表示某些观察被遗漏了。如果您想了解有关遗漏观察中发生了什么变化的详细信息,可以回退到轮询观察到的目录。
根据操作系统,并非所有观察都会以相同的详细程度报告,例如,当目录的内容递归更改时。最好的情况是,网站将收到一条详细的更改记录,其中包含更改类型和一个指向受影响路径的句柄。最坏的情况是,网站将收到一条更通用的更改记录(即,类型为 "unknown"),仍然需要它来枚举目录以确定哪个句柄发生了更改。
这仍然比轮询有所改进,因为目录枚举可以从回调函数按需启动,而不是需要定期轮询更改。
示例
初始化 FileSystemObserver
在您开始观察文件或目录更改之前,您需要初始化一个 FileSystemObserver 来处理这些观察。这是使用 FileSystemObserver() 构造函数完成的,该构造函数接受一个回调函数作为参数。
const observer = new FileSystemObserver(callback);
您可以在 records 数组中的每个对象是 FileSystemChangeRecord 对象 回调函数 体中指定以您想要的任何方式返回和处理文件更改观察。
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。