SuperAPI AI 工具集

cometchat-react-native-expo-patterns

编程与开发

查看项目

更新于 10-21 20:29

技能介绍

用途

本技能用于在 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 不是声明的对等依赖——不要添加。

模拟器无法采集摄像头或麦克风——通话需在真机上验证。

使用方式

  1. 确认项目为 Expo 项目(app.json/app.config.js 含 expo 键,或 package.json 含 expo)。
  2. 先阅读 cometchat-react-native-core,掌握安装、Provider 链与 init→login→render。
  3. 按上述命令安装 UI Kit 及依赖(含 punycode)。
  4. 在 app.json 中声明 iOS infoPlist 与 Android permissions。
  5. 用 npx expo run:ios 或 npx expo run:android 生成开发构建,并始终使用该构建。
  6. 如需通话,安装 calls SDK 及 6 个固定版本的对等依赖,再重新生成开发构建。
  7. 原生层之上的应用代码与裸 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 通过。
  • 真机上:聊天渲染正常、输入框在键盘弹出后仍可用、手势有响应;若安装了通话,首次通话时出现权限提示。

暂未提供

本资料未提供收费、价格、平台支持范围、性能指标或效果数据等信息。