用途
本技能用于将 React Native 应用中的 CometChat UI Kit 从 v4 迁移到 v5。v5 不仅改变了 API,还改变了依赖包集合,因此需要重新安装核心技能中列出的依赖,而不是仅升级单个包。
主要变化
复合组件变为零件
v4 提供端到端组件,一个标签即可获得列表、消息视图、详情和线程。v5 移除了这些复合组件,使每个部分都可自定义。这意味着迁移不是简单的版本升级,而是对聊天屏幕的重写,需要预留相应的工作量。
16 个组件被移除
以下组件在 v5 中已确认不存在:
复合组件 → 自行拼接零件
| v4 | v5 |
|---|---|
| CometChatConversationsWithMessages | CometChatConversations + 消息屏幕 |
| CometChatUsersWithMessages | CometChatUsers + 消息屏幕 |
| CometChatGroupsWithMessages | CometChatGroups + 消息屏幕 |
| CometChatMessages | CometChatMessageHeader + CometChatMessageList + CometChatMessageComposer |
| CometChatThreadedMessages | CometChatThreadHeader 独立屏幕 |
消息屏幕由三个组件放在 flex: 1 容器中组成。列表与窗格之间的导航属于布局问题。
详情与管理屏幕 → 无替代组件
CometChatDetails、CometChatContacts、CometChatAddMembers、CometChatBannedMembers、CometChatTransferOwnership、CometChatUserMemberWrapper 均被移除。v5 没有提供等效组件,需要基于 SDK 自行构建这些屏幕:
| 屏幕 | SDK |
|---|---|
| 用户/群组详情 | CometChat.getUser · getGroup · updateGroup |
| 添加成员 | addMembersToGroup |
| 被封禁成员 | BannedMembersRequestBuilder · unbanGroupMember |
| 转移所有权 | transferGroupOwnership |
CometChatGroupMembers 仅列出活跃成员。如果 v4 应用可以封禁,那么也应该能显示和解封,否则会形成单向门。
官方示例应用中有真实实现,可参考:github.com/cometchat/cometchat-uikit-react-native/tree/v5/examples/SampleApp。这些是示例应用目录路径,不是导入路径。
通话记录详情屏幕 → 仅保留列表
CometChatCallLogDetails、CometChatCallLogHistory、CometChatCallLogParticipants、CometChatCallLogRecordings、CometChatCallLogsWithDetails 已移除。CometChatCallLogs(列表)保留;详情来自通话 SDK 中的 CometChatCalls.CallLogRequestBuilder。
主题:setter 对象 → provider
v4 使用 setter 对象设置主题,v5 改为使用 CometChatThemeProvider:
- let myTheme = new CometChatTheme({});
- myTheme.palette.setMode("dark");
+ <CometChatThemeProvider theme={{ mode: "dark" }}>
CometChatContext / CometChatProvider 已移除。使用 useTheme() 读取当前主题。
使用方式
迁移顺序
- 升级包和依赖集合;先确保构建通过,再处理 UI。
- 用三部分消息屏幕替换复合组件。
- 添加导航,使每个界面成为独立屏幕。
- 在 SDK 上重建详情/管理屏幕——这是最长的步骤,需明确范围。
- 将主题迁移到 provider。
- 在真实设备上重新检查通话和推送;原生层也发生了变化。
常见陷阱
- 将其视为版本升级——聊天屏幕被重写。
- 寻找 v5 详情组件——不存在。
- 因为没有组件而放弃被封禁成员功能——会丢失解封路径。
- 移植 v4 主题 setter——已被 provider 取代。
- 保留 v4 的单屏条件渲染——v5 应用需要导航器。
- 跳过设备测试——依赖和原生配置已改变。
验证方法
- 确保没有移除的符号出现:grep 搜索 WithMessages、CometChatDetails、CometChatMessages。
- 每个发出的符号都在 catalogs/rn-v5.json 中。
- npm run verify:fences:rn-v5 通过。
- 在设备上:每个 v4 流程仍然存在——包括查看和解封被封禁成员。
适用场景
适用于需要将 React Native 应用中的 CometChat UI Kit 从 v4 升级到 v5 的开发者。当出现以下情况时使用:"将聊天从 v4 升级到 v5"、"CometChatConversationsWithMessages 不见了"、"CometChatDetails 未找到"。
限制
- v5 不提供详情与管理屏幕的替代组件,需要自行基于 SDK 构建。
- 通话记录详情屏幕被移除,仅保留列表。
- 主题设置方式改变,需要迁移到 provider。
- 原生层发生变化,需要在真实设备上重新测试。
- 官方示例应用中的实现仅供参考,不能直接作为导入路径。