chrome.storage

说明

使用 chrome.storage API 来存储、检索和跟踪用户数据的更改。

权限

storage

概览

Storage API 提供了一种特定于扩展程序的方式来持久保留用户数据和状态。它类似于 Web 平台的存储 API（IndexedDB 和 Storage），但旨在满足扩展程序的存储需求。以下是一些关键功能：

  • 所有扩展程序上下文（包括扩展程序服务工作线程和内容脚本）都可以访问 Storage API。
  • JSON 可序列化值存储为对象属性。
  • Storage API 是异步的，支持批量读取和写入操作。
  • 即使清除缓存和浏览记录，数据也会保留。
  • 即使使用拆分式无痕模式，存储的设置也会保留。
  • 包含一个专用于企业政策的只读受管理存储区。

尽管扩展程序可以在某些情境（弹出式窗口和其他 HTML 页面）中使用 [Storage][mdn-storage] 接口（可从 window.localStorage 访问），但不建议这样做，原因如下：

  • 扩展程序的服务工作线程无法访问 Storage。
  • 内容脚本与宿主网页共享存储空间。
  • 当用户清除浏览记录时，使用 Storage 接口保存的数据会丢失。

如需从服务工作线程将数据从 Web 存储 API 移至扩展程序存储 API，请执行以下操作：

  1. 创建具有转换例程和 [onMessage][on-message] 处理程序的屏幕外文档。
  2. 向屏幕外文档添加转换例程。
  3. 在扩展程序服务工作线程中，检查 chrome.storage 是否包含您的数据。
  4. 如果未找到数据，请 [创建][create-offscreen] 一个屏幕外文档，然后调用 [sendMessage()][send-message] 以启动转换例程。
  5. 在屏幕外文档的 onMessage 处理程序内，调用转换例程。

此外，扩展程序中的 Web 存储 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。您可以考虑使用它来跨服务工作线程运行存储全局变量。
storage.managed
管理员可以使用架构和企业政策在受管理的环境中配置支持的扩展程序的设置。此存储区是只读的。

清单

如需使用存储 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 添加内容视为将内容放入大卡车。您可以将向存储空间添加内容视为将内容放入管道中。管道中可能已经有材料，甚至可能已装满。始终假设从您将内容添加到存储空间到实际记录内容之间存在延迟。

如需详细了解存储空间限制以及超出限制后会发生什么情况，请参阅 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，并且服务工作线程会使用 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);   } });

从存储空间异步预加载

由于服务工作线程并不总是处于运行状态，因此 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); });

扩展示例

如需查看存储空间 API 的其他演示，请参阅以下任一示例：

类型

AccessLevel

Chrome 102 及更高版本

存储区的访问权限级别。

枚举

“TRUSTED_CONTEXTS”
指定源自扩展程序本身的上下文。

"TRUSTED_AND_UNTRUSTED_CONTEXTS"
指定来自扩展程序外部的上下文。

StorageArea

