文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>即时通信 IM>聊天互动（含 UI）>全功能接入>移动端>React Native

React Native

最近更新时间：2026-03-04 16:57:10

我的收藏

本页目录：

chat-uikit-react-native 介绍

chat-uikit-react-native 是一款基于腾讯云 IM 的 React Native UI 组件库，提供了一些通用的 UI 组件，包含会话、聊天、群组等功能。基于这些精心设计的 UI 组件，您可以快速构建优雅的、可靠的、可扩展的 Chat 应用。基于 React Native 开发的 UIKit 界面风格更契合海外客户的使用习惯，而且支持国际化，欢迎接入。
chat-uikit-react-native 界面效果如下图所示：


开发环境要求

React Native 0.75.0 or ≥ 0.76.9
Node.js version 18+
JDK 17
Xcode 版本 14.0 或更高版本
Android Studio

配置开发环境

如果您是首次开发 React Native 项目，请参见 React Native 官网步骤 set-up-your-environment 配置开发环境。
在创建项目或编译项目过程中如果遇到环境问题，可以运行 npx react-native doctor 进行环境诊断。

集成 chat-uikit-react-native

说明：
如果你需要在 react-native@0.75.0 版本下使用，请参考：chat-uikit-react-native 如何在 react native 0.75.0 上运行？进行集成使用。

步骤1：创建项目（已有项目可忽略此步骤）

1. 创建一个新的 React Native 项目。
npx create-expo-app ChatApp
2. 创建项目完成后，切换进项目并初始化。
cd ChatApp && npm run reset-project

步骤2：集成 chat-uikit-react-native

通过 npm / yarn 方式下载 chat-uikit-react-native 并在项目中使用，您也可在此基础上进行二次开发。
npm
yarn
npm install @tencentcloud/chat-uikit-react-native
yarn add @tencentcloud/chat-uikit-react-native
安装 expo-image-picker、expo-document-picker、 expo-video 富媒体插件。
npx expo install expo-image-picker expo-document-picker expo-video
在 app.json 中配置 expo-image-picker、expo-document-picker、 expo-video 富媒体插件和相关权限。 

{
  "expo": {
    ...
    "plugins": [
      ...
      [
        "expo-image-picker",
        {
          "photosPermission": "The app accesses your photos to let you share them with your friends.",
          "colors": {
            "cropToolbarColor": "#000000"
          },
          "dark": {
            "colors": {
              "cropToolbarColor": "#000000"
            }
          }
        }
      ],
      [
        "expo-document-picker",
        {
          "iCloudContainerEnvironment": "Production"
        }
      ],
      "expo-video"
    ],
    "android": {
      ...
      "permissions": [
        "android.permission.READ_MEDIA_IMAGES",
        "android.permission.READ_MEDIA_AUDIO",
        "android.permission.READ_MEDIA_VIDEO",
        "android.permission.READ_EXTERNAL_STORAGE",
        "android.permission.WRITE_EXTERNAL_STORAGE"
      ]
    },
    "ios": {
      ...
      "infoPlist": {
        "NSCameraUsageDescription": "This app needs access to camera to take photos and videos for sharing.",
        "NSMicrophoneUsageDescription": "This app needs access to microphone to record audio messages.",
        "NSPhotoLibraryUsageDescription": "This app needs access to photo library to select images and videos for sharing.",
        "NSPhotoLibraryAddUsageDescription": "This app needs access to save photos to your photo library."
      }
    }
  }
}

步骤3：引入 chat-uikit-react-native

说明：
以下代码中未填入 SDKAppID、userID 和 userSig，需在步骤5 中获取相关信息后进行替换。
为了尊重版权，IM Demo/TUIKit 工程中默认不包含大表情元素切图。在正式上线商用前，请您替换为自己设计或拥有版权的其他表情包。请注意，下图所示的默认小黄脸表情包版权属于腾讯云，您可以通过升级至 IM 企业版套餐 免费使用该表情包。



