Chrome插件开发【storage】

zheshiyangyang

1402人浏览 · 2025-08-27 17:06:35

zheshiyangyang · 2025-08-27 17:06:35 发布

storage简介

chrome.storage API提供数据的存储、读取、删除、数据监听事件等功能

chrome.storage有三个存储区域：“local”、“sync”、“session”，三个存储区域都支持相同的方法，用法完全一样，仅存储特性不同。因此下面在说明方法时，将不重点介绍某一个存储区域的某一个方法，因为它们的方法都是一样的。

storage API使用前必须在manifest.json里声明“storage”权限

{
  "manifest_version": 3,
  "name": "我的扩展",
  "permissions": ["storage"],  // 必须声明此权限
  // 其他配置...
}

local

local主要用于在用户本地设备上持久化存储数据

local的五大特性：

本地持久化：数据存储在用户的本地设备硬盘中，不会随浏览器关闭而消失，除非用户手动清除
存储范围：仅在当前设备生效，不会跨设备同步(仅在当前浏览器生效)
存储容量：限制较宽松，取决于设备的存储空间
访问权限：仅同一插件内部可以访问
异步操作：所有方法均为异步执行

session

session主要用于保存插件的临时数据

session的五大特性：

生命周期：仅在当前Chrome会话(所有Chrome窗口)有效，关闭所有Chrome窗口后数据自动情况(关闭某个标签页不影响)
存储容量：约10MB
访问权限：仅同一插件内部可以访问
持久化能力：数据不写入磁盘，浏览器崩溃或重启后数据会丢失
异步操作：所有方法均为异步执行

sync

sync专门用于在用户登录Google账号的所有Chrome设备间同步数据，适合存储需要跨设备共享的少量关键信息

sync的五大特性：

同步机制：自动将数据同步到用户所有登陆相同Google账号的Chrome设备，设备联网时保持数据一致
存储机制：单挑数据 <= 8KB，总存储容量约100KB
生命周期：持久存储，除非用户手动清除扩展数据或扩展主动删除
使用场景：仅适合存储少量关键数据，不适合大量数据
性能特点：同步操作有延迟，短时间内多次修改会合并同步

常用方法

存储数据：chrome.storage.(api).set(object,callback)

功能：存储键值对数据（覆盖已存在的键）

适用区域：local、sync、session均支持

语法：

// 语法 api -> local / session / sync
chrome.storage.(api).set(Object,callback)

参数说明：

object（必填）：键值对集合，键为字符串，值为JSON可序列化类型
callback（选填）：操作完成后的回调函数，无参数

例子：

// local区域存储
chrome.storage.local.set({
    testLocalKey:"testLocalValue"
}).then(() => {
    console.log('local区域已存储数据')
})
// session区域存储
chrome.storage.session.set({
    testSessionKey:"testSessionValue"   
}).then(() => {
    console.log('session区域已存储数据')
})
// sync区域存储
chrome.storage.sync.set({
    testSyncKey:"testSyncValue"
}).then(() => {
    console.log('sync区域已存储数据')
})

效果：

获取数据：chrome.storage.(api).get(keys,callback)

功能：获取存储的数据（支持指定键或所有数据）

适用区域：local、sync、session均支持

语法：

// 语法 api -> local / session / sync
chrome.storage.(api).get(keys,callback)

参数说明：

keys（选填）：
- 若为String：获取单个键的数据
- 若为Array：获取多个键的数据
- 若为null或不填：获取当前存储区域的所有数据
- 若为Object：以“默认值”形式获取，当键不存在时返回Object键的值
callback（必填）：
- 回调参数为Object，包含获取到的键值对

例子：

// local区域
chrome.storage.local.set({
    testLocalKey:"testLocalValue"
}).then(() => {
    chrome.storage.local.get("testLocalKey").then((res) => {
        console.log('local区域已存储数据',res)
    })
})
// session区域
chrome.storage.session.set({
    testSessionKey:"testSessionValue"   
}).then(() => {
    chrome.storage.seesion.get("testSessionKey").then((res) => {
        console.log('session区域已存储数据',res)
    })
})
// sync区域
chrome.storage.sync.set({
    testSyncKey:"testSyncValue"
}).then(() => {
    chrome.storage.sync.get('testSyncKey').then((res) => {
        console.log('sync区域已存储数据',res)
    })
})

