Chrome 插件 storage API 解析

Chrome.storage API 解析

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

一、各模块中的 chrome.storage 内容

1. Service workerruntime 内容

2. Actionruntime 内容

3. Contentruntime 内容

二、权限(Permissions

如果需使用 Storage API,需要在 manifest.json 文件中添加权限

json 复制代码
{
  "permissions": [    
    "storage"
  ],
}

三、Chrome.storage API 功能

Storage API 提供一种特定于扩展程序的方法来保留用户数据和状态。它类似于 Web 平台的存储 APIIndexedDBStorage),但在设计上是为了满足扩展程序的存储需求

1. Chrome.storage API 主要功能

  • 所有扩展程序上下文(包括扩展程序 Service Worker 和内容脚本)都可以访问 Storage API
  • 可序列化的 JSON 值存储为对象属性
  • Storage API 是异步的,支持批量读取和写入操作
  • 即使用户清除缓存和浏览记录,这些数据仍会保留
  • 即使在无痕模式拆分后,存储的设置也会保留
  • 包含一个用于企业政策的专属只读代管式存储区域

2. 扩展程序如何使用 Web Storage API

尽管扩展程序可以在某些上下文(弹出式窗口和其他 HTML 网页)中使用 Storage 接口(可通过 window.localStorage 访问),但不建议使用该接口,原因如下:

  • 扩展 Service Worker 无法使用 Web Storage API
  • 内容脚本与托管网页共享存储空间
  • 当用户清除浏览记录后,使用 Web Storage API 保存的数据将会丢失

3. 从 Web Storage API 移至 Service WorkerStorage API

  • 使用转换例程和 onMessage 处理程序创建屏幕外文档
  • 在扩展 Service Worker 中,检查 chrome.storage 以获取您的数据
  • 如果找不到您的数据,请创建屏幕外文档并调用 sendMessage() 以启动转换例程
  • 在屏幕外文档的 onMessage 处理程序内,调用转换例程

4. Storage API 存储区域

  • storage.local
    • 数据会存储在本地,并会在移除扩展程序时清除。存储空间上限为 10 MB,但您可以通过请求 "unlimitedStorage" 权限提高上限,建议使用 storage.local 存储大量数据。
  • storage.sync
    • 如果同步功能已启用,数据会同步到用户登录的任何 Chrome 浏览器。如果停用,其行为类似于 storage.local。当浏览器离线时,Chrome 会将数据存储在本地,并在浏览器恢复在线状态后恢复同步。配额限制大约为 100 KB,每项内容 8 KB。建议您使用 storage.sync 来保留已同步的浏览器的用户设置。如果处理的是敏感用户数据,请改用 storage.session。
  • storage.session
    • 在浏览器会话期间将数据保留在内存中。默认情况下,它不会向内容脚本公开,但可以通过设置 chrome.storage.session.setAccessLevel() 来更改此行为。存储空间上限为 10 MB。storage.session 接口是建议 Service Worker 的若干接口之一。
  • storage.managed
    • 管理员可以使用架构和企业政策在受管环境中配置支持扩展程序的设置。此存储区域是只读的。

