# @ably-labs/react-hooks 中文文档

规范地址：https://npmcn.com/package/%40ably-labs/react-hooks/

版本：2\.1\.2
npm 元数据更新时间：2024-10-09T11:07:00.798Z
中文译文更新时间：2026-11-06T00:53:12.253Z
软件包许可：ISC

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

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

弃用说明：This package has moved to \`ably/react\`, see https://github\.com/ably/ably-js/blob/main/docs/react\.md for instructions on how to use to the latest version

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

- 包体积（解压后）：74.1 kB，55 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react \>=18\.1\.0，react-dom \>=18\.1\.0
- 首次发布：2021-10-15T18:25:04.417Z
- 最新版本发布：2023-10-30T13:54:34.676Z
- 近 30 天下载量：7703（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：25（近 12 个月 0 个）

## 中文简介

> \[有重大意义\] 我们的 3.0 反应钩子库的发布候选件目前作为能动-js的模块可供使用,它包括使用上下文提供者和提供API以响应连接错误和信道错误等重大改进.

## 安装

```sh
npm install @ably-labs/react-hooks
```

也可以使用：`pnpm add @ably-labs/react-hooks`、`yarn add @ably-labs/react-hooks`、`bun add @ably-labs/react-hooks`

## README

# @ capaly- labs/ react- hooks

> \[大  
> 我们的 3.0 反应钩子库的发布候选件目前作为能动-js的模块可供使用,它包括使用上下文提供者和提供API以响应连接错误和信道错误等重大改进. 请看 [新反应钩子 REDME](https://github.com/ably/ably-js/blob/main/docs/react.md#L1) 用于安装指令和使用示例.

使用 Ably 在您的反应应用程序中使用平庸,容易使用, React Hooks!

您可以使用此软件包 :

-   使用反应钩与Ably频道进行交互.
-   通过 Ably 使用频道发送信件
-   获取频道中用户存在的通知
-   发送存在更新

钩子为与Ably互动提供了简化的语法,并管理了Ably SDK实例的生命周期,供您在反应组件重接时注意订阅并不订阅频道和事件.

* * *

-   [安装](https://npmcn.com/package/%40ably-labs/react-hooks/#readme-installation)
    -   [兼容反应版本](https://npmcn.com/package/%40ably-labs/react-hooks/#readme-compatible-react-versions)
    -   [Ably 频道和 API 密钥](https://npmcn.com/package/%40ably-labs/react-hooks/#readme-ably-channels-and-api-keys)
-   [使用量](https://npmcn.com/package/%40ably-labs/react-hooks/#readme-usage)
    -   [使用频道](https://npmcn.com/package/%40ably-labs/react-hooks/#readme-usechannel)
    -   [使用常识](https://npmcn.com/package/%40ably-labs/react-hooks/#readme-usepresence)
-   [开发者笔记](https://npmcn.com/package/%40ably-labs/react-hooks/#readme-developer-notes)

* * *

## 安装

船钩作为ES6舱,所以你可以使用 `import` 反应代码中的语法.

```bash
npm install --save @ably-labs/react-hooks
```

这在盒子里有用 `create-react-app` - 你可以马上使用包裹.

### 兼容反应版本

此套件的最新版本跟踪最新版本的反应.

| 反应版本 | @ capaly- labs/ react- hooks 版本 |
| --- | --- |
| 页:1 | 1.1.8 国家 |
| (单位:千美元) | 2.0.x(当前) |

### Ably 频道和 API 密钥

为了使用这些钩子,您需要Ably API 键. 如果你还没有注册,你可以 [现在报名免费Ably账户](https://www.ably.io/signup)一旦你有Ably账户:

1.  进入您的应用仪表板.
2.  下 **“你的应用程序”**,单击 **“管理软件”** 用于您想要用于此教程的任何应用程序,或创建“创建新应用程序”按钮的新应用程序.
3.  点击 **“API 密钥”** 选项卡.
4.  复制这个秘密 **“API 密钥”** 从你的"根"键得到的值,我们会使用这个 当我们建立我们的应用程序.

强烈建议您使用 [托肯认证](https://www.ably.io/documentation/rest/authentication/#token-authentication),这需要超出此读取范围的服务器侧码。 在下面的例子中,我们直接在加价时使用 API 键,这是用于 \***仅当地发展** 财务报告和审定财务报表 **不应用于生产代码** 财务报告和审定财务报表 **不应该** 献身于你的仓库.

* * *

## 使用量

一旦你用 `npm` 对你的项目,你可以用你的钩子 `react` 代码.

以添加对钩的引用开始

```javascript
import { configureAbly, useChannel } from "@ably-labs/react-hooks";
```

那你需要用那个 `configureAbly` 函数创建实例 `Ably` JavaScript SDK (英语).

```javascript
configureAbly({ key: "your-ably-api-key", clientId: generateRandomId() });
```

`configureAbly` 匹配 Ably SDK 的方法签名 - 并且需要任意一种 `string` 或一个 `AblyClientOptions`。您可以使用此配置对象来设置您的 API 密钥, 或者按您通常的方式进行符号认证 。 如果你想用这个 `usePresence` 钩子,你需要明确提供 `clientId`。 。 。 .

一旦你这样做,你可以使用 `hooks` 在你的代码。 最简单的例子如下:

```javascript
const [channel] = useChannel("your-channel-name", (message) => {
    console.log(message);
});
```

每次发送消息 `your-channel-name` 它会登录到控制台。 你可以随心所欲地处理那些留言.

* * *

### 使用频道

使用Channel 钩子可以让您订阅一个频道并从中接收消息.

```javascript
const [channel, ably] = useChannel("your-channel-name", (message) => {
    console.log(message);
});
```

**频道实例和Ably JavaScript SDK实例都从使用Channel调用中返回.**

`useChannel` 与正则反应结合时真的会发光 `useState` 钩子 - 例如, 您可以在应用程序状态中保存信件列表, 并使用 `useChannel` 钩入订阅频道, 当新消息到达时更新状态 .

```javascript
const [messages, updateMessages] = useState([]);
const [channel] = useChannel("your-channel-name", (message) => {
    updateMessages((prev) => [...prev, message]);
});

