SuperAPI AI 工具集

cometchat-react-v7-core

编程与开发

查看项目

更新于 10-21 20:28

技能介绍

用途

本技能用于在 React 应用中端到端接入 CometChat 聊天功能。当用户提出“给 React 应用加聊天”“设置 CometChat 凭据”“在 React 中集成 CometChat”“展示会话与消息 UI”“构建完整聊天应用”等需求时使用。未限定范围的“加聊天”默认指一个可上线的核心聊天界面:一个 CometChatConversations 会话列表与一个消息面板配对,包裹在 CometChatErrorBoundary 中,完成尺寸设置、交互接线或隐藏、移动端折叠,而非一个裸的双栏演示,也不是完整的组合应用。

主要能力

  • 检测 React 项目与打包工具(Vite→VITE_、CRA→REACT_APP_、Next→NEXT_PUBLIC_/.env.local)。
  • 获取并校验仪表盘凭据:优先通过 CLI 从仪表盘拉取,或手动粘贴;写入框架环境变量并加入 gitignore,绝不回显 Auth Key。
  • 按固定顺序集成:启动时 init() 一次 → init 解析后 login(UID) → 在 CometChatProvider 内渲染。
  • 提供核心界面组件:CometChatConversations、CometChatMessageHeader、CometChatMessageList、CometChatMessageComposer,以及已接线的 CometChatThreadHeader、CometChatSearch。
  • 按需扩展组件:CometChatUsers、CometChatGroups、CometChatCallLogs、CometChatGroupMembers、CometChatIncomingCall。
  • 提供热路径属性映射、稳定属性与视图插槽、布局尺寸标准、主题同步、错误边界等规范。

使用方式

安装:

npm i @cometchat/chat-uikit-react@7 @cometchat/chat-sdk-javascript@4 dompurify

保留 @7/@4 主版本固定,裸安装可能解析到错误主版本。dompurify 为套件所需。语音/视频通话还需 @cometchat/calls-sdk-javascript。

凭据设置:检测 React 与打包工具,复用已有 .cometchat/env;若安装了非 v7 UI Kit 则停止并先协调版本。优先提供仪表盘拉取:按需加载 CLI(npx @cometchat/skills-cli@3 auth login),选择已有应用(provision list --json,绝不自动创建),provision use --app-id <id> --json 返回凭据并写入 .cometchat/config.json。随后由技能写入框架环境变量。

集成顺序(不变量):init() 在启动时执行一次 → login(UID) 在 init 解析后执行(用同步的 CometChatUIKit.getLoggedInUser() 守卫)→ 在 CometChatProvider 内渲染。示例代码:

import { CometChatUIKit } from "@cometchat/chat-uikit-react"; await CometChatUIKit.initFromSettings({ appId: import.meta.env.VITE_COMETCHAT_APP_ID, region: import.meta.env.VITE_COMETCHAT_REGION, credentials: { authKey: import.meta.env.VITE_COMETCHAT_AUTH_KEY }, chatSDK: { presenceSubscription: { type: "ALL_USERS" } }, }); if (!CometChatUIKit.getLoggedInUser()) await CometChatUIKit.login(UID);

login() 需要已存在的用户,绝不虚构或硬编码猜测的 UID;应询问用户或从仪表盘用户中获取。生产环境使用每用户服务端签发的 auth token 与 loginWithAuthToken,Auth Key 仅用于开发。

核心界面(黄金路径):设置 → 受守卫的 init/login → 在 CometChatErrorBoundary 内用 CometChatProvider 包裹应用 → 构建核心界面:CometChatConversations 列表与消息面板(CometChatMessageHeader + CometChatMessageList + CometChatMessageComposer)配对,由宿主状态协调选中会话与侧视图(thread | 会话内搜索 | 无),移动端折叠为单栏。

适用场景

  • 在 React 应用中添加生产就绪的核心聊天界面。
  • 配置 CometChat 凭据并完成初始化与登录。
  • 展示会话列表与消息收发界面。
  • 按需扩展为完整组合应用(用户/群组/通话标签、详情/线程/搜索侧面板、来电等)。
  • 按用户需求缩小范围(嵌入、弹窗、侧边栏)时使用对应的 placement 变体。

限制

  • 视觉构建器(VCB)不在范围内;如需集成 VCB 导出,应指向 CometChat Visual Builder 文档。
  • 本地化/RTL/无障碍由跨家族的 cometchat-i18n 与 cometchat-a11y 技能处理。
  • 生产环境不得将 Auth Key 下发到客户端。
  • 常见陷阱:安装了 v6 导致版本冲突、Region 或环境变量前缀错误、Auth Key 进入生产客户端、在 init 解析前渲染或登录。
  • 部分细节(如真实服务端搜索可能还需仪表盘开关)需自行核实。

验证

启动应用 → 确认 init() 与 login() 解析 → CometChatConversations 列表在 CometChatProvider(位于 CometChatErrorBoundary 内)中以完整尺寸渲染;打开会话 → 消息面板加载且消息可收发;点击“线程回复”打开线程面板(默认)且返回可回到列表;点击消息头搜索图标打开限定该会话的会话内搜索;会话搜索栏已接线或隐藏;窄视口下折叠为单栏。