示例是使用 expo-router 进行路由管理（Expo 创建项目已内置，如果没有，请参考： expo-router 接入）。
App.tsx
Screens.tsx
说明：
以下代码中未填入 SDKAppID、userID 和 userSig，需在步骤5中获取相关信息后进行替换。
替换 app/index.tsx 中的内容，或者您可以新建一个组件引入。
import { TUITranslateService } from '@tencentcloud/chat-uikit-engine';
import { TUILogin } from '@tencentcloud/tui-core';
import React, { useState } from 'react';
import {
  Image,
  StyleSheet,
  Text,
  TouchableOpacity,
  View,
} from 'react-native';
import { ChatScreen, ChatSettingScreen, ConversationListScreen } from './Screens';
import { UIKitProvider } from '@tencentcloud/chat-uikit-react-native';
import resources from '@tencentcloud/chat-uikit-react-native/i18n';

type ScreenType = 'login' | 'conversation-list' | 'chat' | 'chat-setting';

const App = () => {
  const [currentScreen, setCurrentScreen] = useState<ScreenType>('login');
  const [screenStack, setScreenStack] = useState<ScreenType[]>(['login']);

  // Init localization
  TUITranslateService.provideLanguages(resources);
  TUITranslateService.useI18n('en-US');

  const navigateTo = (screen: ScreenType) => {
    setScreenStack(prev => [...prev, screen]);
    setCurrentScreen(screen);
  };

  const navigateBack = () => {
    if (screenStack.length > 1) {
      const newStack = screenStack.slice(0, -1);
      setScreenStack(newStack);
      setCurrentScreen(newStack[newStack.length - 1]);
    }
  };
  
  // Login
  const Login = () => {
    TUILogin.login({
      SDKAppID: 0, // Your SDKAppID
      userID: '', // Login UserID
      userSig: '', // Login userSig
      useUploadPlugin: true,
      framework: 'rn',
    }).then(() => {
      navigateTo('conversation-list');
    });
  };

  const LoginScreen = () => (
    <UIKitProvider>
      <View style={styles.container}>
        <Image
          style={styles.logo}
          source={{uri:'https://web.sdk.qcloud.com/im/assets/images/tencent_rtc_logo.png'}}
        />
        <TouchableOpacity style={styles.buttonContainer} onPress={Login}>
          <Text style={styles.buttonText}>Log in</Text>
        </TouchableOpacity>
      </View>
    </UIKitProvider>
  );

  const renderScreen = () => {
    switch (currentScreen) {
      case 'login':
        return <LoginScreen />;
      case 'conversation-list':
        return <ConversationListScreen navigateTo={navigateTo} />;
      case 'chat':
        return <ChatScreen navigateTo={navigateTo} navigateBack={navigateBack} />;
      case 'chat-setting':
        return <ChatSettingScreen navigateTo={navigateTo} navigateBack={navigateBack} />;
      default:
        return <LoginScreen />;
    }
  };

  return renderScreen();
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    backgroundColor: '#FFFFFF',
  },
  logo: {
    width: 232,
    height: 80,
  },
  buttonContainer: {
    width: '80%',
    justifyContent: 'center',
    alignItems: 'center',
    paddingVertical: 11,
    borderRadius: 5,
    backgroundColor: '#2F80ED',
  },
  buttonText: {
    fontSize: 18,
    lineHeight: 24,
    color: '#FFFFFF',
  },
});

export default App;
在与 app/index.tsx 文件相同的目录中创建一个新的 Screens.tsx 文件。
import React from 'react';
import { Chat, ChatSetting, ConversationList, UIKitProvider } from '@tencentcloud/chat-uikit-react-native';

type ScreenType = 'login' | 'conversation-list' | 'chat' | 'chat-setting';

interface NavigationProps {
  navigateTo: (screen: ScreenType) => void;
  navigateBack?: () => void;
}