// Convert the messages to list items to render in a react component
const messagePreviews = messages.map((msg, index) => <li key={index}>{msg.data.someProperty}</li>);
```

`useChannel` 支持常规调用的所有参数组合 `channel.subscribe`,因此您可以通过提供 `message type` 页:1 `useChannel` 函数 :

```javascript
const [channel] = useChannel("your-channel-name", "test-message", (message) => {
    console.log(message); // Only logs messages sent using the `test-message` message type
});
```

这个 `channel` 实例返回 `useChannel` 可用于向频道发送消息。 这只是一个普通的 Ably JavaScript SDK `channel` 举个例子.

```javascript
channel.publish("test-message", { text: "message text" });
```

因为我们把频道实例 和Ably SDK实例从我们 `useChannel` 钩子,您可以随后使用这些来进行您喜欢的频道操作 .

例如,你可以这样检索历史:

```javascript
const [channel] = useChannel("your-channel-name", (message) => {
    console.log(message);
});

const history = channel.history((err, result) => {
    var lastMessage = resultPage.items[0];
    console.log('Last message: ' + lastMessage.id + ' - ' + lastMessage.data);
});
```

同样值得强调的是 `useChannel` 钩子支持常规的Ably SDK所做的所有附加参数,因为我们只是通过调用. 这意味着你可以使用像 `rewind`数字 :

```javascript
const [channel] = useChannel("[?rewind=100]your-channel-name", (message) => {
    // This call will rewind 100 messages
    console.log(message);
});
```

我们支持提供 [频道选项](https://ably.com/docs/api/realtime-sdk/types#channel-options) 页:1 `useChannel` 钩:

```javascript
const [channel] = useChannel({ channelName: "your-channel-name", options: { ... } }, (message) => {
    ...
});
```

我们也支持提供你自己的 `Realtime` 实例 `useChannel`,如果在同一页上需要一个以上的 Ably 客户端,则可能有用 :

```javascript
import { useChannel, Realtime } from '@ably-labs/react-hooks'

