用途
本技能用于把 React 应用中的 CometChat UI Kit 从 v6 升级到 v7,即把依赖 @cometchat/chat-uikit-react 从 ^6 迁移到 ^7。适用触发场景包括“upgrade my v6 UI Kit to v7”“migrate CometChat React v6→v7”“bump @cometchat/chat-uikit-react to v7”。前置条件是项目当前使用 @cometchat/chat-uikit-react@6;若已是 @7 则无需迁移。
主要能力
技能内置了 v6→v7 的破坏性变更映射(references/migration-guide.md),该映射来自官方迁移文档以及一次真实的 v6.5.4→v7.1.0 导出差异对比。v7 目标符号已对照安装的 7.1.0 版本进行目录校验。逐属性的完整对照表则从文档迁移 .md 孪生文件获取。技能会扫描仓库中的 v6 用法,生成具体变更清单,并应用符号重命名、事件机制转换、插件机制替换、主题属性替换、本地化迁移等变更。
使用方式
迁移工作流如下:
-
检测起点。确认 package.json 中为 @cometchat/chat-uikit-react@6(若已是 @7 则停止)。记录打包器(Vite/Next/CRA/React-Router/Astro,对应环境变量前缀,参见 cometchat-react-v7-patterns),以及应用是否使用 calls、rxjs 事件、DataSource 或消息模板。在分支上操作,就地转换,绝不删除用户代码。
-
更新依赖。执行 npm install @cometchat/chat-uikit-react@7 @cometchat/chat-sdk-javascript@^4.1.13 dompurify@^3.3.1,然后 npm uninstall rxjs(v7 移除了 rxjs;dompurify 为必需,kit 在运行时导入它,按官方文档需显式安装)。若应用使用通话功能,将 Calls SDK 升级到 v7 主版本:npm install @cometchat/calls-sdk-javascript@5(v7 固定为 ^5.x)。启用通话还需在规定的 initFromSettings 路径上使用 uiKit:{callsSDK:{}},而非经典的 setCallingEnabled(true)。
-
扫描仓库中的 v6 用法。检索 references/migration-guide.md 中已移除或重命名的符号与模式,包括 CometChatDocumentBubble、CometChatCompactMessageComposer、CometChatUrlsFormatter、CometChatTextHighlightFormatter、各类 *Events(CometChatMessageEvents/CometChatGroupEvents/CometChatCallEvents/CometChatUserEvents/CometChatConversationEvents/CometChatUIEvents)、DataSource/DataSourceDecorator/ChatConfigurator、CometChatMessageTemplate 与 templates 属性、CometChatMessageList/CometChatConversations 上的 textFormatters 属性、hideError/disableLoadingState 属性、data-theme 属性、本地化相关(getLocalizedString(...)、CometChatLocalize、无前缀 i18n 键如 group_info)、CometChatUIKitLoginListener,以及已移除的独立组件(CometChatEmojiKeyboard/CometChatMediaRecorder/CometChatToast/CometChatListItem/CometChatNotificationBadge)。产出具体变更清单。
-
应用破坏性变更映射:符号重命名;RxJS Events 转为 useCometChatEvents 钩子;DataSource/ChatConfigurator 转为 CometChatMessagePlugin 与 plugins 属性;templates 属性转为 plugins(textFormatters 未被移除,需重新定位);data-theme 转为 theme 属性;通话改为 initFromSettings 上的 uiKit:{callsSDK:{}};本地化改为 v7 方法并将 v6 键映射到内置 sample_ 键(或通过实例方法 CometChatLocalize.getSharedInstance()?.addTranslation(...) 注册,而非静态方法)。对于内置映射中未包含的组件属性变更,通过 cometchat-react-v7-core/references/docs-map.md 获取逐属性对照表。
-
若尚未包裹,将聊天树包裹在 CometChatProvider 中(v7 要求其位于组件之上;init/login 仍为命令式且不变)。
-
验证。构建/类型检查通过;不再残留 v6 符号;应用在 CometChatProvider 内渲染;迁移后的事件/插件/通话正常工作。
适用场景
适用于当前使用 @cometchat/chat-uikit-react@6 的 React 项目,需要升级到 v7 并处理破坏性变更。技能假设已具备 cometchat-react-v7-core(v7 初始化/登录/渲染及 CometChatProvider)与 cometchat-react-v7-components(v7 组件目录)两个配套技能。
限制与注意事项
常见陷阱包括:残留的 rxjs 事件订阅在 v7 中不会触发,需全部转换为 useCometChatEvents;忘记 CometChatProvider 会导致上下文或“未初始化”错误;CometChatMessageTemplate/templates 属性已从组件移除,自定义消息渲染需改用 CometChatMessagePlugin 并通过 plugins 传入;textFormatters 未被移除,仍存在于 CometChatMessageComposer、气泡组件、CometChatSearch 和 CometChatMessageInformation 上,但已从 CometChatMessageList/CometChatConversations 移除,列表气泡从文本插件的 getTextFormatters() 获取格式化器;依赖漂移(缺少 dompurify 或残留 rxjs)会破坏构建;通话需在初始化设置中开启,否则通话按钮隐藏且 Calls SDK 不加载;消息列表默认使用多附件气泡(CometChatImageBubble→CometChatImagesBubble,单数 CometChatFileBubble 仍提供);不要批量移除 hideError,它已从列表组件移除但保留在 CometChatMessageComposer 上,textFormatters 同理仍存在于消息气泡组件上,需限定移除范围。