SuperAPI AI 工具集

cometchat-react-native-bare-patterns

编程与开发

查看项目

更新于 10-21 20:28

技能介绍

用途

本技能用于在 React Native CLI(裸项目)中接入 CometChat UI Kit v5。适用判断标准:项目包含真实的 ios/ 与 android/ 目录,且 app.json 中没有 expo 键。典型触发场景包括“为我的 React Native CLI 应用添加聊天”以及“安装 CometChat 后 Android 构建失败”。

前置与安装

安装命令如下:

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
cd ios && pod install && cd ..

由于开发者自行掌控 ios/ 与 android/ 目录,原生配置可直接编辑;这与 Expo 相反,Expo 中这些目录是生成的,手工修改会被覆盖。

四项不可省略的原生步骤

  1. react-native-gesture-handler 必须是入口文件的第一个导入:
import 'react-native-gesture-handler';
// …every other import after this

它必须位于 index.js 的最顶部,而非某个屏幕文件的顶部。顺序错误往往在 debug 下正常、在 release 下崩溃,这种失败形态最糟糕:本地测试通过,用户端却出问题。

  1. iOS Podfile 需要为两个传递依赖启用 modular headers。@cometchat/chat-uikit-react-native 是 Swift pod,依赖 SPTPersistentCache 与 DVAssetLoaderDelegate,二者均未定义 module。在静态库构建(React Native 默认)下,pod install 会直接失败并报错提示这两个 pod 未定义模块。需在 ios/Podfile 的 target 内添加:
target 'YourApp' do
  pod 'SPTPersistentCache', :modular_headers => true
  pod 'DVAssetLoaderDelegate', :modular_headers => true
  # …
end

随后重新运行 pod install。两个官方 CometChat 示例应用都包含这两行;集成文档未提及,因此首次 pod install 会因两个陌生传递 pod 而失败。

  1. Android 清单权限:在 android/app/src/main/AndroidManifest.xml 中至少需要 INTERNET;仅在添加通话功能时才需要摄像头/音频相关权限。应从集成页面获取完整列表,而非复制不完整的集合。

裸项目中的通话功能

npm install @cometchat/calls-sdk-react-native@5
# 6 REQUIRED peer deps — the calls SDK's declared peerDependencies. Pinned; do NOT float them.
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
cd ios && pod install && cd ..

注意:react-native-url-polyfill 与 react-native-performance 对打包至关重要(UIKit 在模块作用域 require() 通话 SDK,因此即使仅构建聊天,Metro 也会解析其 peer 依赖)。react-native-performance 需保持在 5.x(浮动到 ^6 会导致后续 npm install 出现 ERESOLVE)。@react-native-community/netinfo 与 react-native-callstats 并非声明的 peer 依赖,不要添加。

iOS 权限写入 ios/<YourApp>/Info.plist:

<key>NSCameraUsageDescription</key>
<string>Camera access for video calls</string>
<key>NSMicrophoneUsageDescription</key>
<string>Microphone access for voice/video calls</string>

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

原生变更后需重建而非重载

Metro 重载只刷新 JavaScript。新增原生模块、修改 Gradle 或 plist 后需要完整重建(npx react-native run-ios / run-android)。“我安装了却没有任何变化”几乎总是漏掉了重建。

与 Expo 相同的部分

原生层之上的一切都相同:providers、init → login → render、组件、主题、导航。仅安装与原生配置不同。

常见陷阱

gesture-handler 导入过晚——debug 正常,release 崩溃。 缺少 Podfile modular-headers 两行——pod install 失败并提示两个陌生传递 pod。 添加包后跳过 pod install——iOS 链接失败。 原生变更后重载而非重建。 把 Expo 的 app.json 权限块复制到裸应用——在那里不起作用。

验证

index.js 以 gesture-handler 导入开头。 iOS 与 Android 均能从零干净构建。 npm run verify:fences:rn-v5 通过。 真机上:聊天渲染、手势响应、输入框在键盘弹出时保持可用。同时测试 release 构建——gesture-handler 顺序问题只在那里显现。