chrome.storage

Description

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

Permissions

storage

# Overview(概述)

该 API 已经过优化以满足扩展的特定存储需求。它提供与 localStorage API API 相同的存储功能，但有以下主要区别：

用户数据可以与 Chrome 同步（使用 storage.sync）自动同步。
您的扩展程序的内容脚本可以直接访问用户数据，而无需后台页面。
即使使用拆分隐身行为split incognito behavior，用户的扩展设置也可以保留。
它与批量读取和写入操作异步，因此比阻塞和串行localStorage API 更快。
用户数据可以存储为对象（localStorage API 将数据存储在字符串中）。
可以读取管理员为扩展配置的企业策略（使用带有架构的 storage.managed）。

# Manifest

您必须在扩展清单extension manifest中声明“存储storage”权限才能使用存储 API。例如：

{
  "name": "My extension",
  ...
  "permissions": [
    "storage"
  ],
  ...
}

# Usage

要为您的扩展程序存储用户数据，您可以使用 storage.sync：

chrome.storage.sync.set({key: value}, function() {
  console.log('Value is set to ' + value);
});

chrome.storage.sync.get(['key'], function(result) {
  console.log('Value currently is ' + result.key);
});

or storage.local:

chrome.storage.local.set({key: value}, function() {
  console.log('Value is set to ' + value);
});

chrome.storage.local.get(['key'], function(result) {
  console.log('Value currently is ' + result.key);
});

使用 storage.sync 时，如果用户已启用同步，则存储的数据将自动同步到用户登录的任何 Chrome 浏览器。

当 Chrome 离线时，Chrome 会将数据存储在本地。下次浏览器在线时，Chrome 会同步数据。即使用户禁用同步，storage.sync 仍将工作。在这种情况下，它的行为与 storage.local 相同。

Warning
不应存储机密用户信息！存储区域未加密。

storage.managed 存储是只读的。

# Storage and throttling limits(存储和节流限制)

chrome.storage 不是一辆大卡车。这是一系列的管子。如果你不明白，这些管子可以装满，如果当你把你的信息填满时，它就会排队，而且任何人都会延迟将大量材料放入该管子。

有关存储 API 的当前限制以及超出这些限制时会发生什么的详细信息，请参阅同步sync和本地local的配额信息。

# Examples

以下部分演示了如何使用 chrome.storage 来解决一些常见用例。

# Synchronous response to storage updates(对存储更新的同步响应)

如果您对跟踪对数据对象所做的更改感兴趣，可以向其 onChanged 事件添加一个侦听器。每当存储中发生任何变化时，都会触发该事件。以下是侦听已保存更改的示例代码：

//// background.js ////

chrome.storage.onChanged.addListener(function (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}".`
    );
  }
});

我们可以将这个想法更进一步。在这个例子中，我们有一个选项页面options page，允许用户在扩展中切换“调试模式”（此处未显示实现）。对此设置的更改会立即通过选项页面保存到同步存储中，后台脚本使用 storage.onChanged 尽快应用设置。

<!-- options.html -->

<script defer src="options.js"></script>
<form id="optionsForm">
  <label for="debug">
    <input type="checkbox" name="debug" id="debug">
    Enable debug mode
  </label>
</form>

//// options.js ////

// 用户选项的页内缓存
const options = {};

// 使用用户的选项设置初始化表单
chrome.storage.sync.get('options', (data) => {
  Object.assign(options, data.options);
  optionsForm.debug.checked = Boolean(options.debug);;
});

// 立即保留选项更改
optionsForm.debug.addEventListener('change', (event) => {
  options.debug = event.target.checked;
  chrome.storage.sync.set({options});
});

//// background.js ////

// 注意用户选项的变化并应用它们
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);
  }
});

# Asynchronous preload from storage(从存储异步预加载)

由于 Service Worker 并不总是在运行，Manifest V3 扩展有时需要在执行它们的事件处理程序之前从存储中异步加载数据。为此，以下代码段使用 async action.onClicked 事件处理程序，该处理程序在执行其逻辑之前等待填充 storageCache 全局。

//// background.js ////

// 我们将公开从 storage.sync 检索到的所有数据。
const storageCache = {};
// 从 storage.sync 异步检索数据，然后缓存它。
const initStorageCache = getAllStorageSyncData().then(items => {
  // 将从存储中检索到的数据复制到 storageCache 中。
  Object.assign(storageCache, items);
});

chrome.action.onClicked.addListener(async (tab) => {
  try {
    await initStorageCache;
  } catch (e) {
    // 处理存储初始化期间发生的错误。
  }
  // 正常的动作处理程序逻辑。
});

// 从 storage.sync 中读取所有数据并通过promise公开它。 
// // 注意：一旦 Storage API 获得 promise 支持，此函数 
// 可以大大简化。
function getAllStorageSyncData() {
  // 立即返回一个 promise 并开始异步工作
  return new Promise((resolve, reject) => {
    // 从 storage.sync 异步获取所有数据。
    chrome.storage.sync.get(null, (items) => {
      // 将任何观察到的错误传递到承诺（promise）链 
      if (chrome.runtime.lastError) {
        return reject(chrome.runtime.lastError);
      }
      // // 将从存储中检索到的数据向下传递到承诺（promise）链
      resolve(items);
    });
  });
}

Summary

Types
StorageArea
StorageChange
Properties
local
managed
sync
Events
onChanged

Types

StorageArea

PROPERTIES

