# @convex-dev/presence 中文文档

规范地址：https://npmcn.com/package/%40convex-dev/presence/

版本：0\.4\.0
npm 元数据更新时间：2026-10-07T00:51:48.140Z
中文译文更新时间：2026-11-10T17:42:46.942Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：191 kB，77 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react ~18\.3\.1 \|\| ^19\.0\.0，convex ^1\.36\.1，react-dom ~18\.3\.1 \|\| ^19\.0\.0，expo-crypto \>=14\.1\.0，react-native \>=0\.79\.0
- 首次发布：2025-05-28T02:46:58.175Z
- 最新版本发布：2026-07-21T00:07:17.036Z
- 近 30 天下载量：553910（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：25（近 12 个月 7 个）

## 中文简介

存在功能的对流组件.

## 安装

```sh
npm install @convex-dev/presence
```

也可以使用：`pnpm add @convex-dev/presence`、`yarn add @convex-dev/presence`、`bun add @convex-dev/presence`

## README

# 存在对流组件

[![npm version](https://badge.fury.io/js/@convex-dev%2Fpresence.svg)](https://badge.fury.io/js/@convex-dev%2Fpresence)

用于管理存在功能的 Convex 组件,即实时更新 在“房间”中的用户列表,包括他们上次上网时的状况.

![Demo of presence component](https://raw.githubusercontent.com/get-convex/presence/main/presence.gif)

在没有任何民意测验的情况下有效派驻人员可能十分困难 每次用户发送心跳消息时,不重复运行查询. 这个 部门通过单一的全部署工作人员落实存在(a) [批发工人](https://github.com/get-convex/batch-worker) 睡觉 直到下一次会话超时到期, 这样客户端只能收到更新 当用户加入或离开房间时,心跳不会安排任何工作.

此组件最常用的用例是通过使用Presence hook,它 注意向服务器发送心胸信息并优雅 关闭标签时断开用户.

[![The Presence Component Video](https://img.youtube.com/vi/ZZTm_NtWJrs/0.jpg)](https://www.youtube.com/watch?v=ZZTm_NtWJrs)

## 安装

```bash
npm install @convex-dev/presence
```

## 实例

见 `example` 对于如何使用此组件的简单示例的目录. 这个 `example-with-auth` 目录显示如何使用组件 认证.

有个主机版 `example-with-auth` 时间 [https:// presence.previews.convex.dev 页面存档备份,存于互联网档案馆](https://presence.previews.convex.dev/)。 。 。 .

## 使用量

首先,在您的 Convex 应用程序中添加组件:

`convex/convex.config.ts`

```ts
import { defineApp } from "convex/server";
import presence from "@convex-dev/presence/convex.config.js";

const app = defineApp();
app.use(presence);
export default app;
```

`convex/presence.ts`

```ts
import { mutation, query } from "./_generated/server";
import { components } from "./_generated/api";
import { v } from "convex/values";
import { Presence } from "@convex-dev/presence";

export const presence = new Presence(components.presence);

export const heartbeat = mutation({
  args: {
    roomId: v.string(),
    userId: v.string(),
    sessionId: v.string(),
    interval: v.number(),
  },
  handler: async (ctx, { roomId, userId, sessionId, interval }) => {
    // TODO: Add your auth checks here.
    return await presence.heartbeat(ctx, roomId, userId, sessionId, interval);
  },
});

export const list = query({
  args: { roomToken: v.string() },
  handler: async (ctx, { roomToken }) => {
    // Avoid adding per-user reads so all subscriptions can share same cache.
    return await presence.list(ctx, roomToken);
  },
});

export const disconnect = mutation({
  args: { sessionToken: v.string() },
  handler: async (ctx, { sessionToken }) => {
    // Can't check auth here because it's called over http from sendBeacon.
    return await presence.disconnect(ctx, sessionToken);
  },
});
```

A 类 `Presence` 反应组件可以从您的客户端代码中即时化 这个:

`src/App.tsx`

```tsx
import { api } from "../convex/_generated/api";
import usePresence from "@convex-dev/presence/react";
import FacePile from "@convex-dev/presence/facepile";

export default function App(): React.ReactElement {
  const [name] = useState(() => "User " + Math.floor(Math.random() * 10000));
  const presenceState = usePresence(api.presence, "my-chat-room", name);

  return (
    <main>
      <FacePile presenceState={presenceState ?? []} />
    </main>
  );
}
```

这用的是基本的 `FacePile` 包含在这个软件包中的组件,但您可以 很容易复制此代码并使用 `usePresence` 直接钩线执行您的 自己的风格.

### 反应原生支持

如果您在使用 React Natural ,请安装这些可选的依赖性 :

```sh
npx expo install react-native expo-crypto
```

然后导入 `usePresence` 钩从 `@convex-dev/presence/react-native`数字 :

```ts
import { usePresence } from "@convex-dev/presence/react-native";
```

_说明: 组件目前没有反应原生 等同,但你可以很容易地创建自己的._

## 其他功能

系统组件接口 `Presence` 类的定义 `src/client/index.ts`它包括维持存在的额外职能 状态,用于查询特定用户或房间的存在.

例如,你可以使用 `listUser` 函数来检查用户是否在线 房间.

联系或加入 [Convex迪斯科德社区](https://convex.dev/community) 如果你有任何问题或反馈!

## 常见问题

### @convex-dev/presence 是什么？

存在功能的对流组件\.

### 如何安装 @convex-dev/presence？

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

### @convex-dev/presence 支持 TypeScript 吗？

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

### @convex-dev/presence 支持 ESM 还是 CommonJS？

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

### @convex-dev/presence 可以商用吗？

@convex-dev/presence 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @convex-dev/presence 的下载量有多少？

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

### @convex-dev/presence 还在维护吗？

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