# @cometchat/chat-uikit-react 中文文档

规范地址：https://npmcn.com/package/%40cometchat/chat-uikit-react/

版本：7\.2\.6
npm 元数据更新时间：2026-11-10T07:21:22.778Z
中文译文更新时间：2026-11-10T11:43:33.741Z
软件包许可：https://www\.cometchat\.com/legal-terms-of-service

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

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

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

- 包体积（解压后）：9.2 MB，121 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：react \>=18\.0\.0 \<21\.0\.0，react-dom \>=18\.0\.0 \<21\.0\.0，@cometchat/chat-sdk-javascript ^4\.2\.0，@cometchat/calls-sdk-javascript ^5\.0\.3
- 首次发布：2023-06-07T10:18:01.598Z
- 最新版本发布：2026-11-10T07:21:22.353Z
- 近 30 天下载量：39474（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：194（近 12 个月 40 个）

## 中文简介

准备使用 Chat UI 组件进行反应

## 安装

```sh
npm install @cometchat/chat-uikit-react
```

也可以使用：`pnpm add @cometchat/chat-uikit-react`、`yarn add @cometchat/chat-uikit-react`、`bun add @cometchat/chat-uikit-react`

## README

![CometChat](https://assets.cometchat.io/website/images/logos/banner.png)

# 用于反射的彗星聊天UI Kit

CometChat React UI Kit提供预建,可自定义的UI组件,开发者可以用来快速地将实时消息集成并调用到任何React应用程序.

![](https://npmcn.com/package/%40cometchat/chat-uikit-react/screenshots/sample_app_overview.png)

## 探索样本应用

看看这个 [样本 App](https://github.com/cometchat/cometchat-uikit-react/blob/v7/sample-app/README.md) 可以看到UI Kit在动作中具有完全功能的聊天体验,包括对话,消息,通话,以及AI功能.

## 先决条件

-   节点.js 18
-   npm 第9页
-   反应 QQ 18

## 开始

1.  联合国 [彗星聊天板](https://app.cometchat.com/) 创建账户.
2.  为获取您创建新应用程序 _应用标识_, (中文(简体) ), _地区_,以及 _Auth 密钥_。 。 。 .

## 安装

```sh
npm install @cometchat/chat-uikit-react
```

## 与 AI 编码代理集成

[彗星聊天代理技能](https://www.cometchat.com/docs/agent-skills) 教你的 AI 编码代理 如何与 CometChat React UI Kit 在 React 18+ apps 中构建 由 Vite 所建, 创建 React App , Next.js, React Router 或 Astro . 叫你的经纪人 _"给我的应用程序多聊聊"_ 它检测您的项目设置, 引导您通过一个简短的计划, 您批准, 然后直接将集成代码写入您的现有应用程序, 遵循正式的CometChat指南。 这些技能与克洛德代码,克塞尔,GitHub Copilot,Codex,Windsurf以及其他受欢迎的编码代理商合作.

在您的工程根中运行安装器( 需要节点. js 18+ ):

```sh
npx @cometchat/skills add
```

技能默认为 Claude Code 安装; pass `--ide <agent>` (例如, `--ide cursor`为不同的代理安装它们。 然后在你的经纪人中打开您的项目 并提示它 _"给我的应用程序多聊聊"_,或运行 `/cometchat`。 。 。 .

要多学多学,就去参观 [彗星聊天代理技能](https://www.cometchat.com/docs/agent-skills)。 。 。 .

## 特征

-   **对话** - 列出和管理一对一和分组聊天
-   **信件** ——带反应,线程并读取收件的丰富的消息列表
-   **通话** - 语音和视频通话记录
-   **AI 特性** ——AI动力助理聊天和智能回答
-   **他们** ——CSS自定义属性,用于全视定制
-   **本地化** ——内建多语种支持

## 测试

该项目有三个测试套房: **单位测试** (视频), **E2E测试** (布莱特),和 **故事书**。 。 。 .

### 单位测试( V)

单元测试与源文件同步进行 `*.spec.ts` 编号 : `*.spec.tsx` 包括各个部件、接线和公用事业.

**运行所有单元测试( 单通) :**

```sh
npm test
```

**覆盖运行 :**

```sh
npm run test:coverage
```

不需要浏览器或运行中的服务器 .

* * *

### 故事书

故事书为孤立地建设和测试组件提供了互动的开发环境.

**开始故事本( Dev 模式) :**

```sh
npm run storybook
```

打开时间 `http://localhost:6006`。 。 。 .

**构建静态故事书 :**

```sh
npm run build-storybook
```

* * *

### E2E 测试( Playwright)

端到端测试在 `sample-app/e2e/` 运行在现场样本应用 和真正的彗星聊天应用。 它们涵盖了完整的用户行程:登录,消息,附件,反应,线程,取针和保存,分组,呼叫,搜索,AI等.

#### 先决条件

##### 1\. 创建彗星聊天App

创建一个 **新设** 专门用于E2E测试的CometChat应用——套接字创建和删除 `e2e-*` 用户和团体,所以不要将其指向有真实数据的应用程序.

-   转到 [彗星聊天板](https://app.cometchat.com/)
-   注释下: **应用标识**, (中文(简体) ), **地区**, (中文(简体) ), **Auth 密钥**, (中文(简体) ), **REST API 密钥**

##### 2\. 允许扩展和媒体访问

在彗星聊天板中,启用:

-   **贴纸** ——并从其设置中添加贴纸包(贴纸测试至少需要一包)
-   **通话**
-   **对话高级搜索( A)**
-   **选票**
-   **协作文件**
-   **协作白板**

然后,根据 **聊天和通讯 —— 设置 —— 一般配置 —— 媒体 URL 访问**选择 **已指定 URL**。 。 。 .

> **需求** 每一个附件流—— `e2e/multi-attachment`,则 `e2e/message-composer` 附件测试和图像测试 `e2e/thread-subscription`。没有它,上传托盘永远不会解决 和那些测试暂停.

##### 3\. 创建AI代理用户

在Dashboard —— BYO代理:

-   **AI 助理聊天:** 用户编号 `ai-agent-e2e` 或者在 `AI_AGENT_UID`名称 `AI Agent E2E`,角色 `@agentic`。 。 。 .
-   **代理组聊天 :** 还有两个 `@agentic` 用户; 将其UID放入 `GROUP_AGENT_1_UID` 编号 : `GROUP_AGENT_2_UID`。代理必须连接到后端 **实际答复** ——代理组测试等待真实回复.

##### 4\. 配置环境

```bash
cd sample-app
cp .env.e2e.example .env.e2e
```

填写 `.env.e2e`数字 :

```env
COMETCHAT_APP_ID=your-app-id
COMETCHAT_REGION=us
COMETCHAT_AUTH_KEY=your-auth-key
COMETCHAT_API_KEY=your-rest-api-key
AI_AGENT_UID=ai-agent-e2e
```

`.env.e2e.example` 文档 **每个** 变量。 可选的测试仅允许特定的测试:

| 瓦尔 | 套间 |
| --- | --- |
| `E2E_BLOCKED_MIME_TYPE` | 多连接( block- MIME 测试) |
| `E2E_PIN_MESSAGES_LIMIT` | pin- 保存( pin- 限制测试, 见下文) (s) |
| `GROUP_AGENT_1_UID`, (中文(简体) ), `GROUP_AGENT_2_UID`, (中文(简体) ), `AGENTIC_GROUP_1_ID`, (中文(简体) ), `AGENTIC_GROUP_2_ID` | 代理组聊天 |

每次运行开始时,套房会打印出任何缺失的变量,并测试它会跳过哪些变量.

##### 5\. 安装依赖和 Playwright 浏览器

样本应用可以运行对你的 **本地 UI Kit 源码** (单位:千美元)`src/`)代替已公布的软件包,需要同时安装:

```bash
npm ci                       # repo root — the UI Kit's own dependencies
cd sample-app && npm ci      # the sample app
npx playwright install chromium
```

#### 运行 E2E 测试

**种子测试数据( 参数—— 安全可重运行) :**

```bash
cd sample-app
npm run e2e:seed
```

**运行所有 E2E 测试( 无头) :**

```bash
UIKIT_LOCAL=1 npm run e2e
```

`UIKIT_LOCAL=1` 使应用程序样本解析 `@cometchat/chat-uikit-react` 从 `../src`,所以测试练习 **您的本地变化**。没有它,它们就会与出版的软件包相对应 `sample-app/node_modules`。在Windows上(或使它永久化)放置 `UIKIT_LOCAL=1` 内 `sample-app/.env` 换句话说.

Playwright 启动 dev 服务器 `http://localhost:3005` 单靠自己(并重新使用您已经运行的),所以不需要在单独的终端开始. 要使用另一个端口, 设置 `E2E_PORT` 与该端口的服务器命令(例如:. `E2E_PORT=3006 E2E_WEB_SERVER_COMMAND="npx vite --port 3006 --strictPort"`) (中文(简体) ).

**运行与生产建设** ——终端用户得到什么,开始速度较慢:

```bash
UIKIT_LOCAL=1 npm run build -- --sourcemap
E2E_WEB_SERVER_COMMAND="npx vite preview --port 3005 --strictPort" npm run e2e
```

**其他模式 :**

```bash
npm run e2e:ui                                             # Playwright UI (interactive)
npm run e2e:headed                                         # visible browser
npm run e2e:debug                                          # step through
npx playwright test e2e/conversations/conversations.spec.ts  # one spec file
npx playwright test --grep "pin"                           # tests whose title matches
npx playwright test --grep @smoke                          # the core-flow smoke subset (~10 min)
```

**无障碍性:** `e2e/accessibility/axe.spec.ts` 用斧头扫描主屏幕(WCAG 2.0/2.1 A和AA). 现今存在的侵权事件在每台屏幕中列出 `e2e/accessibility/axe-baseline.json`; 扫描只失败于新的。 在确定违法行为后,从基线中删除其规则。 从当前应用程序中重新生成基线( 执行前审查 diff ): `UPDATE_AXE_BASELINE=1 npx playwright test e2e/accessibility`。 。 。 .

**打开套房:** `npm run lint:e2e` (单位:千美元)`eslint-plugin-playwright` - 更喜欢网络第一的说法,例如: `await expect(locator).toBeVisible()` 超过固定 `waitForTimeout` 睡觉). `locator.isVisible()` 不等待, 所以在给定超时时, 这是一种提示错误; 使用 `toBeVisible({ timeout })`,或 `visibleWithin()` 从 `e2e/helpers/wait.ts` 用于可选元素.

**结果:** hTML 报告写入 `playwright-report/` (单位:千美元)`npx playwright show-report`),一个机器可读摘要 `e2e-results/results.json`,以及失败的痕迹/截图 `test-results/`。 。 。 .

#### 清理

要删除所有 E2E 创建的数据并重置应用程序 :

```bash
npm run e2e:cleanup
```

#### 测试数据策略

| 聊天/ 用户 | 目的 | 由测试修改? |
| --- | --- | --- |
| **爱丽丝·约翰逊** (e2e用户-1) | 登录测试用户 | —— 说 |
| **鲍勃·史密斯** (e2e用户-2) | 静态1:1——只读测试 **参加者** 战略 | 永远不会 |
| **设计小组** (e2e-组-1) | 静态小组——平面图,小组细节 | 永远不会 |
| **战略** (e2e-组-35) | 可变组——发送/编辑/删除/阅读/反应/平分 | 对 |
| **排雷中心/发改委** (e2e组-33) | 接收信息 -- -- 私下/针口交谈测试 | QQNever - 除非测试发送来信 |
| **工程学** | 变形组——聊天接针-对接测试接针/接针 | 对 |
| **测试** | 二级可变组——用于任意(目前针口"被钉下"试验) | 对 |
| **AI 代理 E2E** | AI 助理聊天测试 | 对 |
| **Perf 用户** (用户-1) | 用于性能测量的稳定登录; 由种子创建, 从未通过清理删除 | 永远不会 |
| **查理·布朗** (e2e用户), **戴安娜・普林斯** (e2e用户-4) | 受召人和受召人;代理团体成员; 查理在开关时也会登录 | 呼唤记录增长 |
| 其他种子用户(e2e用户-5.e2e用户-35)和组(e2e-group-2.e2e-group-34) | 名单、搜索、标记和成员统计的人口 | 永远不会 |
| **AI 独行E2E**, (中文(简体) ), **AI E2E小队** (e2e-剂-组-1/2,或 `AGENTIC_GROUP_1_ID`编号 :`AGENTIC_GROUP_2_ID`(中文(简体) ) | 物剂组的测试,其中物剂在 `GROUP_AGENT_1_UID`编号 :`GROUP_AGENT_2_UID` | 对 |

> **为生成的数据所保留** 测试用这些前缀创建自己的丢弃装置,然后将其删除; `npm run e2e:cleanup` 清除任何失败的运行所剩的 。 不要创建自己的用户或组 : 组 `e2e-group-tmp-*` (贵德)和 `E2E_Test_*` (名称),用户 `e2e-user-tmp-*` 财务报告和审定财务报表 `e2e-user-journey-*` (义德.

> **工程和测试组** - 创建两个公共团体 **没错 `Engineering`** 财务报告和审定财务报表 **没错 `Testing`** (任何吉德语). 添加 `e2e-user-1` 改为 **工程学** (测试发出的信息是: `e2e-user-1` 把它列入清单,然后把它钉住) `e2e-user-2` 改为 **测试** (用来发送来信). 套房在运行时解决了两个名字,所以没有guids去env. 处理 `Testing` 作为未来测试的免费第二组.

#### Pin 保存先决条件( S)

接针/接发套房(`e2e/pin-messages`, (中文(简体) ), `e2e/save-messages`和"Pin对话"的块 `e2e/conversations`E2E应用程序需要这些:

-   **启用** 在仪表板上: `features.ux.messages.pinned.enabled`, (中文(简体) ), `features.ux.messages.saved.enabled`, (中文(简体) ), `features.ux.conversations.pinned.enabled`。 。 。 .
-   **平面消息限制 :** 设定 `features.ux.messages.pinned.limit` 改为 **页:1** 财务报告和审定财务报表 `E2E_PIN_MESSAGES_LIMIT=5` ——极限测试只运行在该上限.
-   **战略作用:** `e2e-user-1` 拥有者/管理人; `e2e-user-2` 是一个 **参加者**。UI Kit 显示 Pin/ Unpin 到 _每个_ 委员和 **服务器** 执行谁可以采取行动.
-   **参与者权限 :** 留着 **默认** 范围权限 **参加者** 角色 - **已拒绝、 拒绝、 拒绝、 已绑定的信息列表**许可测试对服务器进行现场直播 拒绝 _列名_ 无法与它们并存,因此这些测试模拟了服务器对被绑定的列表请求的许可错误——没有额外的仪表板设置或嵌入旗.
-   每个测试 **清除它自己的被钉住/保存状态 在REST上先**,所以低接针/救生帽在测试之间永远不会漏出. 对话点测试 **全系统战略** 和针 **仅限** 工程聊天(Bob 保留只读固定) .

#### 温和的先决条件

`e2e/message-actions/moderation.spec.ts` 报告一条信息,并检查 亵渎过滤器阻断一个。 两者都需要 **调和** e2E 应用程序的特性,带有 **亵渎过滤** 打开了,没有他们,那两个测试 跳过的原因。 它们只对被抛弃的用户和团体采取行动.

#### 线索订阅先决条件

`e2e/thread-subscription` 不需要自己的仪表板旗,但:

-   **贴纸** (有贴纸包)和 **选票** 必须启用( 第2步) —— “ 按消息类型自动订阅” 测试会发送一个 .
-   **已指定 URL** 必须是在(第2步)——一个测试发出一个图像.
-   运行对手 **战略** (组案件)和 **鲍勃·史密斯** 1:1——线程订阅以 1:1 以及分组方式提供,因此 1:1 案件坚持选择 _实值_ 现相.

#### 可选固定装置——多附件错误状态

两次测试 `e2e/multi-attachment/multi-attachment.spec.ts` 练习作曲家的 **被拒绝** (不可重复)上传状态. 他们需要不切实际的投入 执行(一个巨大的文件)或者依赖于仪表板配置,所以 **跳过自己 除非您添加匹配的固定符** 改为 `e2e/fixtures/`。检查是名前缀, 因此,展期由你决定(在下文所述的限度内).

**1\. 文件大小超过 - `e2e-oversize.*`**

任何大于 100 MB (任何扩展名) 的单一文件 `e2e/fixtures/`。可以生成一个:

```bash
# from sample-app/
head -c 150000000 /dev/urandom > e2e/fixtures/e2e-oversize.txt   # ~150 MB
```

**2\. 不支持文件类型 - `e2e-blocked-mime.*` + 键 `E2E_BLOCKED_MIME_TYPE`**

这个测试需要 **两者** 如果缺少任何一种,则跳过:

-   **一个固定** 名称 `e2e-blocked-mime.*` 内 `e2e/fixtures/`。其扩展必须 **没有** 为: `png`, (中文(简体) ), `mp4`, (中文(简体) ), `mp3`,或 `pdf` (因此无法与标准固定相撞). 这个 文件的字节是被上传的内容;扩展件本身除此之外不重要.
-   **`E2E_BLOCKED_MIME_TYPE`** 内 `.env.e2e`,设置到您在 仪表板(如:. `E2E_BLOCKED_MIME_TYPE=image/svg+xml`) (中文(简体) ). 测试将这个 MIME 附加到 明确上传。 是因为Playwright不能推断出一个异国情调的MIME 扩展并发送一个空的——服务器用 `mimeType is required` 联合国 _可重试_ 失败)而不是被拒绝的许可 _被拒绝_ 说明检验结果。 没有退缩: MIME必须来自此 和你说的一致.

**在哪里设定限制:** 编辑 **战略组 • 范围许可 • 管理员** 角色。 。 。 E2E套房与战略小组和e2e用户对接 `e2e-user-1` 通常为 管理员/拥有者,因此对管理员范围的MIME类型进行屏蔽可靠地适用于 上传在测试中.

#### 快速启动

```bash
npm ci                              # repo root
cd sample-app && npm ci
cp .env.e2e.example .env.e2e        # fill in credentials
npx playwright install chromium     # once
npm run e2e:seed                    # seed test data
UIKIT_LOCAL=1 npm run e2e           # run against your local UI Kit source
```

## 帮助和支持

对于项目运行或与UI Kit整合的问题,请咨询我们 [文档](https://www.cometchat.com/docs/ui-kit/react/integration-react) 或创建 [支持票](https://help.cometchat.com/hc/en-us) 或通过 [彗星聊天板](https://app.cometchat.com/)。 。 。 .

* * *

## 常见问题

### @cometchat/chat-uikit-react 是什么？

准备使用 Chat UI 组件进行反应

### 如何安装 @cometchat/chat-uikit-react？

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

### @cometchat/chat-uikit-react 支持 TypeScript 吗？

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

### @cometchat/chat-uikit-react 支持 ESM 还是 CommonJS？

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

### @cometchat/chat-uikit-react 可以商用吗？

@cometchat/chat-uikit-react 使用 https://www\.cometchat\.com/legal-terms-of-service 许可。声明的许可为 https://www\.cometchat\.com/legal-terms-of-service，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @cometchat/chat-uikit-react 的下载量有多少？

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

### @cometchat/chat-uikit-react 还在维护吗？

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