用途
本技能面向 CometChat React Native 聊天 SDK 的无头(headless)使用路径。核心规则是:任何功能先检查 UI Kit 是否已有组件,有则用组件;只有当 UI Kit 没有对应组件时,才回退到直接使用 SDK。在 React Native 上这种回退并不罕见,因为 Kit v5 移除了详情与管理类界面,以下需求完全没有组件,只能纯 SDK 实现:用户/群组详情(CometChatDetails 在 v5 被移除)、添加成员(CometChatAddMembers 被移除)、查看/解封被封禁成员(完全没有 UI 界面)、转移所有权(CometChatTransferOwnership 被移除)、通话记录详情(只提供列表)。
主要能力
技能提供两份映射文档。references/page-map.md 是主索引,按页面组织(类似 JavaScript SDK 仓库),共 37 个页面,从实时文档派生,给出「意图 → 文档页 → 该页演示的方法 → RN 页面未携带的契约事实」。references/method-map.md 是按方法组织的配套文档,共 80 个方法,127/127 全部覆盖,给出精确签名、返回类型与约束。两份文档都从同一套回退阶梯开始:这些映射覆盖 SDK 的大部分而非全部,因此「未列出」绝不等于「不存在」;第二级是目录(catalog),目录才是存在性的权威依据。page-map.md 对每个方法回答:签名、resolve 出什么、reject 什么、前置条件,以及它会拒绝做什么——最后一点最重要,它记录了文档页面无法通过省略表达的否定事实,例如不存在 sendCardMessage(),卡片消息是只收不发。每行标记为 D(有 RN 文档支撑)或 T(因 RN 页面内容单薄而从 .d.ts 恢复,RN-G15);T 行不应被当作已文档化内容呈现。
使用方式
安装:SDK 随 UI Kit 一起发布,若已安装 core 则本 SDK 也已安装。纯无头应用可单独安装:
npm install @cometchat/chat-sdk-react-native@4 @react-native-async-storage/async-storage@^2.1.2
注意不要安装 @cometchat/chat-sdk-javascript,那是 Web 包。
顺序不变量:initFromSettings 必须先 resolve,之后才能 login();login() 必须先 resolve,之后才能拉取或发送。否则会静默失败而非抛错。示例:
import { CometChat } from "@cometchat/chat-sdk-react-native";
await CometChat.initFromSettings({ appId: APP_ID, region: REGION, credentials: { authKey: AUTH_KEY }, // 仅开发用;生产用 auth token 登录 chatSDK: { presenceSubscription: { type: "ALL_USERS" } }, // 等价于旧的 .subscribePresenceForAllUsers() }); await CometChat.login(UID, AUTH_KEY); // 仅开发用;生产传 auth token
回退路径(非 skills / 跟随文档的上下文)为公开文档化的经典写法:new CometChat.AppSettingsBuilder().setRegion(REGION).subscribePresenceForAllUsers().autoEstablishSocketConnection(true).build(),再 await CometChat.init(APP_ID, settings)。注意 login 在 .d.ts 中是可变参数且无类型(login(...args: any)),TypeScript 不会捕获错误调用;两种真实形态是 login(uid, authKey) 与 login(authToken)。
监听器生命周期:addMessageListener 返回 void 而非订阅对象,字符串 id 是唯一句柄;SDK 持有监听器而非 React,因此它会跨导航与卸载存活。必须在清理函数中调用 CometChat.removeMessageListener(id),省略清理是重复消息的首要原因,且应用运行越久越严重。
拉取始终使用 builder:列表分页通过 new CometChat.XRequestBuilder().setLimit(n).build() 再 .fetchNext();返回空数组表示结束,不会抛错;不存在裸的 getMessages()。
适用场景
需要自建聊天 UI、只要数据层、在 React Native 中发送消息;排查重复消息、监听器泄漏、历史消息分页;以及上述 UI Kit 已移除组件的详情与管理类功能。
限制与常见陷阱
省略监听器清理会导致重复消息随时间增长;调用裸 sendMessage() 无效,所有内容都命名空间在 CometChat 下;不要臆造 sendCardMessage(),卡片消息只收不发;不要 await startTyping,它返回 void;getLoggedinUser() 返回 null 是正常的无会话结果而非错误(注意是小写 in);封禁必须配套解封,CometChatGroupMembers 只显示活跃成员,需接 BannedMembersRequestBuilder 与 unbanGroupMember;不要在 login resolve 之前注册推送 token,否则它不属于任何用户。验证方式:每个符号都出现在 catalogs/rn-sdk-v4.json 中;npm run verify:fences:rn-v5 通过;每个 addListener 在拆卸路径上都有对应的 removeListener;分页、错误处理与封禁往返均已接通,而非只走通顺路径。