LocalFileSystem - 用于访问沙盒文件系统

LocalFileSystem 是文件系统 API 的接口，可以用于访问沙盒文件系统。这些方法由 window 和 worker 对象实现。

基本概念

本节包括这些方法的一些关键概念。

创建新存储

您可以通过调用 window.requestFileSystem() 来访问沙盒文件系统。成功回调的参数是 FileSystem 对象，它有两个属性：文件系统的名称和根。

如果要创建两个文件系统，可以多次调用该方法：一个是临时文件系统，另一个是持久文件系统。（要了解有关存储类型的更多信息，请参阅基本概念文章。）在大多数情况下，您只需要创建一个文件系统，但在少数情况下，创建第二个可能很有用。例如，如果您要创建邮件应用程序，则可以创建用于缓存资源（如图像和附件）的临时存储来加快性能，同时为唯一数据创建持久存储，例如脱机时编写的电子邮件草稿 - 这样在备份到云之前不会丢失记录。

使用持久存储

requestFileSystem() 方法允许你请求PERSISTENT 或 TEMPORARY存储。持久存储是指保留在浏览器中的存储，除非应用程序或用户将其删除，但用户必须先授予您权限才能使用它。相反，临时存储在没有任何用户权限的情况下自动授予，但浏览器可以随时清除它。

要使用文件系统 API 的 PERSISTENT 存储，可以通过 Chrome 公开的 requestQuota API 申请。因此，要请求存储，您需要执行以下操作：

var requestedBytes = 1024*1024*10; // 10MB

navigator.webkitPersistentStorage.requestQuota (
    requestedBytes, function(grantedBytes) {  
        window.requestFileSystem(PERSISTENT, grantedBytes, onInitFs, errorHandler);
    }, function(e) { console.log('错误', e); }
);

在您的应用可以使用永久存储之前，您的用户必须授予您的应用在本地存储数据的权限。一旦您的用户授予它，您就不需要再次调用 requestQuota() 。随后的调用都是无用的。

另一个 API，即配额管理 API，允许您使用 window.webkitPersistentStorage.queryUsageAndQuota() 查询原始的当前配额使用和分配。要了解更多信息，请参阅这个 StackOverflow 回答。（管理 HTML5 离线存储中介绍了旧版本的 API。）

在单个源中使用

文件系统被沙箱化为单个源。这意味着您的应用无法读取或写入其他应用文件的文件。您的应用无法访问用户硬盘上任意文件夹（例如 “我的图片”，“我的文档”）中的文件。有关限制的详细信息，请参阅基本概念文章。

实例

以下是显示如何请求文件系统存储的代码段。

// 处理特定于浏览器的前缀
window.requestFileSystem  = window.requestFileSystem || window.webkitRequestFileSystem;

// 第一个参数定义存储类型：持久性或临时性
// 接下来，设置所需空间的大小（以字节为单位）
// initFs 是成功的回调
// 最后一个是错误回调，用于拒绝访问和其他错误。
window.requestFileSystem(window.PERSISTENT, 1024*1024,onInitFs,errorHandler);

方法预览

• void requestFileSystem (in unsigned short type, in unsigned long long size, in FileSystemCallback successCallback, in optional ErrorCallback errorCallback);
• void resolveLocalFileSystemURL (in DOMString url, in EntryCallback successCallback, in optional ErrorCallback errorCallback);

常量

常量	值	描述
TEMPORARY	0	可由浏览器自行决定删除的瞬态存储。
PERSISTENT	1	除非用户或应用程序将其清除，否则将保留在浏览器中的存储。在应用程序使用此类存储之前，用户必须授予权限。

方法

requestFileSystem()

请求应存储数据的文件系统。您可以通过使用此全局方法 window.requestFileSystem() 请求 LocalFileSystem 对象来访问沙盒文件系统。

void requestFileSystem(
  in unsigned short type, 
  in unsigned long long size, 
  in FileSystemCallback successCallback, 
  in ErrorCallback errorCallback
);

参数

type

文件系统的存储类型。值可以是 TEMPORARY 或 PERSISTENT。

size

应用程序所需的存储空间（以字节为单位）。

successCallback

浏览器提供文件系统时调用的成功回调。它的参数是 FileSystem 对象，它有两个属性：

• name - 浏览器为文件系统分配的唯一名称。
• root - 表示文件系统根目录的只读 DirectoryEntry 对象。

opt_errorCallback

发生错误或拒绝获取文件系统的请求时调用的错误回调。它的参数是 FileError 对象。

返回

void

异常

此方法可以使用以下代码引发 FileError：

异常	描述
SECURITY_ERROR	应用程序无权访问文件系统接口。例如，您无法从 file:// 运行。有关更多详细信息，请参阅基本概念文章。

resolveLocalFileSystemURL()

允许您查找具有本地 URL 的文件或目录的条目。

void resolveLocalFileSystemURL(
  in DOMString url, 
  in EntryCallback successCallback, 
  in optional ErrorCallback errorCallback
);

参数

url

文件系统中本地文件的 URL。

successCallback

浏览器为提供的 URL 提供文件或目录时调用的成功回调。

errorCallback

发生错误或拒绝获取条目对象的请求时调用的错误回调。

返回

void

异常

此方法可以使用以下代码引发 FileError：

异常	描述
ENCODING_ERR	URL 的语法无效。
NOT_FOUND_ERR	URL 在结构上是正确的，但是指的是不存在的资源。
SECURITY_ERR	应用程序无权访问文件系统接口。

桌面浏览器兼容性

移动浏览器兼容性

相关链接

规范：文件 API：目录和系统规范WD

参考：文件系统 API

介绍：关于文件系统 API 的基本概念