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 的使用示例:

1
2
3
4
5
6
7
8
9
10
// 存储数据
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 支持批量读写操纵, 当我们需要一组数据时不必逐个的去读取或写入.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

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 的使用示例:

1
2
3
4
5
6
7
8
9
10
// 存储数据
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 用于管理者对用户浏览器环境中的存储数据进行控制和配置。

以下是一个简单的示例:

1
2
3
4
5
6

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