chrome.storage

说明

使用 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，请执行以下操作：

  1. 准备一个屏幕外文档 HTML 页面和脚本文件。脚本文件应包含转换例程和 onMessage 处理程序。
  2. 在扩展程序 Service Worker 中，检查 chrome.storage 以获取您的数据。
  3. 如果找不到您的数据，请调用 createDocument()。
  4. 在返回的 Promise 解析后，调用 sendMessage() 以启动转换例程。
  5. 在屏幕外文档的 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

Chrome 浏览器 102 或更高版本

存储区域的访问权限级别。

枚举

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

&quot;TRUSTED_AND_UNTRUSTED_CONTEXTS&quot;
指定源自扩展程序外部的上下文。

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&lt;object&gt;

      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&lt;number&gt;

      Chrome 88 及更高版本

      Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

  • getKeys

    void

    <ph type="x-smartling-placeholder"></ph> 承诺 待定

    从存储空间获取所有密钥。

    getKeys 函数如下所示： 

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

    • callback

      函数（可选）

      callback 参数如下所示： 

      (keys: string[]) => void

      • 密钥

        字符串[]

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

    • 返回

      Promise&lt;string[]&gt;

      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

        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 存储区域中的内容由网域管理员配置的企业政策设置，对扩展程序而言是只读的；尝试修改此命名空间会导致错误。如需了解如何配置政策，请参阅存储区域的清单。

类型

StorageArea

session

Chrome 浏览器 102 或更高版本 MV3+

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

      字符串