# @apinator/client 中文文档

规范地址：https://npmcn.com/package/%40apinator/client/

版本：2\.3\.0
npm 元数据更新时间：2026-10-25T10:56:25.611Z
中文译文更新时间：2026-11-06T17:53:04.339Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：205 kB，11 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-02-16T20:09:35.479Z
- 最新版本发布：2026-10-25T10:56:25.263Z
- 近 30 天下载量：2531（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

JavaScript 客户端 SDK for Apinator – 实时 WebSocket 消息

## 安装

```sh
npm install @apinator/client
```

也可以使用：`pnpm add @apinator/client`、`yarn add @apinator/client`、`bun add @apinator/client`

## README

# @ apiner/ 客户端

[![npm version](https://img.shields.io/npm/v/@apinator/client.svg)](https://www.npmjs.com/package/@apinator/client) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://npmcn.com/package/%40apinator/client/LICENSE) [![CI](https://img.shields.io/github/actions/workflow/status/apinator-io/sdk-js/test.yml?label=CI)](https://github.com/apinator-io/client-js/actions/workflows/test.yml)

JavaScript 客户端 SDK 用于 [定点符](https://apinator.io/) ——网络应用实时WebSocket消息.

## 特征

-   公共、私人、存在和缓存渠道
-   自动与指数备份重接
-   私人/现场频道的客户事件
-   成员追踪
-   TypeScript - 第一种带有完整类型定义
-   零依赖性 — 在任何现代浏览器中工作
-   无害环境管理、共同JS和脚本标签构建

## 安装

```bash
npm install @apinator/client
```

### 没有捆绑

另存为 `index.html` 打开它 脚本标签定义全局 `Apinator`数字 :

```html
<!DOCTYPE html>
<html>
  <body>
    <script src="https://cdn.jsdelivr.net/npm/@apinator/client@2.3.0/dist/apinator.min.js"></script>
    <script>
      const client = new Apinator({
        appKey: 'your-app-key',
        cluster: 'eu',
      });

      client.connect();

      const channel = client.subscribe('my-channel');

      channel.bind('my-event', (data) => {
        console.log('Received:', data);
      });
    </script>
  </body>
</html>
```

然后发表 `my-event` 打开 `my-channel` 从您的服务器(例如: [`@apinator/server`](https://www.npmjs.com/package/@apinator/server))并登录在浏览器控制台上.

喜欢ES模块吗? 从模块中导入 :

```html
<script type="module">
  import { Apinator } from 'https://cdn.jsdelivr.net/npm/@apinator/client@2.3.0/dist/index.mjs';
</script>
```

### 节点.js

22+节点有一个全球 `WebSocket`在旧版本上,安装 [`ws`](https://www.npmjs.com/package/ws) 并传入:

```typescript
import WebSocket from 'ws';
import { Apinator } from '@apinator/client';

const client = new Apinator({ appKey: 'your-app-key', cluster: 'eu', WebSocket });
```

没有一个人, `connect()` 日志 `No WebSocket implementation found…`,报告给 `bind('realtime:error', ...)` 移动到 `unavailable` 而不是重试.

## 快速启动

```typescript
import { Apinator } from '@apinator/client';

const client = new Apinator({
  appKey: 'your-app-key',
  cluster: 'eu',
});

client.connect();

const channel = client.subscribe('my-channel');

channel.bind('my-event', (data) => {
  console.log('Received:', data);
});
```

## 频道类型

### 公共频道

不需要认证 。 任何客户端都可以订阅.

```typescript
const channel = client.subscribe('news');
channel.bind('update', (data) => { /* ... */ });
```

### 私人频道

需要服务器侧认证 。 前缀为 `private-`。 。 。 .

```typescript
const client = new Apinator({
  appKey: 'your-app-key',
  cluster: 'eu',
  authEndpoint: '/api/realtime/auth',
});

const channel = client.subscribe('private-orders');
channel.bind('new-order', (data) => { /* ... */ });
```

### 存在频道

像私人频道,但也追踪谁被订阅。 前缀为 `presence-`。 。 。 .

```typescript
const presence = client.subscribe('presence-chat') as PresenceChannel;

presence.bind('realtime:subscription_succeeded', () => {
  console.log('Members:', presence.getMembers());
  console.log('Me:', presence.me);
});

presence.bind('realtime:member_added', (member) => {
  console.log('Joined:', member);
});

presence.bind('realtime:member_removed', (member) => {
  console.log('Left:', member);
});
```

`channel.me` 来源于已签名的 `channel_data` 由您返回 `authEndpoint`。 。 。 . 只有在 `realtime:subscription_succeeded`。 。 。 .

### 缓存通道

名为频道 `cache-`, (中文(简体) ), `private-cache-` 或者说 `presence-cache-` 保留其最后一个事件 30分钟。 订户迟到的客户端会收到 `realtime:subscription_succeeded`, (中文(简体) ), 紧接着紧紧地绑住你的手 `subscribe()`。 。 。 .

```typescript
const job = client.subscribe(`private-cache-job-${jobId}`);
job.bind('job-finished', (data) => { /* runs even if the job finished before you subscribed */ });
```

如果没有缓存( 或过期) 事件没有到达, 所以保持一个倒置, 如状态 API电话.

## 客户事件

直接从客户端从私人或存在频道触发的事件 :

```typescript
const privateChannel = client.subscribe('private-chat');
privateChannel.trigger('client-typing', { user: 'alice' });
```

## 连接国

监测连接寿命周期:

```typescript
client.bind('state_change', ({ previous, current }) => {
  console.log(`${previous} -> ${current}`);
});
```

国家: `initialized` → `connecting` → `connected` → `disconnected` 编号 : `unavailable`

## API 参考

见 [文件/参考文献](https://npmcn.com/package/%40apinator/client/docs/api-reference.md) 为全API.

## 浏览器支持

任何带有 WebSocket 的浏览器 `fetch` 支持:

-   色调 42+
-   Firefox 39+ (英语)
-   萨法里10.1+
-   边缘14+
-   勇敢 10 + 号

## 链接

-   [安装指南](https://npmcn.com/package/%40apinator/client/docs/installation.md)
-   [快速启动教程](https://npmcn.com/package/%40apinator/client/docs/quickstart.md)
-   [API 参考](https://npmcn.com/package/%40apinator/client/docs/api-reference.md)
-   [架构指南](https://npmcn.com/package/%40apinator/client/docs/architecture.md)
-   [捐款](https://npmcn.com/package/%40apinator/client/CONTRIBUTING.md)
-   [更改日志](https://npmcn.com/package/%40apinator/client/CHANGELOG.md)

## 许可证

麻省理工学院——见 [自由主义](https://npmcn.com/package/%40apinator/client/LICENSE)。 。 。 .

## 常见问题

### @apinator/client 是什么？

JavaScript 客户端 SDK for Apinator – 实时 WebSocket 消息

### 如何安装 @apinator/client？

在项目目录运行 npm install @apinator/client，或使用 pnpm add / yarn add / bun add。

### @apinator/client 支持 TypeScript 吗？

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

### @apinator/client 支持 ESM 还是 CommonJS？

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

### @apinator/client 可以商用吗？

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

### @apinator/client 的下载量有多少？

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

### @apinator/client 还在维护吗？

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