文件系统 API - Web API | MDN

HTML: Markup language
CSS: Styling language
JavaScript: Scripting language
Web APIs: Programming interfaces
Learn web development
Get to know MDN better
此页面由社区从英文翻译而来。了解更多并加入 MDN Web Docs 社区。
View in English Always switch to English
安全上下文: 此特性仅在一些支持的浏览器的安全上下文（HTTPS）中可用。
备注： 此特性在 Web Worker 中可用。
文件系统 API（File System API）——以及通过文件系统访问 API（File System Access API）提供的扩展来访问设备文件系统中的文件——允许使用文件读写以及文件管理功能。
请参阅与其他文件相关 API 的关系，以了解此 API、文件和目录条目 API 和文件 API 之间的区别。
此 API 允许程序与用户本地设备上的或是用户能够访问的网络文件系统上的文件进行交互。此 API 的核心功能包括读取文件、写入或保存文件以及访问目录结构。
大多数与文件和目录的交互都通过句柄来完成。父类 FileSystemHandle 派生出两个子类：FileSystemFileHandle 和 FileSystemDirectoryHandle，分别表示文件句柄和目录句柄。
一个句柄代表了用户操作系统上的一个文件或目录。你可以通过调用诸如 window.showOpenFilePicker() 和 window.showDirectoryPicker() 一类的方法向用户显示一个文件选择器或目录选择器，以此来获得句柄。一旦调用了这些函数，选择器就会出现，用户可以用它选择一个文件或目录。只要这个步骤成功完成，就会返回句柄。
每种句柄都提供了其独有的功能，取决于你使用的种类，会有些许差异（详见接口部分）。在获得句柄后，你便可以访问文件的数据或是被选中的目录的信息（包含子目录）。此 API 开辟了 web 此前一直缺乏的潜在功能。但不论如何，安全性是设计 API 时的首要考量，除非用户明确授权，否则就不允许访问文件和目录的数据（注意：源私有文件系统并非如此，因为其对用户不可见）。
备注：使用此 API 的特性时可能会抛出的各种异常已在规范定义的相关页面中列出。然而，API 与底层操作系统的交互使得实际情况更加复杂。这里提供一篇关于在规范中列出错误对应表的提议，其中包含了一些有用的信息。
备注：基于 FileSystemHandle 的对象能够被序列化存储至 IndexedDB 数据库实例中，也可以通过 postMessage() 传递。
源私有文件系统（origin private file system，OPFS）属于文件系统 API，提供了页面所属的源专用的存储端点，并且不像常规文件系统那样对用户可见。它提供对一种经过高度性能优化的特殊文件的访问能力的选择，例如，对文件内容的原地写入访问。
当选择要上传的文件或目录时，你可以将文件复制到本地沙盒中并一次上传一个块。
应用可以在中断后重新启动上传，例如浏览器关闭或崩溃、连接中断或计算机关机。
具有大量媒体静态资源的视频游戏或其他应用
应用下载一个或多个大型 tar 包并将其本地展开为目录结构。
应用在后台预先获取静态资源，因此用户无需等待下载即可进入下一个任务或游戏级别。
支持离线访问或本地缓存的音频或照片编辑器（性能和速度极佳）
请阅读我们的源私有文件系统，以了解如何使用它。
包含 FileSystemObserver 观察到的单个更改的详细信息。
代表文件或目录条目的对象。多个句柄可以指代同一个条目。大多数情况你都不会直接用到 FileSystemHandle，而是会用到它的子接口 FileSystemFileHandle 和 FileSystemDirectoryHandle。
提供一种观察所选文件或目录的变化的机制。
提供一个文件系统条目的同步句柄，用于在磁盘上原地操作单个文件。其在文件读写上的同步特性可在异步操作开销较大的情景中使关键方法拥有更优秀的性能，例如 WebAssembly。此类只能在专用于操作源私有文件系统上的文件的专用 Web Worker 中访问。
一个附加了便于操作磁盘上单个文件的方法的 WritableStream 对象。
显示允许用户选择一个或多个文件的文件选择器。
返回 Promise，如果拖动的项目是文件，则兑现 FileSystemFileHandle；如果拖动的项目是目录，则兑现 FileSystemDirectoryHandle。
用于获取对 FileSystemDirectoryHandle 对象的引用，该对象允许访问存储在源私有文件系统中的目录及其内容。返回一个兑现 FileSystemDirectoryHandle 对象的 Promise。
以下代码允许用户在文件选择器中选择一个文件。
下面的异步函数可以显示一个文件选择器，并在选择了文件时使用 getFile() 方法取得内容。
下面的示例能够取得指定名称的目录的句柄，如果目录不存在，则创建。
下面的异步函数使用 resolve() 来查找被选择文件相对于指定目录句柄的路径。
以下异步函数能够打开一个文件选择器，并在选择了文件时返回一个 FileSystemFileHandle。然后使用 FileSystemFileHandle.createWritable() 方法创建一个写入流。
然后将用户定义的一个 Blob 写入流中，随后关闭该流。