chrome插件开发中Chrome storage API使用详解

1. 前言

Storage API 是 Google Chrome 提供的一个内置 API，用于在插件中存储和访问数据。它提供了四种存储方式：本地存储（Local Storage）,同步存储（Sync Storage）,会话存储(storage.session), 受管存储(storage.managed)。本地存储用于在本地计算机上存储数据，而同步存储则将数据存储在用户的 Google 账号中，并在不同设备间同步。这使得插件能够在不同环境中保持一致的数据状态，为用户提供更好的体验。

Chrome storage API 提供了一种特定于插件的方法来保存用户数据和状态。它类似于 Web 平台的存储 API（IndexedDB和Storage），但旨在满足扩展的存储需求。以下是一些主要功能：

• 所有插件contexts（包括扩展service worker和content scripts ）都可以访问存储 API。
• 存储数据的格式需要符合要求,存储的数据必须是 JSON 格式的对象或字符串，否则将会触发错误。
• 存储数据的读写是异步的：由于存储数据的读写操作是异步的，因此需要使用回调函数或 Promise 来处理返回值。
• 存储数据可以执行批量读写操作。
• 即使用户清除缓存和浏览历史记录，数据仍然存在。
• 即使用户使用隐身模式，存储的设置也会保留。
• 受管存储区域提供只读模式, 专用于企业浏览器策略。

2. 储存区结束

Chrome storage被分割为四块存储区域, 分别为:

• 本地存储(storage.local)
• 同步存储(storage.sync)
• 存储会话(storage.session)
• 受管存储区域(storage.managed)

2.1. 本地存储(storage.local)

数据存储在本地，当插件被删除时，数据将被清除。配额限制约为 10 MB，但可以通过请求权限来增加”unlimitedStorage”。考虑使用它来存储大量数据。使用它可以让插件在多个页面之间共享数据，而且这些数据在用户关闭浏览器后也不会丢失。

在 Chrome 114 之前，本地配额约为 5 MB。

在实际开发场景中我们通常使用它来存储以下类型的数据：

• 用户配置数据：比如用户选择的语言、主题、字体等。
• 用户历史记录：比如用户最近访问的网站、搜索记录等。
• 扩展程序状态：比如用户是否登录、扩展程序是否启用等。

2.1.1. local Storage API 清单

API	描述
chrome.storage.local.get()	用于获取存储在本地的数据
chrome.storage.local.set()	用于存储数据到本地存储空间中
chrome.storage.local.remove()	用于删除本地存储空间中的数据
chrome.storage.local.clear()	用于删除本地存储空间中所有items
chrome.storage.local.getBytesInUse()	用于获取已存储数据的大小

2.1.2. 本地存储使用方法

下面是一个简单的 chrome.storage.local 的使用示例：

// 存储数据
chrome.storage.local.set({language: 'zh-CN'}, function() {
  console.log('Data saved.');
});

// 读取数据
chrome.storage.local.get('language', function(result) {
  console.log('Language is ' + result.language);
});

在上面的代码中，我们首先使用 chrome.storage.local.set 方法存储了一个名为”language”的键值对，表示用户选择的语言为中文。回调函数中打印了一条日志表示数据已经存储成功。
接着，我们使用 chrome.storage.local.get 方法读取了名为”language”的键值对，并打印出来。如果之前已经存储了这个键值对，那么会输出”Language is zh-CN”。
需要注意的是，存储数据是异步的，因此在读取数据时需要在回调函数中处理。而且存储的数据必须是JSON格式的，因此需要将数据用对象的形式传递给 chrome.storage.local.set 方法。

另外 localStorage 是基于域名的。而 content_scripts 是注入到用户当前浏览页面中的，如果 content_scripts 直接读取 localStorage，所读取到的数据是用户当前浏览页面所在域中的。

所以通常的解决办法是 content_scripts 通过 runtime.sendMessage 和 service worker 通信，由 service worker 读写扩展所在域（通常是 chrome-extension://extension-id/）的 localStorage，然后再传递给 content_scripts。这样就可以实现跨页面共享数据.

另外storage local 支持批量读写操纵, 当我们需要一组数据时不必逐个的去读取或写入.

var user1 = {'name': 'diego', 'age': 18}
var user2 = {'name': 'eagle', 'age': 20}
 
