# @extend-chrome/storage 中文文档

规范地址：https://npmcn.com/package/%40extend-chrome/storage/

版本：1\.5\.0
npm 元数据更新时间：2022-04-05T09:25:26.205Z
中文译文更新时间：2026-11-14T06:09:07.166Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40extend-chrome/storage
原文对照：https://npmcn.com/package/%40extend-chrome/storage/?lang=original
项目主页：https://github.com/extend-chrome/storage#readme
源码仓库：https://github.com/extend-chrome/storage

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：86.7 kB，24 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2020-06-08T22:27:18.701Z
- 最新版本发布：2021-06-27T20:05:19.723Z
- 近 30 天下载量：3004（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 0 个）

## 中文简介

这是用于 Chrome 扩展存储 API 的包装器, 它添加了与 React 类似的承诺和功能集交易 `this.setState` API (英语). 功能集交易可以方便地使用 Chrome 存储 API 在 di 之间共享和管理状态

## 安装

```sh
npm install @extend-chrome/storage
```

也可以使用：`pnpm add @extend-chrome/storage`、`yarn add @extend-chrome/storage`、`bun add @extend-chrome/storage`

## README

[![@extend-chrome/storage logo](https://imgur.com/2BRBk4K.png)](http://bit.ly/35jbrc5)

### @ extend- chrome/ 存储

[![npm (scoped)](https://img.shields.io/npm/v/@extend-chrome/storage.svg)](https://www.npmjs.com/package/@extend-chrome/storage) [![GitHub last commit](https://img.shields.io/github/last-commit/extend-chrome/storage.svg)](https://github.com/extend-chrome/storage) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://npmcn.com/LICENSE) [![TypeScript Declarations Included](https://img.shields.io/badge/types-TypeScript-informational)](https://npmcn.com/package/%40extend-chrome/storage/#readme-typescript)

[![Fiverr: We make Chrome extensions](https://img.shields.io/badge/Fiverr%20-We%20make%20Chrome%20extensions-brightgreen.svg)](http://bit.ly/37mZsfA) [![ko-fi](https://img.shields.io/badge/ko--fi-Buy%20me%20a%20coffee-ff5d5b)](http://bit.ly/2qmaQYB)

* * *

轻松管理 Chrome 扩展存储 `@extend-chrome/storage`。 。 。 .

这是用于 Chrome 扩展存储 API 的包装 [大类型脚本支持](https://npmcn.com/package/%40extend-chrome/storage/#readme-features-typescript) 使用虚拟存储桶并带有现代基于"承诺"的API.

# 目录

-   [开始](https://npmcn.com/package/%40extend-chrome/storage/#readme-getting_started)
-   [使用量](https://npmcn.com/package/%40extend-chrome/storage/#readme-usage)
-   [特征](https://npmcn.com/package/%40extend-chrome/storage/#readme-features)
-   [API 密码](https://npmcn.com/package/%40extend-chrome/storage/#readme-api)
    -   [接口桶](https://npmcn.com/package/%40extend-chrome/storage/#readme-api-bucket)
        -   [桶. get( )](https://npmcn.com/package/%40extend-chrome/storage/#readme-api-bucket-get)
        -   [桶. getKeys( )](https://npmcn.com/package/%40extend-chrome/storage/#readme-api-bucket-getKeys)
        -   [桶. set( )](https://npmcn.com/package/%40extend-chrome/storage/#readme-api-bucket-set)
        -   [buckle.remove () 移动( )](https://npmcn.com/package/%40extend-chrome/storage/#readme-api-bucket-remove)
        -   [桶. 清除( )](https://npmcn.com/package/%40extend-chrome/storage/#readme-api-bucket-clear)
        -   [水桶 变身](https://npmcn.com/package/%40extend-chrome/storage/#readme-api-bucket-changeStream)
        -   [桶.价值](https://npmcn.com/package/%40extend-chrome/storage/#readme-api-bucket-valueStream)
    -   [函数获取 Bucket ()](https://npmcn.com/package/%40extend-chrome/storage/#readme-api-getBucket)

# 开始

你需要用一个像 [滚动](https://rollupjs.org/guide/en/),Parcel,或 Webpack 到 将此库包含在您的 Chrome 扩展名中 .

见 [`rollup-plugin-chrome-extension`](http://bit.ly/35hLMR8) 页:1 用Rollup来建造你的Chrome扩展!

## 安装

```sh
npm i @extend-chrome/storage
```

# 使用量

添加数据 `storage` 允许您使用 `manifest.json` 文档.

```jsonc
// manifest.json
{
  "permissions": ["storage"]
}
```

把你的Chrome扩展到另一个关卡

```javascript
import { storage } from '@extend-chrome/storage'

// Set storage using an object
storage.set({ friends: ['Jack'] })

// Set storage using a function
storage.set(({ friends }) => {
  // friends is ['Jack']
  return { friends: [...friends, 'Amy'] }
})

// Get storage value using a key
storage.get('friends').then(({ friends }) => {
  // friends is ['Jack', 'Amy']
})

// Get storage values using an object
storage
  .get({ friends: [], enemies: [] })
  .then(({ friends, enemies }) => {
    // friends is ['Jack', 'Amy']
    // enemies is the [] from the getter object
  })
```

# 特征

## 虚拟键入存储桶

此库允许您创建存储区域并定义 将管理的数据类型.

```typescript
import { getBucket } from '@extend-chrome/storage'

interface Store {
  a: string
  b: number
}

const store = getBucket<Store>('store')

store.set({ a: 'abc', b })
store.set(({ b = 0 }) => ({ b: b + 500 }))

store.set({ c: true }) // ts error
store.set(({ a }) => ({ d: 'invalid' })) // ts error
```

## 承诺和功能设定

Chrome存储 API 是同步的. 这意味着同步 呼吁 `get` 财务报告和审定财务报表 `set` 将不反映待定的变动。 这个 打电话 `set` 取决于存储中的值 很难.

虽然Chrome存储 API是async,但它使用回调. 这个 给开发者带来一个充满困难的世界 已经用承诺解决了.

`@extend-chrome/storage` 解决了这两个问题。 每一种方法 返回一个承诺和两个承诺 `get` 财务报告和审定财务报表 `set` 可以承担一个函数 提供了当前存储值,类似于 React 的 `this.setState`。 。 。 .

## 编组操作

这个 `set` 方法也可以使用函数( ster) 调用 作为普通类型(字符串、字符串数组或对象).

这个装置将接收存储区域的全部内容 作为争论。 它必须返回将传递给 本地存储区域 `set` 方法.

同步调用 `set` 将构成对 本地语言 `set`。设置将按顺序应用,但每次调用 将用存储区域的最后值解决.

```javascript
bucket.set({ a: 123 })
bucket.set({ b: 456 })
bucket
  .set(({ a, b }) => {
    // a === 123
    // b === 456
    return { c: 789 }
  })
  .then(({ a, b, c }) => {
    // New values in bucket
    // a === 123
    // b === 456
    // c === 789
  })
```

个人电话 `set` 如果设置函数 扔出错误或返回无效类型,但不会影响 其他成套操作.

# API 密码

## 接口 `Bucket`

一个合成存储区域。 和本地人一样 Chrome API 存储区,但是 `get` 财务报告和审定财务报表 `set` 可以将一个函数作为 参数。 A 类 `Bucket` 可使用 [本地或同步存储](https://developer.chrome.com/extensions/storage#using-sync)。 。 。 .

多个同步调用被组成一个调用到 本地 Chrome API 语言 [`StorageArea.set`](https://developer.chrome.com/extensions/storage#method-StorageArea-set)。 。 。 .

包含默认存储区域, 这样您可以只导入 `storage` 如果你不在乎类型 只需要一个 存储区域.

```javascript
import { storage } from '@extend-chrome/storage'

storage.local.set({ a: 'abc' })
storage.sync.set({ b: 123 })
```

使用 : [`getBucket`](https://npmcn.com/package/%40extend-chrome/storage/#readme-api-getBucket)数字 :

```javascript
import { getBucket } from '@extend-chrome/storage'

// Buckets are isomorphic, so export and
// use them throughout your extension
export const bucket1 = getBucket('bucket1')
export const bucket2 = getBucket('bucket2')
```

每个桶都是独立的,所以数值不会相重叠.

```javascript
bucket1.set({ a: 123 })
bucket2.set({ a: 'abc' })

bucket1.get() // { a: 123 }
bucket2.get() // { a: 'abc' }
```

使用 TypeScript 时会发光, 因为可以 定义您的桶将包含的类型. [点击这里获取更多细节 .](https://npmcn.com/package/%40extend-chrome/storage/#readme-features-typescript)

## aync 函数 `bucket.get`

需要一个可选的获得者。 决定对象为 请求的存储区域值 .

参数

```typescript
function get(getter?: string | object | Function) => Promise<{ [key: string]: any }>
```

**\[加强\]**  
类型 : `null`, (中文(简体) ), `string`, (中文(简体) ), `string array`,或 `function`  
默认 : `null`  
除功能外,使用率与本地Chrome API相同 盖特.

-   使用 `null` 把桶里的东西都拿来.
-   使用一个 `string` 作为仅获取对象的存储区域密钥 那个钥匙/值对.
-   使用一个 `object` 带有存储密钥属性名称 想要吗.
    -   如果密钥是 存储中未定义 .
-   使用一个 `function` 将存储内容映射到任意值.
    -   该函数将接收存储的全部内容为 第一次辩论.
    -   获取的呼声将决定函数的返回值.
-   呼吁 `get` 之后 `set` 将决心实现新的价值观.

```typescript
bucket.get('a') // resolves to object as key/value pair
bucket.get({ a: 123 }) // same, but 123 is default value
bucket.get(({ a }) => a) // resolves to value of "a"
```

## aync 函数 `bucket.getKeys`

需要一个可选的获得者。 决定要用一系列字符串来表示存储区域桶中值的键.

```typescript
function getKeys() => Promise<string[]>
```

```typescript
bucket.set({ a: 123 })
bucket.getKeys() // Resolves to ['a']
```

## aync 函数 `bucket.set`

设置存储中的值。 需要设置 `object` 或者说 `function`。决定新的桶值.

参数

```typescript
function set(setter: object | Function) => Promise<{ [key: string]: any }>
```

**`setter`**  
类型 : `object` 或者说 `Function`

-   使用一个 `object` 以密钥/值对设定这些值为 存储.
-   使用一个 `Function` 返回带有密钥/值对的对象.
    -   设置函数收到先前的结果 同步设定操作.
    -   设置器函数不能是自动同步函数 .
-   回返a `Promise` 解决了新的存储值.
-   呼吁 `get` 之后 `set` 将用新的价值观解决问题.

```typescript
// Values in bucket: { a: 'abc' }

// First call to set
bucket.set({ b: 123 })

// Second synchronous call to set
bucket
  .set(({ a, b, c }) => {
    // Values composed from storage
    // and previous call to set:
    // a === 'abc'
    // b === 123
    // c === undefined
    return { c: true }
  })
  .then(({ a, b, c }) => {
    // New values in storage
    // a === 'abc'
    // b === 123
    // c === true
  })
```

```typescript
bucket.set({ a: 123 })
bucket
  .set(({ a }) => ({ b: true }))
  .then(({ a, b }) => {
    // Values were set
    // a === 123
    // b === true
  })
```

## aync 函数 `bucket.remove`

从存储中删除一个或多个值。 决定何时 操作完成 .

```typescript
bucket.remove('a')
bucket.remove(['a', 'b'])
```

## aync 函数 `bucket.clear`

只有这桶才有用 决定何时操作 完成 。 。 其他的桶是没有污染的.

```typescript
bucket.clear()
```

## aync 函数 `bucket.changeStream`

一个RxJs 观察器, 输出 a [存储变化](https://developer.chrome.com/extensions/storage#type-StorageChange) chrome 存储 API 时的对象 `onChanged` 事件火灾.

```typescript
bucket.changeStream
  .pipe(filter(({ a }) => !!a))
  .subscribe(({ a }) => {
    console.log('old value', a.oldValue)
    console.log('new value', a.newValue)
  })
```

## aync 函数 `bucket.valueStream`

一个可观察的,立即释放所有存储值, 何时 `onChanged` 火灾.

```typescript
bucket.valueStream.subscribe((values) => {
  console.log('Everything in this bucket', values)
})
```

## 函数 `getBucket`

创建一个 [桶头](https://npmcn.com/package/%40extend-chrome/storage/#readme-api-bucket) (合成存储区). 带 字符串 `bucketName` 和可选字符串 `areaName`. 回归 (单位:千美元) [`Bucket`](https://npmcn.com/package/%40extend-chrome/storage/#readme-api-bucket) 合成存储区. 导出此 桶并用在你的克罗姆扩展。 会成功的 包括特权页面和内容脚本.

`getBucket` 是类型脚本通用。 传到接口 定义存储区域中需要的类型.

参数

```typescript
function getBucket(bucketName: string, areaName?: 'local' | 'sync') => Bucket
```

**`bucketName`**  
类型 : `string`  
这桶的独有身份证明.

**`[areaName]`**  
类型 : `"local"` 或者说 `"sync"`  
默认 : `"local"`  
选择哪个 [本地 Chrome API 存储区域](https://developer.chrome.com/extensions/storage#using-sync) 用来使用.

```typescript
import { getBucket } from '@extend-chrome/storage'

// JavaScript
export const localBucket = getBucket('bucket1')
export const syncBucket = getBucket('bucket2', 'sync')

// TypeScript
export const localBucket = getBucket<{ a: string }>('bucket1')
export const syncBucket = getBucket<{ b: number }>(
  'bucket2',
  'sync',
)
```

## 常见问题

### @extend-chrome/storage 是什么？

这是用于 Chrome 扩展存储 API 的包装器, 它添加了与 React 类似的承诺和功能集交易 this\.setState API \(英语\)\. 功能集交易可以方便地使用 Chrome 存储 API 在 di 之间共享和管理状态

### 如何安装 @extend-chrome/storage？

在项目目录运行 npm install @extend-chrome/storage，或使用 pnpm add / yarn add / bun add。

### @extend-chrome/storage 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @extend-chrome/storage 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @extend-chrome/storage 可以商用吗？

@extend-chrome/storage 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @extend-chrome/storage 的下载量有多少？

根据 npm 官方下载统计，@extend-chrome/storage 在 2026/10/14 – 2026/11/12 这 30 天内被下载 3,004 次，日均约 100 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @extend-chrome/storage 还在维护吗？

最新版本 1\.5\.0 发布于 2021/06/28（5 年前）；至今共发布 15 个版本，其中过去 12 个月发布了 0 个；首次发布于 2020/06/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。