Chrome Apps Filesystem API 存储示例：配额申请、用量查询与文件写入实战解析（chrome-extensions-samples 存档示例）

• 示例工程

本篇技术指南以 chrome-extensions-samples 仓库存档目录_archive/apps/samples/storage下的 "Storage simple test" 示例为主体，完整讲解 Chrome Apps（Manifest V2 时代）中如何基于 WebKit 前缀的 Filesystem API 申请持久化配额、查询配额用量，以及向文件系统写入大体积测试文件。读完本文，你将掌握webkitStorageInfo.requestQuota、webkitStorageInfo.queryUsageAndQuota、webkitRequestFileSystem与FileWriter的完整调用链，并能在实际 Chrome App 中复刻这套存储测试方案。

示例概览：一个极简的存储测试应用

_archive/apps/samples/storage是一个"非常简单的基础应用"（原文档原文为 "A very basic application"），其核心目的是验证 Chrome Apps 的文件系统能力：允许你请求一个文件系统（request a filesystem）、向其写入一个示例文件（write a sample file），并查询当前可用字节数（query how many bytes are available）。

整个示例只由 5 个文件构成：

原文档将其归类为 Filesystem、Runtime、Window 三类 API 的演示：Runtime（chrome.app.runtime.onLaunched）负责接收启动事件，Window（chrome.app.window.create）负责创建应用窗口，Filesystem 则是本次演示的主角。

清单文件：unlimitedStorage 权限的作用

在 manifest.json 中，应用声明了唯一一项权限unlimitedStorage：

{ "name": "Syncable Storage Sample", "version": "1.1", "manifest_version": 2, "minimum_chrome_version": "23", "app": { "background": { "scripts": ["background.js"] } }, "permissions": [ "unlimitedStorage" ] }

几个值得注意的细节：

• manifest_version: 2与minimum_chrome_version: "23"：这是一个面向 Chrome 23+ 的 Manifest V2 Chrome 应用（Chrome App）。示例存放于_archive目录，属于已归档的旧形态扩展/应用项目，运行前提是当时支持 WebKit 前缀存储 API 的 Chrome 版本。
• unlimitedStorage权限：这是本示例的关键权限。它解除了 Chrome 对本地数据存储的默认配额限制。有了它，webkitStorageInfo.requestQuota的请求才可能被授予远超默认上限的持久化空间。在截图日志中可以看到Granted 31457280（即 30 MB），这正是代码中BIG_FILE所请求的字节数。
• 后台脚本作为应用入口：app.background.scripts声明了background.js，Chrome 应用在启动时执行该脚本，随后通过 Runtime/Window API 创建可见窗口。

应用入口：background.js 的窗口创建流程

background.js 展示了 Chrome App 最基础的启动模式：

chrome.app.runtime.onLaunched.addListener(function() { chrome.app.window.create('main.html', { id: "mainwin", innerBounds: { 'width': 400, 'height': 500 } }); });

• chrome.app.runtime.onLaunched：应用被启动时触发的运行时事件（对应原文档列出的 Runtime API）。
• chrome.app.window.create('main.html', ...)：以main.html为内容创建应用窗口（对应原文档列出的 Window API），并指定窗口id为mainwin、内部尺寸 400×500。

核心逻辑逐行解析：main.js 的三段式存储测试

main.js 是全部技术精髓所在。它先在文件顶部定义一个"大文件"基准值：

var BIG_FILE = 30 * 1024 * 1024; // 30 MB

BIG_FILE同时被用作配额申请量与待写入文件的目标大小，全示例围绕这 30 MB 展开。随后在onload中为 main.html 的三个按钮绑定了三个处理函数，日志统一输出到<pre id="log">区域：

1. 申请配额：webkitStorageInfo.requestQuota

document.getElementById('request-quota').onclick = function() { window.webkitStorageInfo.requestQuota( window.PERSISTENT, BIG_FILE, function(grantedBytes) { log('Granted ' + grantedBytes) }, function(e) { log('Error: ' + e); }); };

• 存储类型：传入window.PERSISTENT，表示申请持久化存储（PERSISTENT与TEMPORARY是 WebKit 存储的两种类型，前者需显式申请配额且数据不会被浏览器自动回收，后者则由浏览器按需逐出）。
• 请求字节数：BIG_FILE，即 30 MB。
• 成功回调：返回实际被授予的字节数grantedBytes。在示例截图中可以看到输出Granted 31457280，恰好等于申请的 30 MB，说明在unlimitedStorage权限下配额被足额批准。
• 失败回调：打印错误对象。

2. 查询配额与用量：webkitStorageInfo.queryUsageAndQuota

document.getElementById('query-quota').onclick = function() { window.webkitStorageInfo.queryUsageAndQuota( window.PERSISTENT, function(usage, quota) { log('usage ' + usage + ' quota ' + quota) }, function(e) { log('Error: ' + e); }); };

• 同样针对PERSISTENT存储类型查询。
• 成功回调返回两个参数：usage（已使用字节数）与quota（配额字节数）。在截图中，写入测试文件之前的查询输出为usage 0 quota 351988776960——用量为 0，而配额高达约 351 GB（约 327 GB），这是unlimitedStorage生效后的实际配额上限。

