跳转到内容

能力中的 API

Storage Buckets API

发布于 更新于

有限可用不支持的浏览器: Firefox (Desktop)、Safari (macOS)WICG 草案

navigator.storageBuckets.open(name, options) 按名称创建或打开存储桶,把同一源的存储空间分成多个分区。各桶分别管理 indexedDB 工厂、caches、桶级文件系统、持久化模式、配额上限和过期时间。存储紧张时,浏览器可以清除低价值的桶,保留已持久化的桶。不使用存储桶 API 时,一个源只有默认桶,数据只能整体保留或整体逐出。

Chrome 122 与 Edge 122 一并提供了 StorageBucketManager 和 StorageBucket 的全部成员(indexedDB、caches、getDirectory()、persist()、estimate()、setExpires());Android 版 Chrome、Samsung Internet 与 Android WebView 镜像该版本。Firefox 尚未实现(Bugzilla 1594740),Safari 没有实现(BCD api.StorageBucketManager)。可以在支持存储桶的 Chrome 中使用 bucket.indexedDB,其他浏览器回退到 window.indexedDB,两者共用同一套 schema 代码。

navigator.storageBuckets.open(name)
navigator.storageBuckets.open(name, options)
navigator.storageBuckets.keys()
navigator.storageBuckets.delete(name)
bucket.persist()
bucket.persisted()
bucket.estimate()
bucket.setExpires(timestamp)
bucket.expires()
bucket.getDirectory()

open() 返回 Promise<StorageBucket>,keys() 返回存活桶名的 Promise<sequence<DOMString>>,delete() 返回 Promise<undefined>,即使不存在同名桶也会兑现。navigator.storageBuckets 带 [SecureContext],暴露在 Window 与 worker 上;persist() 仅限 Window,因为它可能要查询 persistent-storage 权限。indexedDB 与 caches 属性是作用域限定在桶内的普通 IDBFactory 与 CacheStorage 对象,getDirectory() 返回桶级源私有文件系统的 FileSystemDirectoryHandle。

open() 接受一个桶名和一个可选的 StorageBucketOptions 字典。桶名必须是 1 到 64 个码点的 ASCII 小写字母、数字、_ 或 -,且不能以 _ 或 - 开头;打开已存在的名称会返回已有的桶并忽略 options。

成员 类型 必填 说明
persisted boolean 否,默认 false 请求 "persistent" 桶模式。只有 persistent-storage 权限为 "granted" 时才会生效;否则桶以尽力而为模式打开,bucket.persisted() 兑现为 false。
quota unsigned long long(字节) 否 桶用量的上限;浏览器可以施加更低的限制。设置后 bucket.estimate() 把它作为 quota 报告。
expires DOMHighResTimeStamp(自 Unix 纪元起的毫秒数) 否 桶被视为已消失的时间点。过期的桶在下一次 open()、keys() 或访问时被惰性移除。

Chromium 的 IDL 还带有一个 durability 成员("strict" 或 "relaxed"),位于 StorageBucketsDurability 运行时标志之后;WICG explainer 已把它从 API 的第一版中移除,因为 IndexedDB 事务本身就暴露同样的 durability 选项,所以不要依赖它。

open() 返回的 StorageBucket 有以下成员。

成员 类型 说明
name DOMString(只读) 打开桶时使用的键。
persist() Promise<boolean> persistent-storage 权限已授予时升级为 "persistent" 模式;以结果模式兑现。
persisted() Promise<boolean> 桶处于 "persistent" 模式时为 true。
estimate() Promise<StorageEstimate> 仅此桶的 usage 与 quota,不同于覆盖整个源的 navigator.storage.estimate()。
setExpires(ms) / expires() Promise<undefined> / Promise<DOMHighResTimeStamp?> 设置或读取过期时间;未设置时 expires() 兑现为 null。
indexedDB、caches、getDirectory() IDBFactory、CacheStorage、Promise<FileSystemDirectoryHandle> 桶级的存储端点。

open()、keys() 与 delete() 出错时会拒绝 Promise。不过,整个 API 在当前上下文中不可用时,Chromium 会同步抛出 SecurityError。

异常 方法 条件
TypeError open()、keys()、delete()、estimate() 无法获得 storage shelf(opaque origin、存储被禁用);open() 还会因桶名无效、expires 早于当前时间、quota 小于等于零而拒绝。
InvalidCharacterError delete() 规范规定的桶名无效情形。Chromium 在这里改以 TypeError 拒绝(见下方说明)。
InvalidStateError persist()、persisted()、estimate()、setExpires()、expires() 桶的 removed 标志已置位:你拿到句柄之后它被删除或已过期。
QuotaExceededError open() Chromium 特有:该源创建的桶数量超过实现允许的上限(Too many buckets created.)。
UnknownError open()、keys()、delete() Chromium 特有:存储后端失败(Unknown error occured while creating a bucket.,拼写错误是 Chromium 原文)。
SecurityError 任一方法(同步抛出) Chromium 在此上下文中拒绝该 API,例如 opaque origin:Access to Storage Buckets API is denied in this context.

