此页面由 Cloud Translation API 翻译。

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

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

扩展程序中的 Web 存储 API 在使用方式上也有一些细微差别。如需了解详情，请参阅 [存储空间和 Cookie][storage-and-cookies] 一文。

存储区域

Storage API 分为以下四个存储分区（“存储区”）：

storage.local: 数据存储在本地，会在移除扩展程序时清除。配额限制约为 10 MB，但可以通过请求 "unlimitedStorage" 权限来提高。建议使用它来存储更多数据。

storage.sync: 如果启用了同步功能，数据会同步到用户登录的任何 Chrome 浏览器。如果停用，则行为与 storage.local 类似。Chrome 会在浏览器离线时将数据存储在本地，并在浏览器重新上线时恢复同步。配额限制约为 100 KB，每个商品 8 KB。建议使用此功能在同步的浏览器之间保留用户设置。

警告：本地存储区和同步存储区不应存储机密用户数据，因为它们未加密。处理敏感数据时，请考虑使用 session 存储区将值保存在内存中，直到浏览器关闭为止。

storage.session: 在浏览器会话期间将数据保存在内存中。默认情况下，它不会向内容脚本公开，但可以通过设置 chrome.storage.session.setAccessLevel() 来更改此行为。配额限制约为 10 MB。您可以考虑使用它来存储服务工作线程运行时的全局变量。

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

如需详细了解存储空间限制以及超出限制后会发生什么情况，请参阅 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"
指定来自扩展程序外部的上下文。

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
  
  字符串

chrome.storage 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

说明

权限

概览

存储区域

清单

用法

storage.local

storage.sync

storage.session

存储空间和限流限制

使用场景

对存储更新的同步响应

从存储空间异步预加载

扩展示例

类型

AccessLevel

枚举

StorageChange

属性

属性

local

类型

属性

managed

类型

sync

类型

属性

事件

onChanged

参数

chrome.storage