四、Chrome.storage API 类型(Types

1. AccessLevel

存储区域的访问权限级别

类型为枚举

枚举值
  • TRUSTED_CONTEXTS
    • 用于指定源自扩展程序本身的上下文
  • TRUSTED_AND_UNTRUSTED_CONTEXTS
    • 指定源自该扩展程序外部的上下文

2. StorageArea

存储区域

属性
1. onChanged

在一项或多项更改时触发

  • onChanged: Event

onChanged.addListener 监听 demo

js 复制代码
onChanged.addListener((callback: function)=> {...})

callback 参数如下

js 复制代码
(changes: object)=>void
2. clear

从存储空间中移除所有内容

clear 函数如下所示:

js 复制代码
(callback?: function)=> {...}
3. get

从存储空间中获取一项或多项内容

get 函数如下所示:

js 复制代码
(keys?: string|string[]|object,callback?: function)=> {...}

keys: 要获取的单个键、要获取的键的列表,或指定默认值的字典。空列表或对象将返回空的结果对象。传入 null 以获取存储空间的全部内容。

4. getBytesInUse

获取一项或多项内容占用的空间量(以字节为单位)

getBytesInUse 函数如下所示:

js 复制代码
(keys?: string|string[],callback?: function)=> {...}

keys: 用于获取总用量的单个键或键列表。空列表将返回 0。传入 null 可获取所有存储空间的总用量

5. remove

从存储空间中移除一项或多项内容

remove 函数如下所示:

js 复制代码
(keys: string|string[],callback?: function)=> {...}

keys: 要移除的项的单个键或键列表

6. set

设置多个项

set 函数如下所示

js 复制代码
(items: object,callback?: function)=> {...}

items: 一个对象,提供用于更新存储空间的每个键值对。存储空间中的其他键值对不会受到影响

7. setAccessLevel

为存储区域设置所需的访问权限级别
setAccessLevel 函数如下所示:

js 复制代码
(accessOptions: object,callback?: function)=> {...}

accessOptions: 对象

  • accessLevel: AccessLevel

3. StorageChange

属性
1. newValue
2. oldValue

五、Chrome.storage API 属性(Properties

1. local

local 存储区域中的内容是每台机器的本地内容

1. 类型

StorageArea 对象

2. 属性
  • QUOTA_BYTES: 10485760
    • 本地存储空间中可存储的数据量上限(以字节为单位),衡量依据是每个值的 JSON 字符串化处理以及每个密钥的长度。如果扩展程序具有 unlimitedStorage 权限,则系统将忽略此值。如果更新会导致超出此限制,则更新会立即失败,并在使用回调时设置 runtime.lastError;如果使用 async/await,则设置被拒的 Promise。

2. managed

managed 存储区域中的内容由域管理员设置,并且对于扩展程序是只读的;尝试修改此命名空间会导致错误。

1. 类型

StorageArea

3. session

session 存储区域中的内容存储在内存中,不会持久保留到磁盘中

1. 类型

StorageArea 对象

属性
  • QUOTA_BYTES: 10485760
    • 可存储在内存中的数据量上限(以字节为单位),计算方式为:估算每个值和键的动态分配内存用量。会导致超出此限制的更新会立即失败,并且会在使用回调或 Promise 遭拒时设置 runtime.lastError。

4. sync

sync 存储区域中的内容会通过 Chrome 同步功能进行同步

1. 类型

StorageArea 对象

2. 属性
  • MAX_ITEMS: 512
    • 同步存储空间中可存储的内容数量上限。会导致超出此限制的更新将立即失败,并在使用回调或 Promise 遭拒时设置 runtime.lastError
  • MAX_WRITE_OPERATIONS_PER_HOUR: 1800
    • 每小时可执行的 set、remove 或 clear 操作次数上限。此上限是每 2 秒 1 次,低于短期的更高每分钟写入次数限制
  • MAX_WRITE_OPERATIONS_PER_MINUTE: 120
    • 每分钟可执行的 set、remove 或 clear 操作次数上限。此速率为每秒 2 次,在更短的时间段内,提供的吞吐量比每小时写入次数更高
  • QUOTA_BYTES: 102400
    • 可存储在同步存储空间中的数据总量(以字节为单位),衡量依据是每个值和每个密钥的长度的 JSON 字符串化处理
  • QUOTA_BYTES_PER_ITEM: 8192
    • 同步存储空间中每一项的大小上限(以字节为单位),衡量依据是相应项的值加上密钥长度的 JSON 字符串化处理

六、Chrome.storage API 事件(Events

1. onChanged

在一项或多项更改时触发

js 复制代码
chrome.storage.onChanged.addListener(
  callback: function,
)

callback 参数如下所示:

js 复制代码
(changes: object,areaName: string)=>void

七、示例

1. Storage API 用法示例

js 复制代码
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);
});
js 复制代码
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);
});
js 复制代码
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);
});

2. 同步响应存储空间更新

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}".`
    );
  }
});

3. 从存储空间异步预加载

js 复制代码
const storageCache = { count: 0 };
const initStorageCache = chrome.storage.sync.get().then((items) => {
  Object.assign(storageCache, items);
});

chrome.action.onClicked.addListener(async (tab) => {
  try {
    await initStorageCache;
  } catch (e) {
  }
  storageCache.count++;
  storageCache.lastTabId = tab.id;
  chrome.storage.sync.set(storageCache);
});

引用

相关推荐
逐·風27 分钟前
unity关于自定义渲染、内存管理、性能调优、复杂物理模拟、并行计算以及插件开发
前端·unity·c#
Devil枫1 小时前
Vue 3 单元测试与E2E测试
前端·vue.js·单元测试
尚梦2 小时前
uni-app 封装刘海状态栏(适用小程序, h5, 头条小程序)
前端·小程序·uni-app
守城小轩2 小时前
Chromium127编译指南 Mac篇(五)- 编译Chromium
chrome·chrome devtools·指纹浏览器·浏览器开发
GIS程序媛—椰子2 小时前
【Vue 全家桶】6、vue-router 路由(更新中)
前端·vue.js
前端青山2 小时前
Node.js-增强 API 安全性和性能优化
开发语言·前端·javascript·性能优化·前端框架·node.js
毕业设计制作和分享3 小时前
ssm《数据库系统原理》课程平台的设计与实现+vue
前端·数据库·vue.js·oracle·mybatis
清灵xmf5 小时前
在 Vue 中实现与优化轮询技术
前端·javascript·vue·轮询
大佩梨5 小时前
VUE+Vite之环境文件配置及使用环境变量
前端
GDAL5 小时前
npm入门教程1:npm简介
前端·npm·node.js