非标准
该特性是非标准的,请尽量不要在生产环境中使用它!
文件与目录条目 API 模拟一个 web 应用可以导航和访问的本地文件系统。你在虚拟的沙箱文件系统中可以开发一个读、写、创建文件或者目录的应用。
因为这是一个非标准 API,它的规范目前还没有在标准的轨道上,所以要记住,并不是所有的浏览器都实现了它,而且那些实现了的浏览器可能只实现了它的一小部分。有关详细信息,请查看浏览器兼容性部分。
根据您希望的是异步行为还是同步行为,存在两个非常相似的 API。同步 API 可在 Worker
中使用,并将返回所需的值。异步 API 不会阻塞和函数,API不会返回值;相反,您将需要提供一个回调函数,以便在响应到达时处理它。
Firefox 实现的文件与目录条目 API 非常有限;不支持创建文件。仅用于访问用户在 file <input>
元素中选择的文件(也请参阅 HTMLInputElement
中选择的文件),或使用拖放将文件或目录提供给 Web 站点或应用程序时。Firefox 也没有实现同步 API。仔细检查您使用的 API 的任何部分的浏览器兼容性,并查看 Firefox 中文件与目录条目 API 支持的更多细节。
访问文件系统
有两种方法可以访问当前规范草案中定义的文件系统:
- 当处理用于拖放的
drop
事件时,您可以调用DataTransferItem.webkitGetAsEntry()
来为被删除的项获取FileSystemEntry
。如果结果不是null
,那么它就是一个被删除的文件或目录,您可以使用文件系统调用来处理它。 - 属性允许您访问当前选定文件的
FileSystemFileEntry
对象,但前提是将它们拖放到文件选择器(bug 1326031)。如果htmlinputel.webkitdirectory
为真,则<input>
元素是一个目录选择器,您将为每个选择的目录获得FileSystemDirectoryEntry
对象。
异步 API
大多数操作都应该使用异步API,以防止在主线程上使用文件系统访问时阻塞整个浏览器。它包括以下接口:
FileSystem
- 表示文件系统。
FileSystemEntry
- 表示文件系统中单个条目的基本接口。这是由表示文件或目录的其他接口实现的。
FileSystemFileEntry
- 表示文件系统中的单个文件。
FileSystemDirectoryEntry
- 表示文件系统中的单个目录。
FileSystemDirectoryReader
- 该接口通过调用
FileSystemDirectoryEntry.createReader()
创建,提供了允许读取目录内容的功能。 FileSystemFlags
- 定义一组值,这些值用于在调用文件和目录API中的某些方法时指定选项标志。
FileError
- 表示由异步文件系统调用生成的错误。
还有两个全局函数(目前不属于规范的一部分,仅在 Google Chrome 中被实现)。它们在 Window
对象上可用,并在LocalFileSystem
: requestFileSystem()
和 resolveLocalFileSystemURL()
中实现。
同步API
同步 API 应该只用于 Worker
中;在执行完毕前,这些调用会阻塞运行,并且只会简单地返回结果,而不是使用回调。在主线程上使用它们会阻塞整个浏览器,这很不明智。否则,下面的接口将镜像来自异步 API 的接口。
FileSystemSync
- 表示文件系统。
FileSystemEntrySync
- 表示文件系统中单个条目的基本接口。这是由表示文件或目录的其他接口实现的。
EntrySync
FileSystemFileEntrySync
- 表示文件系统中的单个文件。
FileSystemDirectoryEntrySync
- 表示文件系统中的单个目录。
FileSystemDirectoryReaderSync
- 该接口通过调用
FileSystemDirectoryEntrySync.createReader()
创建,提供了允许读取目录内容的功能。 FileException
- Represents an error which is generated by synchronous file system calls.
还有两个全局函数(目前不属于规范的一部分,仅在 Google Chrome 中被实现)。在 LocalFileSystemSync
: requestFileSystemSync()
和 resolveLocalFileSystemSyncURL()
中实现。
其他接口
LocalFileSystem
- 使您能够访问沙盒文件系统。
LocalFileSystemSync
LockedFile
- 提供处理具有所有必要锁的给定文件的工具。
Metadata
规范
规范 | 状态 | 备注 |
---|---|---|
File and Directory Entries API | Draft | Draft of proposed API |
此 API 没有正式的 W3C 或 WHATWG 规范。
浏览器兼容性
FileSystem
BCD tables only load in the browser
FileSystemSync 属性
BCD tables only load in the browser
Firefox 50 中引入了对文件与目录条目 API 的部分支持。在使用各个接口和方法之前,一定要检查它们的兼容性表,确保它们得到支持。将 about:config 中的 dom.webkitBlink.filesystem
值设为 false
可禁用该 API。