用途
本技能用于把 CometChat Flutter v6 UI Kit 接入特定项目形态,或排查“init 该放哪里”“导航后主题重置”“密钥进了 git”等问题。它只补充给定工具链下的差异(DELTA),CometChat 侧的基础事实由 cometchat-flutter-v6-core 提供;框架机制(go_router、riverpod、--dart-define)属于 Flutter 既有知识,不是套件 API。套件符号来自目录。
配套技能(先读):cometchat-flutter-v6-core 覆盖安装、凭据、settings 资源、init→login→render,本技能假定已完成;cometchat-flutter-v6-placement 决定界面放哪里,本技能决定如何接入应用的管线。
前置与安装
由 core 覆盖,无新增包。
导航
套件内部及所有配方都使用普通 Navigator.push/pop,因此在以下方案下均可工作,无需转换其配方。
- 普通 Navigator:无需处理,core 的配方已是如此。
- go_router:把聊天页面注册为路由,用 context.push('/chat/:uid') 推入。套件自身的内部 pop 仍可用,因为 go_router 位于同一 Navigator 之上。把 init/login 门禁放在路由之上(包裹 MaterialApp.router 的 builder,或在 redirect 中拦截),确保登录解析完成前任何聊天路由都无法构建。
- auto_route:同理,等待登录的 AutoRouteGuard 是惯用门禁。
若启用通话,额外要求:在 MaterialApp 上设置 navigatorKey: CallNavigationContext.navigatorKey(→ -calls)。使用 go_router 时,把同一个 key 传入路由配置,不要另建第二个。
状态管理
套件是自包含的,每个 widget 内部驱动自己的 BLoC。无需把套件接入应用状态层,也不需要自己引入 flutter_bloc。
- bloc / cubit:从你的 auth cubit 暴露已登录用户,并据此拦截聊天路由。不要试图接管套件内部 bloc。
- riverpod:用一个 FutureProvider 执行 initFromSettings + login,聊天页面 .when(...) 依赖它,是最干净的门禁。
- provider / getx:同样形态,一个异步 init future,所有聊天相关内容置于其下。
读取套件状态:CometChatUIKit.loggedInUser 是同步 getter。列表状态请使用 widget 的 stateCallBack / onLoad,而非全局 store。
配置与密钥
initFromSettings 读取打包资源,因此无法读取 --dart-define。两种可选方案,需说明取舍并由用户选择:
- 保留 initFromSettings,在构建时从现有密钥源生成 cometchat-settings.json(由 CI 写入文件)。保留 integrationSource="ai-agent" 遥测。
- 使用经典 UIKitSettingsBuilder + CometChatUIKit.init(...) 配合 --dart-define 值。可行,但会丢失遥测归属。
无论哪种,Auth Key 最终都会进入应用包,仅限开发使用;生产环境应使用服务端签发的 auth token + loginWithAuthToken(见 core 的 lifecycle.md)。不要 gitignore 已注册的 cometchat-settings.json 资源(否则新克隆或 CI 构建会报 “No file or variants found for asset”);提交一个占位版本(不含真实 Auth Key),由开发/CI 覆盖,并用 pre-commit/CI 检查保护真实密钥。
平台设置
- Android:android/app/build.gradle.kts 中 minSdk = 26(文档中的 24 过低);INTERNET 权限;通话需摄像头/麦克风权限。
- iOS:Podfile 中 platform :ios, '15.1',然后 pod install;附件与通话需要照片/摄像头/麦克风用途说明字符串。两个下限来自 cometchat_calls_sdk,套件无条件依赖它,因此无论是否使用通话都适用(DOCS-BACKLOG D7)。
- Web:套件支持 Web,但插件支撑的功能(媒体选择器、通话)行为不同;承诺前需验证。使用同一 settings 资源运行 flutter run -d chrome。
- 桌面端:非文档化目标;如被问及,如实说明,不要猜测。
常见陷阱
- 在可重复进入的页面(或路由 builder 内)初始化 → 重复 init。应在根部只门禁一次(lifecycle.md)。
- 登录解析前聊天路由可达 → 白屏。要拦截路由,而不只是 widget。
- 期望 initFromSettings 读取 --dart-define —— 它读取的是资源。见上文。
- 为“连接”套件而添加 flutter_bloc —— 不必要;套件自己管理 bloc。
- 启用通话时出现两个 navigator key —— 路由与 CallNavigationContext 必须共用一个。
- 提交了 cometchat-settings.json —— Auth Key 进入仓库。
- 在读取资源的 init 前忘记 WidgetsFlutterBinding.ensureInitialized()。
验证
应用在你声称的每个目标平台均可构建;登录解析前聊天路由不可达;离开再返回不会重新 init;密钥不在 git 中;启用通话时,来电可从任意路由呈现。