3. 申请文件系统并写入文件：webkitRequestFileSystem + FileWriter

这是示例中最复杂的部分，完整展示了"申请文件系统 → 创建文件 → 创建写入器 → 写入大文件"的完整链路：

document.getElementById('request-filesystem').onclick = function() { window.webkitRequestFileSystem( PERSISTENT, BIG_FILE, function(fs) { log('Filesystem: ' + fs); fs.root.getFile( 'test.txt', {create: true, exclusive: true}, function(fileEntry) { log('fileEntry: ' + fileEntry); fileEntry.createWriter(function(fileWriter) { log('fileWriter: ' + fileWriter); fileWriter.onwriteend = function(e) { log('Write completed.'); }; fileWriter.onerror = function(e) { log('Write failed: ' + e.toString()); }; var bb = new WebKitBlobBuilder(); for (var i = 0; i < BIG_FILE/50; i++) { bb.append('01234567890123456789012345678901234567890123456789'); } fileWriter.write(bb.getBlob('text/plain')); }, function(e) { log('Error: ' + e); }); }); }, function(e) {log('Error' + e);}); };

逐步拆解这条调用链：

1. window.webkitRequestFileSystem(PERSISTENT, BIG_FILE, successCallback, errorCallback)：申请一个持久化文件系统。第二个参数BIG_FILE是希望分配的空间大小；成功回调收到DOMFileSystem对象fs（截图日志中显示为[object DOMFileSystem]）。
2. fs.root.getFile('test.txt', {create: true, exclusive: true}, ...)：在文件系统根目录创建文件test.txt。create: true表示不存在时创建，exclusive: true表示文件已存在则报错（避免覆盖）。成功回调收到FileEntry（截图日志中显示为[object FileEntry]）。
3. fileEntry.createWriter(...)：为文件创建写入器FileWriter（截图日志中显示为[object FileWriter]），并注册两个事件：
   • onwriteend：写入完成后输出Write completed.；
   • onerror：写入失败时输出错误信息。
4. 构造 Blob 并写入：使用WebKitBlobBuilder将BIG_FILE/50次拼接的 50 字节字符串组装成约 30 MB 的 Blob，然后调用fileWriter.write(bb.getBlob('text/plain'))一次性写入。注意源码中的注释提示：在 Chrome 12 中应使用window.WebKitBlobBuilder，这体现了该示例对早期 Chrome 版本兼容性的考虑。

写入完成后再次点击 "Query Quota"，queryUsageAndQuota即可反映文件占用（截图日志中可见写入后usage 162等输出变化），从而完成"写入—校验"的闭环验证。

界面层：main.html 的按钮与日志输出

main.html 结构极其精简：

<button id="request-quota">Request Quota</button> <button id="query-quota">Query Quota</button> <button id="request-filesystem">Request FileSystem and write file</button> <pre id="log"></pre>

三个按钮的id与 main.js 中的getElementById一一对应，日志通过log()函数以追加方式写入<pre>元素：

function log(message) { document.getElementById('log').textContent += message + '\n'; }

扩展观察：同目录下的姊妹示例与存储 API 家族

在_archive/apps/samples目录下还有与存储相关的姊妹示例，可作为本主题的延伸阅读：

• syncfs-editor（_archive/apps/samples/syncfs-editor/README.md）：一个基于chrome.syncFileSystemAPI 的云备份文本编辑器，展示文件系统数据与云端同步的能力，与本文示例的本地持久化存储形成互补。
• storage 的 MV2 扩展形态：在_archive/mv2/api/storage/stylizr/中可看到面向普通扩展的chrome.storage用法（基于 JSON 的键值存储），与本文基于 File System 的二进制文件存储属于不同层级——前者适合配置与轻量数据，后者适合大文件读写。

历史定位与适用前提

需要说明的是，本示例存放于_archive归档目录，其技术栈（webkitStorageInfo、webkitRequestFileSystem、WebKitBlobBuilder等 WebKit 前缀 API 以及 Chrome App 形态）属于 Manifest V2 时代的能力。从仓库结构可以推断，当前仓库的活跃示例（api-samples/、functional-samples/等目录）已转向 Manifest V3 与新一代 Web 平台 API（如 File System Access API、chrome.storage）。因此，本文内容适合以下场景：理解 Chrome Apps 存储架构的历史实现、维护存量 Chrome App 代码，或研究 Web 存储配额模型的设计演进。在实际新项目中，应优先选用当前受支持的存储方案。

小结

_archive/apps/samples/storage用不到 60 行 JavaScript 完整演示了 Chrome Apps 文件系统的三大核心能力：配额申请（webkitStorageInfo.requestQuota）、配额/用量查询（webkitStorageInfo.queryUsageAndQuota）与文件系统写入（webkitRequestFileSystem→FileEntry.createWriter→FileWriter.write）。配合unlimitedStorage权限，示例在截图中呈现了"申请 30 MB → 获得足额授权 → 查询超大配额 → 写入 30 MB 测试文件"的完整可验证流程。对于想要回顾 Chrome App 存储机制、或为存量应用编写存储自检工具的开发者而言，这是一个麻雀虽小、五脏俱全的参考实现。

• 示例工程