// Conversation List Screen Component
export const ConversationListScreen = ({ navigateTo }: NavigationProps) => {
  const onPressConversation = () => {
    navigateTo('chat');
  };

  return (
    <UIKitProvider>
      <ConversationList onPressConversation={onPressConversation} />
    </UIKitProvider>
  );
};

// Chat Screen Component
export const ChatScreen = ({ navigateTo, navigateBack }: NavigationProps) => {
  const handleNavigateBack = () => {
    navigateBack?.();
  };
  
  const navigateToChatSetting = () => {
    navigateTo('chat-setting');
  };

  return (
    <UIKitProvider>
      <Chat
        navigateBack={handleNavigateBack}
        navigateToChatSetting={navigateToChatSetting}
      />
    </UIKitProvider>
  );
};

// Chat Setting Screen Component
export const ChatSettingScreen = ({ navigateTo, navigateBack }: NavigationProps) => {
  // Navigate to Chat when you click header back button.
  const handleNavigateBack = () => {
    navigateBack?.();
  };
  
  // Navigate to Chat when you click the send message button.
  const navigateToChat = () => {
    navigateBack?.();
  };
  
  // Navigate to ConversationList when you disband group or leave group.
  const navigateToConversationList = () => {
    navigateTo('conversation-list');
  };

  return (
    <UIKitProvider>
      <ChatSetting
        navigateBack={handleNavigateBack}
        navigateToChat={navigateToChat}
        navigateToConversationList={navigateToConversationList}
      />
    </UIKitProvider>
  );
};

步骤4： 获取 SDKAppID 、userID 与 userSig

设置 Login 中的相关参数 SDKAppID 、userID 以及对应的 userSig :
SDKAppID 信息，可通过 即时通信 IM 控制台 获取:

userID 信息，可通过单击 即时通信 IM 控制台 > 账号管理，切换至目标应用所在账号，即可创建账号并获取 userID。

userSig 信息，可单击 即时通信 IM 控制台 > 开发工具 > UserSig生成&校验，填写创建的 userID，即可生成 userSig。


步骤5：编译并运行项目

编译并运行项目您需要使用真机或模拟器，推荐使用真机运行。您可以参见 React Native 官网 running-on-device 连接真机进行调试。
替换 App.tsx 中的 SDKAppID、userID、userSig，然后运行命令如下：
Android
iOS
1. 手机开启开发者模式，打开 USB 调试开关。
2. 用 USB 连接手机，推荐选择 传输文件 选项，不要选择 仅充电 选项。
3. 确认手机连接成功后，执行 npm run android 编译运行项目。
npm run android
1. 用 USB 连接手机，用 Xcode 打开工程的 ios 目录。
2. 按照 React Native 官网 running-on-device 配置签名信息。
3. 进入 ios 目录下安装依赖。
cd ios
pod install
4. 回退到根目录，执行 npm run ios 编译运行项目。
cd ../
npm run ios

步骤6：发送第一条消息

1. 项目启动之后单击左上角发起会话。
2. 进入发起会话窗口。在搜索栏输入 步骤5 中创建的 userID（test_2），选中后打开会话。
3. 在输入框中输入消息并点击发送。


常见问题

运行时环境报错怎么办？

可以执行以下命令，进行环境诊断。
npx react-native doctor

chat-uikit-react-native 如何在 react native 0.75.0 上运行？

通过 npm / yarn 方式下载 chat-uikit-react-native@1.1.0 ，并参考 chat-uikit-react-native@1.1.0 接入文档进行集成。
npm
yarn
npm install @tencentcloud/chat-uikit-react-native@1.1.0 react-native-image-picker react-native-document-picker react-native-video
yarn add @tencentcloud/chat-uikit-react-native@1.1.0 react-native-image-picker react-native-document-picker react-native-video

相关文档

UIKit 相关：

chat-uikit-react-native npm

中国站
目录