在写这篇文章时,只有 GoogleChrome 浏览器可以实施此FileSystemAPI。目前尚不存在专门用于文件/配额管理的浏览器用户界面。
要在用户的系统上存储数据,您的应用可能需要请求配额。不过,可使用--unlimited-quota-for-files
标记运行Chrome浏览器进行测试。
此外,如果您要开发的是用于Chrome网上应用店的应用或扩展程序,可使用unlimitedStorage
清单文件权限,而无需请求配额。
最后,用户会收到授予、拒绝或为应用增加存储的权限对话框。
如果您要通过 file://
调试您的应用,可能需要--allow-file-access-from-files
标记。不使用这些标记会导致SECURITY_ERR
或QUOTA_EXCEEDED_ERR
FileError。
请求文件系统
网络应用可通过调用 window.requestFileSystem()
请求对沙盒文件系统的访问权限:
- // Note: The file system has been prefixed as of Google Chrome 12:
- window.requestFileSystem = window.requestFileSystem || window.webkitRequestFileSystem;
- window.requestFileSystem(type, size, successCallback, opt_errorCallback)
- type
- 文件存储是否应该是持久的。可能的值包括
window.TEMPORARY
和window.PERSISTENT
。 - 通过
TEMPORARY
存储的数据可由浏览器自行决定删除(例如在需要更多空间的情况下)。要清除PERSISTENT
存储,必须获得用户或应用的明确授权, - 并且需要用户向您的应用授予配额。请参阅请求配额。
- size
- 应用需要用于存储的大小(以字节为单位)。
- successCallback
- 文件系统请求成功时调用的回调。其参数为
FileSystem
对象。 - opt_errorCallback
- 用于处理错误或获取文件系统的请求遭到拒绝时可选的回调。其参数为
FileError
对象。
如果您是首次调用requestFileSystem()
,系统会为您的应用创建新的存储。请注意,这是沙箱文件系统,也就是说,
一个网络应用无法访问另一个应用的文件。这也意味着您无法在用户硬盘上的任意文件夹(例如“我的图片”、“我的文档”等)中读/写文件。
用法示例:
function onInitFs(fs) {
console.log('Opened file system: ' + fs.name);
}
window.requestFileSystem(window.TEMPORARY, 5*1024*1024 /*5MB*/, onInitFs, errorHandler);
FileSystem 规范还定义了计划用于WebWorkers的同步API(LocalFileSystemSync
)接口。不过,本教程不涉及该同步API。
在本文档的其余部分中,我们将使用相同的处理程序处理异步调用引发的错误:
- function errorHandler(e) {
- var msg = '';
- switch (e.code) {
- case FileError.QUOTA_EXCEEDED_ERR:
- msg = 'QUOTA_EXCEEDED_ERR';
- break;
- case FileError.NOT_FOUND_ERR:
- msg = 'NOT_FOUND_ERR';
- break;
- case FileError.SECURITY_ERR:
- msg = 'SECURITY_ERR';
- break;
- case FileError.INVALID_MODIFICATION_ERR:
- msg = 'INVALID_MODIFICATION_ERR';
- break;
- case FileError.INVALID_STATE_ERR:
- msg = 'INVALID_STATE_ERR';
- break;
- default:
- msg = 'Unknown Error';
- break;
- };
- console.log('Error: ' + msg);
- }
当然,这种错误回调非常通用,能让您充分理解,但您提供给用户的应是易于一般人理解的讯息。请求存储配额要使用 PERSISTENT 存储,
您必须向用户取得存储持久数据的许可。由于浏览器可自行决定删除临时存储的数据,因此这一限制不适用于 TEMPORARY 存储。为了将 PERSISTENT 存储与 FileSystem API 配合使用,
Chrome 浏览器使用基于 window.webkitStorageInfo 的新 API 以请求存储:
- window.webkitStorageInfo.requestQuota(PERSISTENT, 1024*1024, function(grantedBytes) {
- window.requestFileSystem(PERSISTENT, grantedBytes, onInitFs, errorHandler);
- }, function(e) {
- console.log('Error', e);
- });
用户授予许可后,就不必再调用 requestQuota()
了。后续调用为无操作指令。
您还可以使用 API 查询源的当前配额使用情况和分配情况:window.webkitStorageInfo.queryUsageAndQuota()
使用文件沙盒环境中的文件通过 FileEntry
接口表示。
FileEntry 包含标准文件系统中会有的属性类型(name
、isFile
...)和方法(remove
、moveTo
、copyTo
...)。FileEntry
的属性和方法:
- fileEntry.isFile === true
- fileEntry.isDirectory === false
- fileEntry.name
- fileEntry.fullPath
- ...
- fileEntry.getMetadata(successCallback, opt_errorCallback);
- fileEntry.remove(successCallback, opt_errorCallback);
- fileEntry.moveTo(dirEntry, opt_newName, opt_successCallback, opt_errorCallback);
- fileEntry.copyTo(dirEntry, opt_newName, opt_successCallback, opt_errorCallback);
- fileEntry.getParent(successCallback, opt_errorCallback);
- fileEntry.toURL(opt_mimeType);
- fileEntry.file(successCallback, opt_errorCallback);
- fileEntry.createWriter(successCallback, opt_errorCallback);
- ...