属性

  • onChanged

    Event<functionvoidvoid>

    Chrome 73 及更高版本

    当一个或多个项发生更改时触发。

    onChanged.addListener 函数如下所示： 

    (callback: function) => {...}

    • callback

      函数

      callback 参数如下所示： 

      (changes: object) => void

      • 更改

        对象

  • 清除

    void

    Promise

    从存储空间中移除所有内容。

    clear 函数如下所示： 

    (callback?: function) => {...}

    • callback

      函数 可选

      callback 参数如下所示： 

      () => void

    • 返回

      Promise<void>

      Chrome 95 及更高版本

      仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

  • get

    void

    Promise

    从存储空间中获取一项或多项内容。

    get 函数如下所示： 

    (keys?: string | string[] | object, callback?: function) => {...}

    • 密钥

      字符串 | 字符串数组 | 对象（可选）

      要获取的单个键、要获取的键列表，或指定默认值的字典（请参阅对象说明）。空列表或空对象将返回空结果对象。传入 null 可获取存储空间的全部内容。

    • callback

      函数 可选

      callback 参数如下所示： 

      (items: object) => void

      • 项目

        对象

        包含键值对映射中各项的对象。

    • 返回

      Promise<object>

      Chrome 95 及更高版本

      仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

  • getBytesInUse

    void

    Promise

    获取一个或多个内容所用的空间量（以字节为单位）。

    getBytesInUse 函数如下所示： 

    (keys?: string | string[], callback?: function) => {...}

    • 密钥

      字符串 | 字符串数组 可选

      单个键或键列表，用于获取总使用量。如果列表为空，则返回 0。传入 null 可获取所有存储空间的总用量。

    • callback

      函数 可选

      callback 参数如下所示： 

      (bytesInUse: number) => void

      • bytesInUse

        数值

        存储空间使用量（以字节为单位）。

    • 返回

      Promise<number>

      Chrome 95 及更高版本

      仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

  • getKeys

    void

    Promise Chrome 130 及更高版本

    从存储空间获取所有键。

    getKeys 函数如下所示： 

    (callback?: function) => {...}

    • callback

      函数 可选

      callback 参数如下所示： 

      (keys: string[]) => void

      • 密钥

        字符串[]

        包含从存储空间读取的键的数组。

    • 返回

      Promise<string[]>

      仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

  • 移除

    void

    Promise

    从存储空间中移除一项或多项内容。

    remove 函数如下所示： 

    (keys: string | string[], callback?: function) => {...}

    • 密钥

      字符串 | 字符串数组

      要移除的商品的单个键或键列表。

    • callback

      函数 可选

      callback 参数如下所示： 

      () => void

    • 返回

      Promise<void>

      Chrome 95 及更高版本

      仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

  • set

    void

    Promise

    设置多个项。

    set 函数如下所示： 

    (items: object, callback?: function) => {...}

    • 项目

      对象

      一个对象，用于提供要更新存储空间的每个键值对。存储空间中的任何其他键值对都不会受到影响。

      数字等原始值将按预期序列化。具有 typeof "object" 和 "function" 的值通常会序列化为 {}，但 Array（按预期序列化）、Date 和 Regex 除外（使用其 String 表示形式进行序列化）。

    • callback

      函数 可选

      callback 参数如下所示： 

      () => void

    • 返回

      Promise<void>

      Chrome 95 及更高版本

      仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

  • setAccessLevel

    void

    Promise Chrome 102 及更高版本

    为存储区设置所需的访问权限级别。默认情况下，session 存储空间仅限受信任的上下文（扩展程序页面和服务工作器）访问，而 managed、local 和 sync 存储空间允许受信任和不受信任的上下文访问。

    setAccessLevel 函数如下所示： 

    (accessOptions: object, callback?: function) => {...}

    • accessOptions

      对象

      • accessLevel

        AccessLevel

        存储区的访问权限级别。

    • callback

      函数 可选

      callback 参数如下所示： 

      () => void

    • 返回

      Promise<void>

      仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

StorageChange

属性

  • newValue

    任何可选

    商品的新值（如果有）。

  • oldValue

    任何可选

    商品的旧值（如果有）。

属性

local

local 存储区中的内容是每个机器本地的。

类型

StorageArea 和对象

属性

  • QUOTA_BYTES

    10485760

    可存储在本地存储空间中的数据量上限（以字节为单位），计算方式为每个值的 JSON 字符串化长度加上每个键的长度。如果扩展程序具有 unlimitedStorage 权限，系统将忽略此值。如果更新会导致超出此限制，则会立即失败，并在使用回调时设置 runtime.lastError，或者在使用 async/await 时设置被拒绝的 Promise。

managed

managed 存储区域中的项由网域管理员配置的企业政策设置，并且对扩展程序是只读的；尝试修改此命名空间会导致错误。如需了解如何配置政策，请参阅存储区域的清单。

类型

StorageArea

sync

sync 存储区域中的内容会使用 Chrome 同步功能进行同步。

类型

StorageArea 和对象

属性

  • MAX_ITEMS

    512

    同步存储空间中可存储的最大项数。如果更新会导致超出此限制，则更新会立即失败，并在使用回调时或 Promise 被拒绝时设置 runtime.lastError。

  • MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

    1000000

    已弃用

    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

      字符串