先选定存储端点,再运行应用代码。Firefox 和 Safari 可以回退到源的默认存储,继续使用同一套代码。

把草稿放进持久化桶,缺少支持时回退到默认 IndexedDB

链接到“把草稿放进持久化桶,缺少支持时回退到默认 IndexedDB”一节

草稿需要优先保留,因此存入申请 persisted: true 的桶。浏览器没有 navigator.storageBuckets 时,就用 window.indexedDB 打开同一个数据库。如果浏览器拒绝持久化请求,代码会提示数据仍有丢失风险。

function openDatabase(factory, name, version) {
return new Promise((resolve, reject) => {
const request = factory.open(name, version);
request.onupgradeneeded = () => request.result.createObjectStore('drafts', { keyPath: 'id' });
request.onsuccess = () => resolve(request.result);
request.onerror = () => reject(request.error);
});
}
async function openDraftsDatabase() {
if (!('storageBuckets' in navigator)) {
return { db: await openDatabase(indexedDB, 'drafts', 1), persisted: false };
}
const bucket = await navigator.storageBuckets.open('drafts', { persisted: true });
return {
db: await openDatabase(bucket.indexedDB, 'drafts', 1),
persisted: await bucket.persisted(), // persistent-storage 授予前为 false
};
}
const { db, persisted } = await openDraftsDatabase();
if (!persisted) {
document.querySelector('#storage-note').textContent =
'草稿以尽力而为方式保存,存储紧张时可能被清除。';
}

在全新的 Chrome 配置文件中 persisted 会返回 false,因为 persistent-storage 尚未授予;先在用户手势中调用 navigator.storage.persist() 才会改变这一结果。

资讯缓存供离线阅读,保留一周后即可丢弃。给桶设置 expires 时间戳,浏览器就能自动清除,无需另写清理任务。回退分支把响应存入默认 caches,按记录的日期清理。

const WEEK = 7 * 24 * 60 * 60 * 1000;
async function feedCache() {
if ('storageBuckets' in navigator) {
const bucket = await navigator.storageBuckets.open('feed', { expires: Date.now() + WEEK });
return bucket.caches.open('articles');
}
const cache = await caches.open('articles');
const stamp = await cache.match('/__cached-at');
if (stamp && Date.now() - Number(await stamp.text()) > WEEK) {
await caches.delete('articles');
return caches.open('articles');
}
if (!stamp) await cache.put('/__cached-at', new Response(String(Date.now())));
return cache;
}
const cache = await feedCache();
await cache.add('/api/feed?page=1');

打开已存在的桶不会刷新它的过期时间,所以长期使用的资讯桶需要在每次成功同步后调用 bucket.setExpires(Date.now() + WEEK) 把期限持续后推。

规范

规范状态
Storage Buckets(存储分桶)WICG 草案
Storage Buckets API: open() methodWICG 草案
Storage Buckets API: the StorageBucket interfaceWICG 草案
  • 图例
  • 支持
  • 部分支持
  • 需开启标志
  • 不支持
  • 未知
浏览器 / 平台支持版本置信度来源备注
Chrome (Desktop)#支持122低来源12
Chrome (Android)#支持122低来源3
Edge (Desktop)#支持122低来源4
Firefox (Desktop)#不支持—低来源5
Safari (macOS)#不支持—低来源6
  1. 依据 MDN browser-compat-data,StorageBucketManager(navigator.storageBuckets)在 Chrome 122 中发布。
  2. 该条目尚无 MDN 说明页;依据 caniuse 上该特性的各浏览器支持表核对。
  3. 依据 MDN browser-compat-data,镜像桌面版 Chrome 的支持情况。
  4. 依据 MDN browser-compat-data,镜像 Chromium 的支持情况。
  5. 未实现;依据 MDN browser-compat-data,作为未关闭的 Firefox bug 跟踪中。
  6. 依据 MDN browser-compat-data,未实现。

源数据: /compatibility/storage-buckets.json · 全球使用占比: 72 % (StatCounter 2026-09, CC BY-SA 4.0)

来源: 规范 · 最近核验 2026-09-04 · 置信度: 低 (由来源计算)