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。