# @arkstack/realtime 中文文档

规范地址：https://npmcn.com/package/%40arkstack/realtime/

版本：0\.22\.2
npm 元数据更新时间：2026-11-07T13:59:20.606Z
中文译文更新时间：2026-11-06T19:42:33.842Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40arkstack/realtime
原文对照：https://npmcn.com/package/%40arkstack/realtime/?lang=original
项目主页：https://arkstack.toneflix.net/guide/notifications
源码仓库：https://github.com/arkstack-hq/arkstack

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

- 包体积（解压后）：52 kB，13 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：0 个
- peer 依赖：vue ^3\.4\.0，react \>=18，firebase ^11\.0\.0，pusher-js ^8\.4\.0
- 首次发布：2026-07-07T06:52:05.282Z
- 最新版本发布：2026-11-07T13:59:20.442Z
- 近 30 天下载量：2451（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：62（近 12 个月 62 个）

## 中文简介

消费Arkstack实时通知的客户端(Pusher/Firebase),框架-不可知核心外加React和Vue绑定.

## 安装

```sh
npm install @arkstack/realtime
```

也可以使用：`pnpm add @arkstack/realtime`、`yarn add @arkstack/realtime`、`bun add @arkstack/realtime`

## README

# @ arkstack/ 实时

[![@arkstack/realtime](https://img.shields.io/npm/dt/@arkstack/realtime?style=flat-square&label=@arkstack/realtime&link=https%3A%2F%2Fwww.npmjs.com%2Fpackage%2F@arkstack/realtime)](https://www.npmjs.com/package/@arkstack/realtime)

消费的客户 [阿克斯达克](https://arkstack.toneflix.net/) 实时通知。 框架不可知核外加反应和Vue绑定 [推进器](https://pusher.com/channels) 或者说 [火地云通讯](https://firebase.google.com/docs/cloud-messaging)。 。 。 .

与 `realtime` 通知驱动程序 [`@arkstack/notifications`](https://www.npmjs.com/package/@arkstack/notifications),用于广播每个用户的频道(`user.<id>`该客户端订阅 .

## 安装

```sh
pnpm add @arkstack/realtime
```

然后安装您传输的客户端 SDK( 两者都是可选的对等依赖性—— 只安装您使用的一个):

```sh
pnpm add pusher-js   # Pusher transport
pnpm add firebase    # Firebase transport
```

## 使用量

创建客户端并订阅用户频道. `subscribe`编号 :`forUser` 解析到未订阅函数.

```ts
import { createRealtime } from '@arkstack/realtime'

const realtime = createRealtime({
  transport: 'pusher',
  pusher: {
    key: import.meta.env.VITE_PUSHER_KEY,
    cluster: 'mt1',
    authEndpoint: '/broadcasting/auth',
  },
})

const unsubscribe = await realtime.forUser(user.id, (notification) => {
  console.log(notification.title, notification.description)
})

// later
unsubscribe()
await realtime.disconnect()
```

### 客户事件

推进器私人和存在频道可以发送ephemeral客户端事件(往往) 叫做低语。 发送事件前订阅频道 :

```ts
const stopTyping = await realtime.listenForWhisper('private-room.7', 'typing', ({ userId }) =>
  console.log(`${userId} is typing`),
)

await realtime.whisper('private-room.7', 'typing', { userId: user.id })
stopTyping()
```

这个 `client-` 前缀自动添加。 Pusher 发送客户端事件过它 私人/现场频道。 Firebase 使用实时数据库发布同样内容 互联客户端的电平事件. 使用 `listen(channel, event, handler)` 财务报告和审定财务报表 `trigger(channel, event, payload)` 当您需要低级API时 确切的事件名称.

每个 `notification` 匹配服务器所播放的有效载荷 :

```ts
interface RealtimeNotification {
  id: string
  type: string | null
  title: string
  description: string
  actionText?: string | null
  actionLink?: string | null
  meta?: Record<string, unknown> | null
  read_at: string | null
  created_at: string
}
```

## 反应

```tsx
import { useNotifications } from '@arkstack/realtime/react'

function Bell({ realtime, userId }) {
  const { notifications, latest, clear } = useNotifications(realtime, realtime.channelFor(userId), { limit: 20 })

  return (
    <span onClick={clear}>
      {notifications.length} · {latest?.title}
    </span>
  )
}
```

钩子会累积通知( 最新的第一个), 封顶于 `limit`,然后在卸载时或何时自动取消订阅 `client`编号 :`channel` 变化.

## 阴道

```vue
<script setup>
import { useNotifications } from "@arkstack/realtime/vue";

const props = defineProps(["realtime", "userId"]);
const { notifications, latest, clear } = useNotifications(
  props.realtime,
  props.realtime.channelFor(props.userId),
  { limit: 20 },
);
</script>

<template>
  <span @click="clear">{{ notifications.length }} · {{ latest?.title }}</span>
</template>
```

当组件范围被处理时,可堆放的不订阅自动进行.

## 基地

Firebase Cloud 消息传送给设备(通过 `onMessage`),因此通知用事件名称而不是频道匹配:

```ts
const realtime = createRealtime({
  transport: 'firebase',
  firebase: {
    apiKey: import.meta.env.VITE_FIREBASE_API_KEY,
    projectId: import.meta.env.VITE_FIREBASE_PROJECT_ID,
    appId: import.meta.env.VITE_FIREBASE_APP_ID,
    messagingSenderId: import.meta.env.VITE_FIREBASE_SENDER_ID,
    databaseURL: import.meta.env.VITE_FIREBASE_DATABASE_URL,
  },
})
```

Firebase 客户端活动记录如下: `arkstack/client-events` 实时 数据库出版后立即被移除. 配置消防基地安全 您认证的客户端可以读取和写入频道规则 。 覆盖 根为 `firebase.clientEventsPath` 需要的时候.

## 自定义运输

提供 `transportFactory` 以连接任何后端(原始 WebSocket, SSE, 测试双版,...):

```ts
import { createRealtime, type RealtimeTransport } from '@arkstack/realtime'

const transport: RealtimeTransport = {
  subscribe(channel, event, handler) {
    const socket = new WebSocket(`wss://example.test/${channel}`)
    socket.addEventListener('message', (e) => {
      const { event: name, payload } = JSON.parse(e.data)
      if (name === event) handler(payload)
    })

    return { channel, unsubscribe: () => socket.close() }
  },
  disconnect() {},
}

const realtime = createRealtime({ transportFactory: () => transport })
```

## API 密码

-   `createRealtime(config)` - 创建一个 `RealtimeClient`配置 : `transport` (单位:千美元)`'pusher'` | `'firebase'`, (中文(简体) ), `event` (默认) `notification`, (中文(简体) ), `channelPrefix` (默认) `user.`, (中文(简体) ), `pusher`编号 :`firebase` 证书,或自定义 `transportFactory`。 。 。 .
-   `client.subscribe(channel, handler)` 编号 : `client.forUser(userId, handler)` ——订阅;返回一个未订阅的函数.
-   `client.listen(channel, event, handler)` ——听一听任意事件.
-   `client.listenForWhisper(channel, event, handler)` 编号 : `client.whisper(channel, event, payload)` ——接收并发送Pusher客户端事件.
-   `client.trigger(channel, event, payload)` ——通过支持它的运输机发出确切的事件名称.
-   `client.channelFor(userId)` ——每个用户频道名.
-   `client.disconnect()` ——拆解运输接通.
-   `@arkstack/realtime/react` —— 说 `useNotifications(client, channel, { limit? })` → `{ notifications, latest, clear }`。 。 。 .
-   `@arkstack/realtime/vue` —— 说 `useNotifications(client, channel, { limit? })` → `{ notifications, latest, clear, stop }`。 。 。 .

见 [通知指南](https://arkstack.toneflix.net/guide/notifications) 用于服务器侧.

## 许可证

麻省理工学院

## 常见问题

### @arkstack/realtime 是什么？

消费Arkstack实时通知的客户端\(Pusher/Firebase\),框架-不可知核心外加React和Vue绑定\.

### 如何安装 @arkstack/realtime？

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

### @arkstack/realtime 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/arkstack\_\_realtime 是否存在。

### @arkstack/realtime 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @arkstack/realtime 可以商用吗？

@arkstack/realtime 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @arkstack/realtime 的下载量有多少？

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

### @arkstack/realtime 还在维护吗？

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