onChanged
event
Chrome 73+
当一项或多项更改时触发。
The onChanged.addListener function looks like:
```
(callback: function) => {...}
```
- callback
  function
  The callback parameter looks like:
```
(changes: object) => void
```
  - changes
    object

clear
function
Promise
从存储中删除所有项目。
The clear function looks like:
```
(callback?: function) => {...}
```
- callback
  function optional
  The callback parameter looks like:
```
() => void
```
  - returns
  Promise<void>
  Pending
  这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

get
function
Promise
从存储中获取一项或多项。
The get function looks like:
```
(keys?: string | string[] | object, callback?: function) => {...}
```
- keys
  string | string[] | object optional
  要获取的单个键、要获取的键列表或指定默认值的字典（请参阅对象的描述）。空列表或对象将返回空结果对象。传入 null 以获取存储的全部内容。
- callback
  function optional
  The callback parameter looks like:
```
(items: object) => void
```
  - items
    object
    具有键值映射中的项目的对象。

returns
Promise<object>
Pending
这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

getBytesInUse
function
Promise
获取一个或多个项目使用的空间量（以字节为单位）。
The getBytesInUse function looks like:
```
(keys?: string | string[], callback?: function) => {...}
```
- keys
  string | string[] optional
  要获取总使用量的单个键或键列表。空列表将返回 0。传入 null 以获取所有存储的总使用量。
- callback
  function optional
  The callback parameter looks like:
```
(bytesInUse: number) => void
```
  - bytesInUse
    number
    存储中使用的空间量，以字节为单位。

returns
Promise<number>
Pending
这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

remove
function
Promise
从存储中移除一件或多件物品。
The remove function looks like:
```
(keys: string | string[], callback?: function) => {...}
```
- keys
  string | string[]
  要删除的项目的单个键或键列表。
- callback
  function optional
  The callback parameter looks like:
```
() => void
```
  - returns
  Promise<void>
  Pending
  这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

set
function
Promise
设置多个项目。
The set function looks like:
```
(items: object, callback?: function) => {...}
```
- items
  object
  一个对象，它为每个键/值对提供更新存储。存储中的任何其他键/值对都不会受到影响。
  数字等原始值将按预期序列化。具有“object”和“function”typeof类型的值通常会序列化为 {}，但 Array（按预期序列化）、Date 和 Regex（使用其字符串表示形式序列化）除外。
- callback
  function optional
  The callback parameter looks like:
```
() => void
```
  - returns
  Promise<void>
  Pending
  这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

StorageChange

PROPERTIES

newValue
any optional
项目的新值（如果有新值）。
oldValue
any optional
项目的旧值（如果有旧值）。

Properties

local

本地存储区中的项目对于每台机器都是本地local的。

TYPE

StorageArea & object

PROPERTIES

QUOTA_BYTES
5242880
可以存储在本地存储中的最大数据量（以字节为单位），通过每个值的 JSON 字符串化加上每个键的长度来衡量。如果扩展具有无限存储unlimitedStorage权限，则该值将被忽略。会导致超出此限制的更新会立即失败并设置 runtime.lastError。

managed

托管存储区中的项目由域管理员managed设置，对于扩展是只读的；尝试修改此命名空间会导致错误。

TYPE

StorageArea

sync

同步存储区中的项目使用 Chrome 同步进行同步sync。

TYPE

StorageArea & object

PROPERTIES

MAX_ITEMS
512
同步存储中可以存储的最大项目数。会导致超出此限制的更新将立即失败并设置 runtime.lastError。
MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE
1000000
Deprecated
storage.sync API 不再具有持续的写入操作配额。
MAX_WRITE_OPERATIONS_PER_HOUR
1800
每小时可以执行的最大设置set、删除remove或清除clear操作数。这是每 2 秒 1 次，比短期更高的每分钟写入次数限制更低的上限。
会导致超出此限制的更新立即失败并设置runtime.lastError。
MAX_WRITE_OPERATIONS_PER_MINUTE
120
每分钟可以执行的设置set、删除remove或清除clear操作的最大数量。这是每秒 2 次，在更短的时间内提供比每小时写入更高的吞吐量。
会导致超出此限制的更新立即失败并设置runtime.lastError。
QUOTA_BYTES
102400
可以存储在同步存储中的最大数据总量（以字节为单位），通过每个值的 JSON 字符串化加上每个键的长度来衡量。会导致超出此限制的更新立即失败并设置runtime.lastError。
QUOTA_BYTES_PER_ITEM
8192
同步存储中每个单独项目的最大大小（以字节为单位），通过其值加上其密钥长度的 JSON 字符串化来衡量。包含大于此限制的项目的更新将立即失败并设置runtime.lastError。

Events

onChanged

chrome.storage.onChanged.addListener(
  callback: function,
)

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

PARAMETERS

callback
function
The callback parameter looks like:
```
(changes: object, areaName: string) => void
```
- changes
  object
- areaName
  string

By.一粒技术服务.

chrome.storage

chrome.storage

Description

Permissions

# Overview(概述)

# Manifest

# Usage

# Storage and throttling limits(存储和节流限制)

# Examples

# Synchronous response to storage updates(对存储更新的同步响应)

# Asynchronous preload from storage(从存储异步预加载)

Summary

Types

StorageArea

PROPERTIES

StorageChange

PROPERTIES

Properties

local

TYPE

PROPERTIES

managed

TYPE

sync

TYPE

PROPERTIES

Events

onChanged

PARAMETERS

results matching ""

No results matching ""