const realtime = new Realtime(options);

useChannel({ channelName: "your-channel-name", realtime: realtime }, (message) => {
    ...
})
```

对于任何必须提供频道选项的情况(例如设置加密密钥).

* * *

### 使用常识

使用Presence hook 允许您订阅频道上的存在事件 - 这将允许您在用户加入或离开频道时得到通知 .

**请注意** 获取当前成员被执行 作为一种效果,所以它会加载 _之后_ 您的组件是第一次.

```javascript
const [presenceData, updateStatus] = usePresence("your-channel-name");

// Convert presence data to list items to render    
const peers = presenceData.map((msg, index) => <li key={index}>{msg.clientId}: {msg.data}</li>);
```

`usePresence` 返回存在消息的数组 - 每一个消息都是一种常规的 Ably JavaScript SDK `presenceMessage` 举个例子.

您可以选择提供字符串 `usePresence` 设置初始 `presence data` 绳子.

```javascript
const [presenceData, updateStatus] = usePresence("your-channel-name", "initial state");

// The `updateStatus` function can be used to update the presence data for the current client
updateStatus("new status");
```

新状态会被发送到频道,其他订阅频道的客户将立即被通知更改.

如果你不想用这个 `presenceData` 从使用中返回 Presence, 您可以配置回调

```javascript
const [_, updateStatus] = usePresence("your-channel-name", "initial state", (presenceUpdate) => {
    console.log(presenceUpdate);
});
```

使用支持对象以及字符串

```javascript
usePresence("your-channel-name", { foo: "bar" });
```

如果你正在使用 `TypeScript` 有类型的提示可以确保更新是相同的 `type` 或提供的通用类型参数:

```tsx
const TypedUsePresenceComponent = () => {
    // In this example MyPresenceType will be checked - if omitted, the shape of the initial 
    // value will be used ...and if that's omitted, `any` will be the default.

    const [val] = usePresence<MyPresenceType>("testChannelName", { foo: "bar" });

    return (
        <div role='presence'>
            {JSON.stringify(val)}
        </div>
    );
}

interface MyPresenceType {
    foo: string;
}
```

`PresenceData` 这是储存同步、每个客户元数据的好办法, 所以这里的类型特别有价值.

我们也支持提供你自己的 `Realtime` 实例 `usePresence`,如果在同一页上需要一个以上的 Ably 客户端,则可能有用 :

```javascript
import { useChannel, Realtime } from '@ably-labs/react-hooks'

const realtime = new Realtime(options);

usePresence({ channelName: "your-channel-name", realtime: realtime }, (presenceUpdate) => {
    ...
})
```

## 常见问题

### @ably-labs/react-hooks 是什么？

\[有重大意义\] 我们的 3\.0 反应钩子库的发布候选件目前作为能动-js的模块可供使用,它包括使用上下文提供者和提供API以响应连接错误和信道错误等重大改进\.注意：该包已被作者标记为弃用——This package has moved to \`ably/react\`, see https://github\.com/ably/ably-js/blob/main/docs/react\.md for instructions on how to use to the latest version

### 如何安装 @ably-labs/react-hooks？

在项目目录运行 npm install @ably-labs/react-hooks，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18\.1\.0）、react-dom（\>=18\.1\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @ably-labs/react-hooks 支持 TypeScript 吗？

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

### @ably-labs/react-hooks 支持 ESM 还是 CommonJS？

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

### @ably-labs/react-hooks 可以商用吗？

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

### @ably-labs/react-hooks 的下载量有多少？

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

### @ably-labs/react-hooks 还在维护吗？

最新版本 2\.1\.2 发布于 2023/10/30（3 年前）；至今共发布 25 个版本，其中过去 12 个月发布了 0 个；首次发布于 2021/10/16。作者已将其标记为弃用，新项目建议寻找替代方案。