# @extend-chrome/messages 中文文档

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

版本：1\.2\.2
npm 元数据更新时间：2022-04-05T09:25:25.733Z
中文译文更新时间：2026-11-14T06:08:15.499Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：83.2 kB，16 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2020-06-09T20:17:45.468Z
- 最新版本发布：2021-05-26T01:18:58.437Z
- 近 30 天下载量：3238（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 0 个）

## 中文简介

用于 Chrome 扩展消息的 API 有道理 .

## 安装

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

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

## README

[![@extend-chrome/messages logo](https://imgur.com/XYtiJBw.png)](https://npmcn.com/package/%40extend-chrome/messages/%20//github.com/extend-chrome/messages)

### @ extend- chrome/ 邮件

[![npm (scoped)](https://img.shields.io/npm/v/@extend-chrome/messages.svg)](https://www.npmjs.com/package/@extend-chrome/messages) [![GitHub last commit](https://img.shields.io/github/last-commit/extend-chrome/messages.svg)](https://github.com/extend-chrome/messages) [![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/messages/#readme-typescript)

[![Fiverr: We make Chrome extensions](https://img.shields.io/badge/Fiverr%20-We%20make%20Chrome%20extensions-brightgreen.svg)](https://www.fiverr.com/jacksteam) [![ko-fi](https://img.shields.io/badge/ko--fi-Buy%20me%20a%20coffee-ff5d5b)](https://ko-fi.com/K3K1QNTF)

* * *

Chrome 扩展消息的 API 有道理 。 承诺和 可观察方便.

## 目录

-   [开始](https://npmcn.com/package/%40extend-chrome/messages/#readme-getting_started)
-   [使用量](https://npmcn.com/package/%40extend-chrome/messages/#readme-usage)
-   [特征](https://npmcn.com/package/%40extend-chrome/messages/#readme-features)
-   [API 密码](https://npmcn.com/package/%40extend-chrome/messages/#readme-api)

## 开始

你需要用一个像 [滚动](https://rollupjs.org/guide/en/), (中文(简体) ), Parcel,或Webpack,将这个库包含在Chrome扩展的构建中.

见 [`rollup-plugin-chrome-extension`](https://github.com/extend-chrome/rollup-plugin-chrome-extension) 用Rollup来建造你的Chrome扩展!

### 安装

```sh
$ npm i @extend-chrome/messages
```

## 使用量

使用同位素信件包发送和接收信件,或使用 传统消息对象.

```javascript
// messages.js, used in both the background and content script
import { getMessage } from '@extend-chrome/messages'

// getMessage returns [Function, Observable, Function]
export const [sendNumber, numberStream, waitForNumber] = getMessage(
  // String to be used as a greeting
  'NUMBER',
)
```

```javascript
// background.js, a background script
import { numberStream } from './messages'

// numberStream is an RxJs Observable
numberStream.subscribe(([n, sender]) => {
  console.log('the data passed to sendNumber', n)
  // Sender is a Chrome runtime MessageSender
  console.log('the message sender', sender)
})
```

```javascript
// content.ts, a content script
import { sendNumber } from './messages'

document.body.onclick = () => {
  sendNumber(42) // 42 is logged in the background
}
```

### `getMessage` 有很好的 TypeScript 支持 !

如果你喜欢TypeScript, `getMessage` 是一个通用函数。 它闪耀,当 定义信件数据类型。 不再出现消息数据类型错误! 情报已经覆盖了.

```typescript
// messages.ts
import { getMessage } from '@extend-chrome/messages'

interface Stats {
  hi: number
  low: number
  date: string
}

export const [sendStats, statsStream, waitForStats] = getMessage<Stats>('STATS')

// If you have a message type with no data, use void rather than undefined
// This way you can call it with zero arguments
export const [sendReady, readyStream, waitForReady] = getMessage<void>('READY')
```

```typescript
// background.ts
import { statsStream } from './messages'

statsStream.subscribe(([{ hi, lo, date }, sender]) => {
  // Intellisense knows this is an Observable of
  // [Stats, chrome.runtime.MessageSender]
})

waitForReady().then(() => {
  console.log('content.ts is ready')
})
```

```typescript
// content.ts
import { sendStats } from './messages'

sendStats({ hi: 30, low: 14, date: '11/12/2019' })

// Throws a TS error
sendStats('not a Stats object')

sendReady()
```

## 特征

### 类型脚本定义

此库用 TypeScript 书写, 广泛输入, 定义为 包含,所以不需要安装额外的 `@types` 图书馆!

### RxJs 观测器

0.5.0版本介绍a [RxJs 可观察](https://rxjs-dev.firebaseapp.com/guide/overview) 作为 [`messages.stream`](https://npmcn.com/package/%40extend-chrome/messages/#readme-api-messages-stream)。 。 。 .

### 范围

0.5.0版本介绍 [`getScope`](https://npmcn.com/package/%40extend-chrome/messages/#readme-api-use-scope),一种使用单独的 通讯空间 .

如果您正在为 Chrome 扩展写一个库, 使用 内部讯息,但你不想污染全球讯息空间.

## API 密码

### `getMessage(greeting)`

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

const [sendMessage, messageStream, waitForMessage] = getMessage('greeting')
```

3⁄4 ̄ ̧漯B 导入到两者 信件发送者和接收者上下文(即背景页和内容) 剧本). `getMessage` 是 TypeScript 通用函数。 见 [使用量](https://npmcn.com/package/%40extend-chrome/messages/#readme-usage) 包含类型脚本支持的章节 !

#### `greeting`

> 类型 : `string`

一个识别消息的独特字符串 .

#### 回返情况: `[messageSender, messageStream]`

> 类型 : `[Function, Observable]`

将消息Sender导入要发送的消息的上下文中。 打电话 带有您要发送的数据的发送者.

`messageStream` 是可观察的 `[data, MessageSender]` tu. 导入 将信件插入上下文中。 订阅它 带有信件处理器功能.

### 这个 `messages` 命名空间

如果您对传统消息命名空间更满意,请导入 `messages` 对象.

#### `messages.send(data, [options])`

发送单向消息很简单:只要打电话 `messages.send` 带有对象 至少包括一个 `greeting` 属性.

```javascript
// content-script.js
import { messages } from '@extend-chrome/messages'

// Simple message with no data
messages.send({ greeting: 'hello' }).then(() => {
  console.log('The message was sent.')
})

// Message with data
messages
  .send({
    greeting: 'with-data',
    // You can use any prop name or value
    data: { x: 1 },
  })
  .then(() => {
    console.log('The message was sent.')
  })
```

实际上,可以将任何数据类型作为消息发送,但对象为 `greeting` 道具是一种很好的,灵活的图案.

##### 得到回复 `options.async`

设置可选 `options.async` 改为 `true` 以获得答复。 仅信件 第三个听众 `sendResponse` 参数将会收到同步消息.

```javascript
// content-script.js
import { messages } from '@extend-chrome/messages'

messages
  .send(
    // Message
    { greeting: 'hello' },
    // Options
    { async: true },
  )
  .then((response) => {
    console.log('They said', response.greeting)
  })
```

#### `messages.on(handler)`

要接收单向消息, 请使用 0 或 1 的处理器功能 参数。 此处理器将只接收未同步发送的信件 选项.

处理器的返回值未使用 .

```javascript
// background.js
import * as messages from '@extend-chrome/messages'

// Listener should have 2, 1, or 0 arguments
messages.on((message, sender) => {
  if (message.greeting === 'hello') {
    console.log(sender.id, 'said hello')
  }
})
```

##### 同步信件

> 我发现依赖Aync消息有点反模式 颜色是 关闭反应端口相当有攻击性,所以除非你这样做 一个同步的,最好用一个单独的信息 听者处理回复.

要接收同步消息,请使用3个参数的处理器. 这个处理器 将仅接收以同步选项发送的信息.

第三个论点是 `sendResponse` 函数,必须称之为非常 很快,否则克洛姆就会出错. 哪怕是一次等待,都可能使延期不可靠.

```javascript
// Async functions are OK!
messages.on(async (message, sender, sendResponse) => {
  if (message.greeting === 'hello') {
    console.log(sender.id, 'said hello')

    await somethingAsync()

    // Still need to call sendResponse
    sendResponse({ greeting: 'goodbye' })
  }
})
```

#### `messages.off(handler)`

用您想要停止使用的信息处理器函数调用此功能 .

#### `messages.stream`

> 类型 : `Observable`

观察其范围内的所有信息.

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

// Receives all messages in the default scope
messages.stream.subscribe(([message, sender, sendResponse]) => {
  if (typeof sendResponse !== 'undefined') {
    // If sendResponse is defined, it must be called
    sendResponse({ greeting: 'message received!' })
  }
})
```

### `getScope`

如果您正在为 Chrome 扩展写一个库, 使用 内部讯息,但你不想污染全球讯息空间.

```javascript
import { messages, getScope } from '@extend-chrome/messages'

const myScope = getScope('my-library')

// `messages.on` will not receive this message
myScope.send({ greeting: 'hey' })

// `myScope.on` will not receive this message
messages.send({ greeting: 'hello?' })
```

> 注:Chrome API事件 `chrome.runtime.onMessage` 还会收到所有 消息,但项目使用 `@extend-chrome/messages` 将不会收到来自 其他范围.

## 常见问题

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

用于 Chrome 扩展消息的 API 有道理 \.

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

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

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

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

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

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

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

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

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

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

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

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