用途
本技能用于在 Expo 项目中接入 CometChat React Native UI Kit v5。它聚焦于 Expo 与裸 React Native CLI 的差异部分:安装方式与原生配置。原生层之上的内容(Provider 链、init → login → render、各组件、主题、导航)与裸 RN 完全一致,无需按工具链重新推导应用代码。
适用判断:项目含 app.json/app.config.js 且带 expo 键,或 package.json 中含 expo;或用户提出“给 Expo 应用加聊天”“Expo Go 里聊天不工作”等需求。若为非 Expo 应用,应改用 cometchat-react-native-bare-patterns。前置技能 cometchat-react-native-core(安装、Provider 链、init→login→render)需先阅读,本技能不再重复。
主要能力与关键事实
Expo Go 不可用
UI Kit 附带自定义原生模块,而 Expo Go 是固定的预构建二进制,无法加载这些模块。没有变通方法、没有配置开关、代码层面也无从修复,必须使用开发构建。
症状:应用能在 Expo Go 中运行,但聊天界面崩溃或什么都不渲染,并报出 NativeModule 错误,错误信息指向 gesture-handler / svg / video 而非 CometChat,因此看起来像是不相关的问题。
生成开发构建:
npx expo run:ios # 或: npx expo run:android
此后一直使用该开发构建,而非 Expo Go。
安装包
与裸 RN 相同的包列表,外加 Expo 专属的 punycode:
npm install @cometchat/chat-uikit-react-native@5 @cometchat/chat-sdk-react-native@4
npm install @react-native-clipboard/clipboard \
react-native-svg react-native-video react-native-localize react-native-gesture-handler \
react-native-safe-area-context @react-native-async-storage/async-storage@^2.1.2 dayjs punycode
原生配置写在 app.json
这是 Expo 与裸 RN 的核心分歧:Expo 会生成原生工程,手动编辑 Info.plist 或 AndroidManifest.xml 没有意义,下一次 prebuild 会覆盖它。应在 app.json 中声明权限,由 Expo 写入:
{
"expo": {
"ios": {
"infoPlist": {
"NSCameraUsageDescription": "Camera access for video calls",
"NSMicrophoneUsageDescription": "Microphone access for voice/video calls"
}
},
"android": {
"permissions": [
"android.permission.INTERNET",
"android.permission.CAMERA",
"android.permission.MODIFY_AUDIO_SETTINGS",
"android.permission.RECORD_AUDIO",
"android.permission.ACCESS_NETWORK_STATE",
"android.permission.BLUETOOTH_CONNECT",
"android.permission.VIBRATE"
]
}
}
}
BLUETOOTH_CONNECT(Android 12+)用于让通话把音频路由到蓝牙耳机;/calls/react-native/setup 列出了它,而通话 SDK 自身的 manifest 只合并了旧版 BLUETOOTH。
不包含 READ_/WRITE_EXTERNAL_STORAGE,尽管 expo-integration 页面列出了它们:它们在现代 Android 上已是空操作(WRITE 自 11 起、READ 自 13 起),且 UI Kit 自身的 manifest 已为旧设备合并了它们。
修改 app.json 后需重新构建——仅重载 JS 不会应用原生权限变更。
Expo 上的通话
通话会引入原生 WebRTC,因此同样需要新的开发构建:
npm install @cometchat/calls-sdk-react-native@5
# 6 个必需的对等依赖——通话 SDK 声明的 peerDependencies。已固定版本;不要浮动。
npm install @react-native-async-storage/async-storage@^2.1.2 react-native-background-timer@^2.4.1 \
react-native-performance@^5.1.2 react-native-svg@^15.12.0 react-native-url-polyfill@2.0.0 \
react-native-webrtc@124.0.7
npx expo run:ios
react-native-url-polyfill 与 react-native-performance 对打包至关重要(UIKit 在模块作用域 require() 通话 SDK,因此即使只做聊天构建,Metro 也会解析其依赖;缺一个就会导致打包失败)。react-native-performance 需保持在 5.x(浮动到 ^6 会让之后每次 npm install 报 ERESOLVE)。@react-native-community/netinfo / react-native-callstats 不是声明的对等依赖——不要添加。
模拟器无法采集摄像头或麦克风——通话需在真机上验证。
使用方式
- 确认项目为 Expo 项目(app.json/app.config.js 含 expo 键,或 package.json 含 expo)。
- 先阅读 cometchat-react-native-core,掌握安装、Provider 链与 init→login→render。
- 按上述命令安装 UI Kit 及依赖(含 punycode)。
- 在 app.json 中声明 iOS infoPlist 与 Android permissions。
- 用 npx expo run:ios 或 npx expo run:android 生成开发构建,并始终使用该构建。
- 如需通话,安装 calls SDK 及 6 个固定版本的对等依赖,再重新生成开发构建。
- 原生层之上的应用代码与裸 RN 相同,无需按工具链重写。
适用场景
- 已有 Expo 配置的项目需要接入 CometChat 聊天。
- 排查“Expo Go 中聊天不工作”的问题。
- 在 Expo 上启用语音/视频通话。
限制与常见坑点
- 在 Expo Go 中测试——自定义原生模块无法加载,必须用开发构建。
- 直接编辑 ios/ 或 android/——prebuild 会覆盖,应使用 app.json。
- 忘记 punycode——Expo 专属,缺失时会表现为不相关的模块错误。
- 改 app.json 后仅重载 JS——原生配置需要重新构建。
- 期望通话在模拟器上可用——无法采集摄像头或麦克风。
验证方式
- 应用从开发构建运行,而非 Expo Go。
- npm run verify:fences:rn-v5 通过。
- 真机上:聊天渲染正常、输入框在键盘弹出后仍可用、手势有响应;若安装了通话,首次通话时出现权限提示。
暂未提供
本资料未提供收费、价格、平台支持范围、性能指标或效果数据等信息。