说明
使用 chrome.storage
API 存储、检索和跟踪用户数据的更改。
权限
storage
概览
Storage API 提供了一种特定于扩展程序的方式来保留用户数据和状态。它与 Web 平台的存储 API(IndexedDB 和 Storage)类似,但旨在满足扩展程序的存储需求。以下是一些主要功能:
- 所有扩展程序上下文(包括扩展程序 Service Worker 和内容脚本)都可以访问 Storage API。
- 可序列化的 JSON 值存储为对象属性。
- Storage API 与批量读写操作异步。
- 即使用户清除缓存和浏览记录,这些数据仍会保留。
- 即使使用无痕模式拆分,系统仍会保留已存储的设置。
- 包含一个专用的只读托管存储区域,适用于企业政策。
尽管扩展程序在某些情况下(弹出式窗口和其他 HTML 页面)可以使用 [Storage
][mdn-storage] 接口(可通过 window.localStorage
访问),但我们不建议您这样做,原因如下:
- 扩展程序的 Service Worker 无法访问
Storage
。 - 内容脚本与托管页面共享存储空间。
- 当用户清除浏览记录后,使用
Storage
界面保存的数据将会丢失。
如需将数据从 Web Storage API 移到 Service Worker 中的 Extensions Storage API,请执行以下操作:
- 使用转换例程和 [
onMessage
][on-message] 处理程序创建屏幕外文档。 - 向屏幕外文档添加转化例程。
- 在扩展程序 Service Worker 中,检查
chrome.storage
以获取您的数据。 - 如果未找到您的数据,请 [创建][create-offscreen] 一个屏幕外文档,然后调用 [
sendMessage()
][send-message] 以启动转换例程。 - 在屏幕外文档的
onMessage
处理程序内,调用转换例程。
Web Storage API 在扩展程序中的工作方式也存在一些细微差别。如需了解详情,请参阅 [存储和 Cookie][storage-and-cookies] 一文。
存储区域
Storage API 分为以下四个存储分区(“存储区域”):
storage.local
- 数据会存储在本地,当扩展程序被移除时,系统会清除这些数据。配额限制约为 10 MB,但可通过请求
"unlimitedStorage"
权限提高。请考虑使用它来存储大量数据。 。
storage.sync
- 如果启用了同步功能,数据会同步到用户登录的任何 Chrome 浏览器。如果停用,它的行为类似于
storage.local
。Chrome 会在浏览器离线时将数据存储在本地,并在浏览器恢复在线状态时继续同步。配额限制约为 100 KB,每项内容 8 KB。您可以考虑使用此功能,在各已同步的浏览器之间保留用户设置。 。
- storage.session
- 在浏览器会话期间将数据保存在内存中。默认情况下,它不会向内容脚本公开,但可以通过设置
chrome.storage.session.setAccessLevel()
来更改此行为。配额限制约为 10 MB。考虑使用它在 Service Worker 的运行期间存储全局变量。 。
- storage.managed
- 管理员可以使用架构和企业政策在受管环境中配置支持的扩展程序设置。此存储区域为只读。
清单
如需使用 Storage API,请在扩展程序中声明 "storage"
权限
清单。例如:
{
"name": "My extension",
...
"permissions": [
"storage"
],
...
}
用法
以下示例展示了 local
、sync
和
session
个存储区域:
storage.local
chrome.storage.local.set({ key: value }).then(() => {
console.log("Value is set");
});
chrome.storage.local.get(["key"]).then((result) => {
console.log("Value currently is " + result.key);
});
storage.sync
chrome.storage.sync.set({ key: value }).then(() => {
console.log("Value is set");
});
chrome.storage.sync.get(["key"]).then((result) => {
console.log("Value currently is " + result.key);
});
storage.session
chrome.storage.session.set({ key: value }).then(() => {
console.log("Value was set");
});
chrome.storage.session.get(["key"]).then((result) => {
console.log("Value currently is " + result.key);
});
如需详细了解 managed
存储区域,请参阅存储区域的清单。
存储空间上限和节流限制
不要认为添加到 Storage API 就像是把东西放到一辆大卡车中。考虑添加到 就像将物品放入管道一样。管子里可能已经有材质了 甚至可能被填充始终假定从您添加到存储空间到实际完成 1 个时间之间存在延迟 已记录。
如需详细了解存储区域限制以及超出限制时会出现什么情况,请参阅 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);
});
扩展程序示例
如需查看 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,其他平台需要使用回调。
-
-
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,其他平台需要使用回调。
-
-
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,其他平台需要使用回调。
-
-
getKeys
void
<ph type="x-smartling-placeholder"></ph> 承诺 待定从存储空间获取所有密钥。
getKeys
函数如下所示:(callback?: function) => {...}
-
callback
函数(可选)
callback
参数如下所示:(keys: string[]) => void
-
密钥
字符串[]
包含从存储空间读取的键的数组。
-
-
返回
Promise<string[]>
只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
-
-
移除
void
<ph type="x-smartling-placeholder"></ph> 承诺从存储空间中移除一项或多项内容。
remove
函数如下所示:(keys: string | string[], callback?: function) => {...}
-
密钥
string |字符串 []
要移除的项的单个键或键列表。
-
callback
函数(可选)
callback
参数如下所示:() => void
-
返回
承诺<void>
Chrome 88 及更高版本只有 Manifest V3 及更高版本支持 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,其他平台需要使用回调。
-
-
setAccessLevel
void
<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 102 及更高版本为存储区域设置所需的访问权限级别。默认为仅限可信上下文。
setAccessLevel
函数如下所示:(accessOptions: object, callback?: function) => {...}
-
accessOptions
对象
-
accessLevel
存储区域的访问权限级别。
-
-
callback
函数(可选)
callback
参数如下所示:() => void
-
返回
承诺<void>
只有 Manifest V3 及更高版本支持 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
字符串
-