说明
使用 chrome.storage
API 存储、检索和跟踪用户数据的更改。
权限
storage
如需使用 Storage API,请在扩展程序中声明 "storage"
权限
清单。例如:
{
"name": "My extension",
...
"permissions": [
"storage"
],
...
}
概念和用法
Storage API 提供了一种特定于扩展程序的方式来保留用户数据和状态。它与 Web 平台的存储 API(IndexedDB 和 Storage)类似,但旨在满足扩展程序的存储需求。以下是一些主要功能:
- 所有扩展程序上下文(包括扩展程序 Service Worker 和内容脚本)都可以访问 Storage API。
- 可序列化的 JSON 值存储为对象属性。
- Storage API 与批量读写操作异步。
- 即使用户清除缓存和浏览记录,这些数据仍会保留。
- 即使使用无痕模式拆分,系统仍会保留已存储的设置。
- 包含一个专用的只读托管存储区域,适用于企业政策。
扩展程序可以使用 Web Storage API 吗?
虽然扩展程序在某些情况下(弹出式窗口和其他 HTML 页面)可以使用 Storage
接口(可通过 window.localStorage
访问),但我们不推荐使用该接口,原因如下:
- 扩展程序 Service Worker 无法使用 Web Storage API。
- 内容脚本与托管页面共享存储空间。
- 当用户清除浏览记录后,使用 Web Storage API 保存的数据将会丢失。
如需将数据从 Web Storage API 移到 Service Worker 中的 Extensions Storage API,请执行以下操作:
- 准备一个屏幕外文档 HTML 页面和脚本文件。脚本文件应包含转换例程和
onMessage
处理程序。 - 在扩展程序 Service Worker 中,检查
chrome.storage
以获取您的数据。 - 如果找不到您的数据,请调用
createDocument()
。 - 在返回的 Promise 解析后,调用
sendMessage()
以启动转换例程。 - 在屏幕外文档的
onMessage
处理程序内,调用转换例程。
Web Storage API 在扩展程序中的工作方式也存在一些细微差别。如需了解详情,请参阅 存储和 Cookie 一文。
存储区域
Storage API 分为以下存储区域:
storage.local
- 数据会存储在本地,并会在扩展程序被移除时清除。存储空间上限为 10 MB(在 Chrome 113 及更低版本中为 5 MB),但可以通过请求
"unlimitedStorage"
权限提高上限。我们建议使用storage.local
存储更多数据。 storage.managed
- 自管式存储空间是供政策安装的扩展程序使用的只读存储空间,由系统管理员使用开发者定义的架构和企业政策进行管理。政策与选项类似,但由系统管理员(而不是用户)配置,从而能够为组织中的所有用户预先配置扩展程序。有关策略的信息,请参阅管理员文档。如需详细了解
managed
存储区域,请参阅存储区域的清单。 storage.session
- 在浏览器会话期间将数据保存在内存中。默认情况下,它不会向内容脚本公开,但可以通过设置
chrome.storage.session.setAccessLevel()
来更改此行为。存储空间上限为 10 MB(在 Chrome 111 及更低版本中为 1 MB)。storage.session
接口是我们建议为 Service Worker 推荐的几种接口之一。 storage.sync
- 如果启用了同步功能,数据会同步到用户登录的任何 Chrome 浏览器。如果停用,它的行为类似于
storage.local
。Chrome 会在浏览器离线时将数据存储在本地,并在浏览器恢复在线状态时继续同步。配额限制约为 100 KB,每项内容 8 KB。我们建议使用storage.sync
在各同步的浏览器之间保留用户设置。如果您要处理敏感用户数据,请改用storage.session
。
存储空间上限和节流限制
Storage API 具有以下使用限制:
- 存储数据通常会降低性能,而该 API 包含存储空间配额。我们建议您谨慎选择存储哪些数据,以免失去存储数据的权限。
- 存储可能需要一些时间才能完成。请确保在设计代码结构时考虑到该时间。
如需详细了解存储区域限制以及超出限制时会出现什么情况,请参阅 sync
、local
和 session
的配额信息。
使用场景
以下部分介绍了 Storage API 的常见用例。
同步响应存储更新
如需跟踪对存储空间所做的更改,请向其 onChanged
事件添加监听器。当存储空间发生任何变化时,就会触发该事件。示例代码会监听以下更改:
background.js:
chrome.storage.onChanged.addListener((changes, namespace) => {
for (let [key, { oldValue, newValue }] of Object.entries(changes)) {
console.log(
`Storage key "${key}" in namespace "${namespace}" changed.`,
`Old value was "${oldValue}", new value is "${newValue}".`
);
}
});
我们可以把这个想法做得更好。在此示例中,我们有一个选项页面,
允许用户切换“调试模式”(此处未显示实现)。选项页面会立即将新设置保存到 storage.sync
,Service Worker 会使用 storage.onChanged
尽快应用设置。
options.html:
<!-- type="module" allows you to use top level await -->
<script defer src="options.js" type="module"></script>
<form id="optionsForm">
<label for="debug">
<input type="checkbox" name="debug" id="debug">
Enable debug mode
</label>
</form>
options.js:
// In-page cache of the user's options
const options = {};
const optionsForm = document.getElementById("optionsForm");
// Immediately persist options changes
optionsForm.debug.addEventListener("change", (event) => {
options.debug = event.target.checked;
chrome.storage.sync.set({ options });
});
// Initialize the form with the user's option settings
const data = await chrome.storage.sync.get("options");
Object.assign(options, data.options);
optionsForm.debug.checked = Boolean(options.debug);
background.js:
function setDebugMode() { /* ... */ }
// Watch for changes to the user's options & apply them
chrome.storage.onChanged.addListener((changes, area) => {
if (area === 'sync' && changes.options?.newValue) {
const debugMode = Boolean(changes.options.newValue.debug);
console.log('enable debug mode?', debugMode);
setDebugMode(debugMode);
}
});
从存储空间异步预加载
由于 Service Worker 不会一直运行,因此 Manifest V3 扩展程序有时需要
在执行事件处理脚本之前,从存储空间异步加载数据。为此,
以下代码段使用异步 action.onClicked
事件处理脚本,用于等待 storageCache
全局的,以便在执行其逻辑之前填充。
background.js:
// Where we will expose all the data we retrieve from storage.sync.
const storageCache = { count: 0 };
// Asynchronously retrieve data from storage.sync, then cache it.
const initStorageCache = chrome.storage.sync.get().then((items) => {
// Copy the data retrieved from storage into storageCache.
Object.assign(storageCache, items);
});
chrome.action.onClicked.addListener(async (tab) => {
try {
await initStorageCache;
} catch (e) {
// Handle error that occurred during storage initialization.
}
// Normal action handler logic.
storageCache.count++;
storageCache.lastTabId = tab.id;
chrome.storage.sync.set(storageCache);
});
示例
以下示例展示了 local
、sync
和
session
个存储区域:
局部
chrome.storage.local.set({ key: value }).then(() => {
console.log("Value is set");
});
chrome.storage.local.get(["key"]).then((result) => {
console.log("Value is " + result.key);
});
同步
chrome.storage.sync.set({ key: value }).then(() => {
console.log("Value is set");
});
chrome.storage.sync.get(["key"]).then((result) => {
console.log("Value is " + result.key);
});
会话
chrome.storage.session.set({ key: value }).then(() => {
console.log("Value was set");
});
chrome.storage.session.get(["key"]).then((result) => {
console.log("Value is " + result.key);
});
如需查看 Storage API 的其他演示,请探索以下任一示例:
类型
AccessLevel
存储区域的访问权限级别。
枚举
"TRUSTED_CONTEXTS"
指定源自扩展程序本身的上下文。
"TRUSTED_AND_UNTRUSTED_CONTEXTS"
指定源自扩展程序外部的上下文。
StorageArea
属性
-
onChanged
事件<functionvoidvoid>
Chrome 73 及更高版本在一项或多项内容发生更改时触发。
onChanged.addListener
函数如下所示:(callback: function) => {...}
-
callback
函数
callback
参数如下所示:(changes: object) => void
-
更改
对象
-
-
-
清除
void
<ph type="x-smartling-placeholder"></ph> 承诺将所有内容从存储空间中移除。
clear
函数如下所示:(callback?: function) => {...}
-
callback
函数(可选)
callback
参数如下所示:() => void
-
返回
承诺<void>
Chrome 88 及更高版本Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
-
-
get
void
<ph type="x-smartling-placeholder"></ph> 承诺从存储空间获取一项或多项内容。
get
函数如下所示:(keys?: string | string[] | object, callback?: function) => {...}
-
密钥
string |string[] |对象(可选)
要获取的单个键、要获取的键列表或指定默认值的字典(请参阅对象说明)。空列表或对象将返回空的结果对象。传入
null
以获取存储空间的全部内容。 -
callback
函数(可选)
callback
参数如下所示:(items: object) => void
-
items
对象
所含项的键值对映射中的对象。
-
-
返回
Promise<object>
Chrome 88 及更高版本Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
-
-
getBytesInUse
void
<ph type="x-smartling-placeholder"></ph> 承诺获取一个或多个项占用的空间量(以字节为单位)。
getBytesInUse
函数如下所示:(keys?: string | string[], callback?: function) => {...}
-
密钥
string |string[] 选填
要获取其总用量的单个键或键列表。空列表将返回 0。传入
null
可获取所有存储空间的总用量。 -
callback
函数(可选)
callback
参数如下所示:(bytesInUse: number) => void
-
bytesInUse
number
存储空间正在使用的存储空间大小(以字节为单位)。
-
-
返回
Promise<number>
Chrome 88 及更高版本Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
-
-
移除
void
<ph type="x-smartling-placeholder"></ph> 承诺从存储空间中移除一项或多项内容。
remove
函数如下所示:(keys: string | string[], callback?: function) => {...}
-
密钥
string |字符串 []
要移除的项的单个键或键列表。
-
callback
函数(可选)
callback
参数如下所示:() => void
-
返回
承诺<void>
Chrome 88 及更高版本Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
-
-
set
void
<ph type="x-smartling-placeholder"></ph> 承诺设置多项。
set
函数如下所示:(items: object, callback?: function) => {...}
-
items
对象
提供每个键值对以更新存储空间的对象。存储空间中的任何其他键值对都不会受到影响。
数字等基元值将按预期进行序列化。具有
typeof
"object"
和"function"
的值通常会序列化为{}
,但Array
(按预期序列化)、Date
和Regex
(使用其String
表示法序列化)。 -
callback
函数(可选)
callback
参数如下所示:() => void
-
返回
承诺<void>
Chrome 88 及更高版本Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
-
-
setAccessLevel
void
<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 102 及更高版本为存储区域设置所需的访问权限级别。默认为仅限可信上下文。
setAccessLevel
函数如下所示:(accessOptions: object, callback?: function) => {...}
-
accessOptions
对象
-
accessLevel
存储区域的访问权限级别。
-
-
callback
函数(可选)
callback
参数如下所示:() => void
-
返回
承诺<void>
Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
-
StorageChange
属性
-
newValue
任何选填字段
商品的新值(如果有新值)。
-
oldValue
任何选填字段
商品的旧值(如果有旧值)。
属性
local
local
存储区域中的项是每台机器的本地项。
类型
StorageArea 和对象
属性
-
QUOTA_BYTES
10485760
可在本地存储空间中存储的数据的最大数量(以字节为单位),测量方式是将每个值加上每个键的长度进行 JSON 字符串化。如果扩展程序具有
unlimitedStorage
权限,系统会忽略此值。会导致超出此限制的更新会立即失败,并在使用回调时设置runtime.lastError
;如果使用 async/await,设置被拒的 Promise。
managed
managed
存储区域中的内容由网域管理员配置的企业政策设置,对扩展程序而言是只读的;尝试修改此命名空间会导致错误。如需了解如何配置政策,请参阅存储区域的清单。
类型
session
session
存储区域中的内容存储在内存中,不会持久保留在磁盘中。
类型
StorageArea 和对象
属性
-
QUOTA_BYTES
10485760
可在内存中存储的数据量上限(以字节为单位),通过估算每个值和键的动态分配内存使用量来衡量。在使用回调或 Promise 被拒绝时,会导致超出此限制的更新会立即失败,并设置
runtime.lastError
。
sync
sync
存储区域中的内容会通过 Chrome 同步功能进行同步。
类型
StorageArea 和对象
属性
-
MAX_ITEMS
512
同步存储空间中可存储的内容数量上限。在使用回调或 Promise 被拒绝时,会导致超出此限制的更新将立即失败,并设置
runtime.lastError
。 -
MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE
100 万
<ph type="x-smartling-placeholder"></ph> 已弃用storage.sync API 不再有持续写入操作配额。
-
MAX_WRITE_OPERATIONS_PER_HOUR
1800
每小时可执行的
set
、remove
或clear
操作次数上限。此值为每 2 秒 1 次,该上限比短期内的每分钟写入次数上限更低。在使用回调或 Promise 被拒绝时,会导致超出此限制的更新会立即失败,并设置
runtime.lastError
。 -
MAX_WRITE_OPERATIONS_PER_MINUTE
120
每分钟可执行的
set
、remove
或clear
操作数量上限。即每秒 2 次,在较短的时间内提供的吞吐量高于每小时写入次数。在使用回调或 Promise 被拒绝时,会导致超出此限制的更新会立即失败,并设置
runtime.lastError
。 -
QUOTA_BYTES
102400
同步存储空间中可存储的数据总量(字节),通过对每个值加上每个键的长度进行 JSON 字符串化来衡量。在使用回调或 Promise 被拒绝时,会导致超出此限制的更新会立即失败,并设置
runtime.lastError
。 -
QUOTA_BYTES_PER_ITEM
8192
同步存储空间中每一项的最大大小(以字节为单位),测量方式是将相应内容的值加其键长度的 JSON 字符串化。当使用回调或 Promise 被拒绝时,包含超过此限制的项的更新将立即失败,并设置
runtime.lastError
。
事件
onChanged
chrome.storage.onChanged.addListener(
callback: function,
)
在一项或多项内容发生更改时触发。
参数
-
callback
函数
callback
参数如下所示:(changes: object, areaName: string) => void
-
更改
对象
-
areaName
字符串
-