效果：

删除数据：chrome.storage.(api).remove(keys,callback)

功能：删除指定键的数据

适用区域：local、sync、session均支持

语法：

// 语法 api -> local / session / sync
chrome.storage.(api).remove(keys,callback)

参数说明：

keys（必填）：要删除的键，单个键使用字符串，多个键使用数组
- 类型：String、Array
callback（选填）：操作完成后的回调函数，无参数

例子：

// local区域
chrome.storage.local.remove("testLocalKey").then(() => {
    console.log('local区域已删除testLocalKey')
})
// session区域
chrome.storage.session.remove("testSessionKey").then(() => {
    console.log('session区域已删除testSessionKey')
})
// sync区域
chrome.storage.sync.remove('testSyncKey').then(() => {
    console.log('sync区域已删除testSyncKey')
})

效果：

清空数据：chrome.storage.(api).clear(callback)

功能：清空当前区域的所有数据

使用区域：local、sync、session

语法：

chrome.storage.(api).clear(callback)

参数说明：

callback（选填）：操作完成后的回调函数

例子：

// local区域
chrome.storage.local.clear(() => {
    console.log('local区域已清除')
})
// session区域
chrome.storage.session.clear(() => {
    console.log('session区域已清除')
})
// sync区域
chrome.storage.sync.clear(() => {
    console.log('sync区域已清除')
})

效果：

计算占用:chrome.storage.(api).getBytesInUse(keys,callback)

功能：计算指定键（所有键）占用的存储空间

使用区域：local、sync、session均支持（对sync尤其重要，监控是否超出100KB限制）

语法：

// 语法 api -> local / session / sync
chrome.storage.(api).getBytesInUse(keys,object)

参数说明：

keys（选填）：
- 类型：String、Array、null
- 若为null或不填，计算当前存储区域的所有数据的总占用空间
callback（必填）：回填参数为Number类型，表示占用的字节数

例子：

// local区域
chrome.storage.local.getBytesInUse((bytes) => {
    console.log('local区域已使用' + bytes + '字节')
})
// session区域
chrome.storage.session.getBytesInUse((bytes) => {
    console.log('session区域已使用' + bytes + '字节')
})
// sync区域
chrome.storage.sync.getBytesInUse((bytes) => {
    console.log('sync区域已使用' + bytes + '字节')
})

效果：

监听事件

onChanged.addListener(listener)

功能：监听所有存储区域的数据变化（新增、修改、删除）

使用区域：全局事件，所有区域

语法：

// 全局事件
chrome.storage.onChanged.addListener(listener)

参数说明：

listener（必填）：有两个回调参数：
- changes：变化的键值对集合，它有两个属性
  - 类型：Object
  - oldValue：修改前的值（删除时为undefined）
  - newValue：修改后的值（新增时为新值，删除时为undefined）
- areaName：发生变化的存储区域
  - 类型：String
  - 值域：local / sync / session

注意：当前脚本通过set主动修改的数据不会触发该事件（避免循环触发），仅监听“外部修改”（插件其它组件、跨设备同步修改）

例子：

我们将创建监听，并在F12开发者工具的Application中修改数据，查看是否可以监听修改

// 创建一个监听
chrome.storage.onChanged.addListener((changes,areaName) => {
    console.log(`存储区域：${areaName}发生变化`)
    switch(areaName){
        case "local":
            console.log(`local发生变化：`,changes)
            break;
        case "session":
            console.log(`session发生变化：`,changes)
            break;
        case "sync":
            console.log(`sync发生变化：`,changes)
            break;
    }
})

// 手动给三个区域先设置一个值
chrome.storage.local.set({
    "key1": "value1",
    "key2": "value2"
})
chrome.storage.session.set({
    "key3": "value3",
    "key4": "value4"
})
chrome.storage.sync.set({
    "key5": "value5",
    "key6": "value6"
})

我们将local存储区域里的“key1”改为“key10”看一下效果：