用途
本技能用于将现有的 CometChat iOS 集成从 UI Kit v4 升级到 v5。当已有 v4 集成需要迁移到 v5,或升级后构建报错提示找不到 CometChatConversationsWithMessages 等符号时,使用本技能。
配套技能 cometchat-ios-core 描述了 v5 的目标状态,本技能是通向该状态的“对账”路径。应先依据官方指南构建(通过 cometchat-ios-core/references/docs-map.md 获取 /ui-kit/ios/upgrading-from-v4),再应用下述差异。
主要能力
主导迁移的核心变化
v4 的复合组件在 v5 中已不存在:CometChatMessages、CometChatUsersWithMessages、CometChatGroupsWithMessages、CometChatConversationsWithMessages 均被移除,为其提供配置的对象(MessageHeaderConfiguration、MessageListConfiguration、MessageComposerConfiguration)同样不再存在。
这不是重命名,而是所有权的反转。v4 提供一个包办一切的屏幕;v5 提供三个组件,并要求由你自行掌控屏幕与导航。旧代码中每一处推入复合组件的地方,都变成需要你编写的视图控制器,按 cometchat-ios-core 的黄金路径组合,并应用其五条布局规则。这部分是迁移工作的主体,属于宿主应用的设计变更,而非查找替换。
机械性差异
- 主题系统被替换:v4 的主题对象让位于
CometChatTheme的静态颜色加各组件样式对象。应从主题重新推导品牌样式,而不是移植 v4 样式代码(参见cometchat-ios-customization)。 - Setter 与属性拆分:若干 v4 setter 在 v5 中变为属性,包括样式类(
avatarStyle、badgeStyle、receiptStyle、statusIndicatorStyle、typingIndicatorStyle)、onSearchClick、onSelectedItemProceed,以及通话按钮点击处理器。 - 重命名:
set(usersRequestBuilder:)→set(userRequestBuilder:);set(subtitleView:)→set(subtitle:)、set(trailView:)→set(trailingView:)(仅限 Users/Groups,Conversations 与 GroupMembers 保留旧拼写);set(sessionID:)→set(sessionId:);set(callSettingBuilder:)→set(callSettingsBuilder:);set(onDeclineClick:)→set(onCancelClick:);列表与输入框上set(parentMessage:)→set(parentMessageId:),但线程头部仍使用set(parentMessage:)。 - 依赖:v5 仅支持 SPM(CocoaPods 正在逐步退出),并精确固定版本:kit 5.1.22 / SDK 4.1.7 / Calls 5.0.3,均需手动添加。
使用方式
先升级依赖,让编译器枚举出待办工作——报错即迁移清单。优先修复复合组件(它们会级联影响),然后处理样式,最后处理重命名。采用增量方式:宿主应用的导航、认证与设计系统保持原样。
注意事项
- 切勿混用大版本。同时存在 v4 与 v5 符号的半迁移项目无法构建。
- 移植任何符号前,先对照
catalogs/ios-v5.json检查——若目录中不存在,即表示该符号已移除;v5 文档页面提到它并不构成其存在的证据。
验证
项目构建后不残留任何 v4 符号;每个原复合组件屏幕现在都是组合屏幕,能全尺寸渲染、避让键盘并支持返回导航;主题看起来是有意设计的,而非半移植状态。