文件和目录条目 API 简介

本简介讨论了文件和目录条目 API 中的基本概念和术语。它将为您提供整体概述，并引导您了解关键概念。它还描述了如果您忽略了限制，可能会导致安全错误。

若要了解有关此 API 中使用术语的更多信息，请参阅定义部分。

有关文件和目录条目 API 的参考文档，请参阅参考登录页面及其子页面。

规范仍在定义中，可能会发生变化。

API 的实用性

• 文件和目录条目 API 是一款重要的 API，原因如下：
• 它允许应用程序拥有涉及大型二进制 blob 的离线和存储功能。
• 它可以通过让应用程序在后台预取资产并在本地缓存来提高性能。
• 它允许您的 Web 应用程序用户直接编辑他们本地文件目录中的二进制文件。

它提供了一个存储 API，您的用户已经熟悉该 API，他们习惯于使用文件系统。

文件和目录条目 API 与其他存储 API

• 文件和目录条目 API 是其他存储 API（如IndexedDB）的替代方案。对于处理 blob 的应用程序来说，该 API 是更好的选择，原因如下：
• 文件和目录条目 API 为未被数据库解决的用例提供客户端存储。如果您想要拥有大型可变数据块，那么文件和目录条目 API 比数据库更有效率的存储解决方案。
• 虽然 Firefox 支持 IndexedDB 的 blob 存储，但 Chrome 目前不支持（Chrome 仍在实现对 IndexedDB 中 blob 存储的支持）。如果您将 Chrome 作为您的应用程序的目标，并且想要存储 blob，那么文件和目录条目 API 和 App Cache 是您的唯一选择。但是，AppCache 存储不是本地可变的，也不允许进行细粒度的客户端管理。

示例用例

• 以下只是您可以使用文件和目录条目 API 的一些示例：
  • 具有持久上传器的应用程序
  • 当选择文件或目录进行上传时，您可以将该文件复制到本地沙盒中，并一次上传一个块。
• 该应用程序可以在中断后重新启动上传，例如浏览器关闭或崩溃、连接中断或计算机关闭。
  • 具有大量媒体资产的视频游戏或其他应用程序
  • 该应用程序下载一个或多个大型 tarball，并将它们在本地扩展到目录结构中。
• 该应用程序在后台预取资产，因此用户可以在等待下载时继续执行下一个任务或游戏级别。
  • 具有离线访问或本地缓存的音频或照片编辑器（非常适合提高性能和速度）
• 该应用程序可以就地写入文件（例如，仅覆盖 ID3/EXIF 标签，而不是整个文件）。
  • 离线视频播放器
  • 该应用程序可以下载大型文件（>1GB）以供日后观看。
• 该应用程序可以访问部分下载的文件（以便您即使应用程序仍在下载其余内容或由于您不得不赶火车而未完成下载，也能观看 DVD 的第一章节）。
  • 离线 Web 邮件客户端
  • 客户端下载附件并在本地存储它们。

客户端缓存附件以供日后上传。

虚拟化文件系统

该 API 不会让您访问本地文件系统，沙盒也不一定是文件系统的一部分。相反，它是一个虚拟化的文件系统，它对 Web 应用程序看起来像一个完整的成熟文件系统。它不一定与浏览器之外的本地文件系统相关联。

不同的存储类型

应用程序可以请求临时存储或持久存储。临时存储更容易获得，因为浏览器会直接为您提供它，但它有限制，当浏览器空间不足时可能会被浏览器删除。另一方面，持久存储可能会为您提供更大的空间，这些空间只能由用户删除，但它需要用户授予您权限。

存储配额

为了防止 Web 应用程序占用整个磁盘空间，浏览器可能会对每个应用程序实施配额，并在 Web 应用程序之间分配存储空间。

异步和同步版本

文件和目录条目 API 具有异步和同步版本。这两个版本的 API 提供相同的功能。事实上，它们几乎完全相同，只是存在一些差异。

WebWorkers

异步 API 可以用于文档或WebWorkers 上下文，而同步 API 只能用于 WebWorkers。

回调

异步 API 不会通过返回值来提供数据；相反，您必须传递一个回调函数。您发送请求以执行操作，并通过回调获得通知。相比之下，同步 API 不使用回调，因为 API 方法返回的值。

异步和同步 API 的全局方法

异步 API 具有以下全局方法：requestFileSystem() 和 resolveLocalFileSystemURL()。这些方法是窗口对象和工作进程全局范围的成员。另一方面，同步 API 使用以下方法：requestFileSystemSync() 和 resolveLocalFileSystemSyncURL()。这些同步方法仅是工作进程全局范围的成员，而不是窗口对象的成员。

使用异步 API 的错误回调

与其他 API 的交互

• 文件和目录条目 API 旨在与 Web 平台上的其他 API 和元素一起使用。例如，您可能会使用以下之一：
• fetch()
• 拖放 API
• WebWorkers（用于文件和目录条目 API 的同步版本）

区分大小写

文件系统 API 区分大小写，并保留大小写。

遵守同源策略

源是执行脚本的文档的 URL 的域、应用程序层协议和端口。每个源都有自己关联的文件系统集。

为了防止恶意应用程序运行有害的可执行文件，您无法在“文件和目录条目 API”的沙箱中创建可执行文件。

由于文件系统是沙盒化的，因此 Web 应用程序无法访问其他应用程序的文件。您也不能读取或写入用户硬盘驱动器上的任意文件夹（例如“我的图片”和“我的文档”）中的文件。

您无法从file://本地运行应用程序。如果您这样做，浏览器会抛出错误或应用程序会静默失败。此限制也适用于许多文件 API，包括 Blob 和 FileReader。

为了测试目的，您可以通过使用--allow-file-access-from-files标志启动浏览器来绕过 Chrome 上的限制。仅为此目的使用此标志。

本节定义并解释“文件和目录条目 API”中使用的术语。

blob

代表二进制大对象。Blob 是一组二进制数据，存储为单个对象。它是 Web 应用程序中引用二进制数据的通用方法。Blob 可以是图像或音频文件。

Blob

Blob（大写 B）是一种数据结构，它是不可变的，这意味着 Blob 引用的二进制数据不能直接修改。这使得 Blob 在传递给异步 API 时行为可预测。

持久存储

持久存储是保留在浏览器中的存储，除非用户将其清除或应用程序将其删除。

临时存储

瞬态存储可供任何 Web 应用程序使用。它是自动的，不需要请求，但浏览器可以在没有警告的情况下删除存储。

• 文件和目录条目 API
• 在 JavaScript 中读取文件 (web.dev)