// 往存储中写入数据
chrome.storage.local.set({'user1': user1}, function() {
    console.log('保存成功');

chrome.storage.local.set({'user2': user2}, function() {
    console.log('保存成功');


// 从存储中批量读取数据
chrome.storage.local.get(['user1', 'user2'], function(result) {
    document.write(
        'name: ' + result['user1'].name + '<br>' + 'age: ' + result['user1'].age 
        + '<hr>' 
        + 'name: ' + result['user2'].name + '<br>' + 'age: ' + result['user2'].age
        );
});

2.2. 同步存储(storage.sync)

如果同步存储被启用，数据将同步到用户登录的任何 Chrome 浏览器。如果禁用，其行为类似于storage.local. 当浏览器离线时，Chrome 会在本地存储数据，并在浏览器重新上线时恢复同步。整体配额约为 100 KB，单条记录限额为 8 KB。可以使用它来跨浏览器同步用户设置。

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

在实际开发场景中通常用于存储需要在多个设备之间同步的数据，例如：

• 用户偏好设置：如主题、语言、字体大小等。
• 书签和浏览历史：使用户在不同设备上能够访问相同的书签和浏览历史记录。
• 扩展程序状态和配置：确保用户在不同设备上使用相同的扩展程序设置。

2.2.1. sync Storage API 清单

API	描述
chrome.storage.sync.get()	用于获取存储在同步存储的数据
chrome.storage.sync.set()	用于存储数据到同步存储空间中
chrome.storage.sync.remove()	用于删除同步存储空间中的数据
chrome.storage.sync.clear()	用于删除同步存储空间中所有items
chrome.storage.sync.getBytesInUse()	用于获取已使用的同步存储数据的大小

chrome.storage.sync 的API包含以上几个参数，与 chrome.storage.local 基本一致。它们属于StorageArea的基本方法.

以下是一个chrome.storage.sync 的使用示例：

// 存储数据
chrome.storage.sync.set({theme: 'dark'}, function() {
  console.log('Data saved.');
});

// 读取数据
chrome.storage.sync.get('theme', function(result) {
  console.log('Theme is ' + result.theme);
});

2.3. 会话存储(storage.session)

在浏览器会话期间将数据保存在内存中。默认情况下，它不会暴露给content scripts，但可以通过设置更改此行为chrome.storage.session.setAccessLevel()。配额限制约为 10 MB。考虑使用它来存储跨service worker运行的全局变量。

在 Chrome 112 之前，配额约为 1 MB。

2.4. 受管存储区域(storage.managed)

用于存储和管理由管理员在企业环境中配置的扩展程序设置，它的主要作用是在企业环境中统一管理和配置扩展程序的设置。企业管理员可以通过集中管理的方式，向员工的Chrome浏览器中推送扩展程序的特定设置，确保各个用户使用相同的配置。

管理员可以使用JSON Schema和企业策略在托管环境中配置支持扩展的设置。该存储区域是只读的。

2.4.1. managed Storage API 清单

API	描述
chrome.storage.managed.get()	用于获取存储在 Chrome 管理的环境中的数据
chrome.storage.managed.set()	用于存储数据到 Chrome 管理的环境中，但只能由管理员或管理控制台授权的组织进行写操作
chrome.storage.managed.remove()	用于删除 Chrome 受管存储中的数据，但只能由管理员或管理控制台授权的组织进行写操作
chrome.storage.managed.clear()	用于删除受管存储空间中所有items, 但只能由管理员或管理控制台授权的组织进行写操作
chrome.storage.managed.getBytesInUse()	用于获取受管存储空间已使用的存储数据的大小

需要注意的是，chrome.storage.managed 主要用于企业或教育机构的管理控制台，而不是一般的插件开发。该 API 用于管理者对用户浏览器环境中的存储数据进行控制和配置。

以下是一个简单的示例：

chrome.storage.managed.get(['theme', 'language'], function(result) {
  console.log('Theme is ' + result.theme);
  console.log('Language is ' + result.language);
});

3. 如何查看local storage 和 sync storage

可能是出于数据安全考虑, Devtools中没有提供直接查看这两块存储区域的图形化工具, 网上提供的图形化工具插件Storage Area Explorer也被禁用了, 但是通过一些方法可以安装并启用这个插件, 具体参考is-there-a-way-to-view-chrome-storage-local-in-developer-tools.

另一种方法是使用命令行, 当断点停在content script上或service worker脚本上时, 打开console, 输入chrome.storage.sync.get()或chrome.storage.sync.get() 在打印出的对象上, 展开节点Promise=>PromiseResult可以看到所有数据.

第三种方法: 打开chrome://sync-internals/ 在Sync Node Browser界面展开Extension settings节点可以看到Sync strage的存储状况.

4. 相关阅读

Chrome插件开发

5. 参考文档

谷歌插件开发：Storage API 详解（手把手带你从零探索开发谷歌插件

Chrome storage存储 API使用详解

Chrome extension API - chrome.storage