React 框架集成 IM UIKit - IM 即时通讯（含 UI）

开发者中心

IM 即时通讯（含 UI）

集成开发

React 框架集成 IM UIKit

更新时间： 2024/03/15 18:26:21

本文旨在让新手快速了解如何集成云信即时通讯组件库（IM UIKit）。在本教程中，您可以体验集成 IM UIKit 的基本流程和 IM UIKit 提供的 UI 界面。您也可以前往 Github 参考 IM UIKit 的源码。

本文介绍如何基于 React 框架集成 IM UIKit。

如果需要基于 Vue 或其他 Web 开发框架集成 IM UIKit，请参见非 React 框架集成 IM UIKit。

集成效果示例

前提条件

开始前，请确保您已：

已在云信控制台创建应用，获取 App Key。
已注册云信 IM 账号，获取 accid 和 token。
已准备如下开发环境：
- React 建议使用版本： 16.8.0 <= 建议版本 < React 18.0.0
- React DOM 建议使用版本： React DOM 16.8.0 <= 建议版本 < React DOM 18.0.0

实现流程

步骤1：按需导入组件

通过 NPM 方式将 IM UIKit 安装到您的 Web 项目中。

示例代码如下：
```
$ npm install @xkit-yx/im-kit-ui --save
```
目前仅支持 npm 方式集成，暂不支持 CDN 方式集成。

将 IM UIKit 组件导入到您的 React 项目中。详细说明可参考组件导入。

以导入会话列表组件和会话消息组件为例，示例代码如下：

import {
  Provider, // 全局上下文
  ConversationContainer, // 会话列表组件
  ChatContainer, // 聊天（会话消息）组件
} from '@xkit-yx/im-kit-ui'

//如果您希望引入组件 css：
import "@xkit-yx/im-kit-ui/es/style/css";
//如果您希望引入组件 less：
import "@xkit-yx/im-kit-ui/es/style";

建议引入组件的 css 或 less（两者选其一）。

步骤2：初始化

初始化 IM UIKit 需要传入必传参数 sdkVersion 和 initOptions。更多初始化详情请参见初始化。

sdkVersion：传入1或2选择基于哪个 IM SDK 集成 IM UIKit。1 表示基于 NIM Web SDK；2表示基于 NIM Web SDK 的含圈组版（NIM Web Elite SDK）
initOptions：用于初始化的参数

初始化示例代码如下：

import React from 'react'
import { Provider } from '@xkit-yx/im-kit-ui'

const App = () => {
  const initOptions = {
    appkey: '',  // 传入您的App Key
    account: '', // 传入您的云信 IM 账号
    token: '',   // 传入您的 Token 
    debugLevel: 'debug', // 设置日志level
    // 参考 NIM SDK 的 initOptions
  }

  return (
    <Provider initOptions={initOptions} sdkVersion={1}>
      <div className="app">……</div>
    </Provider>
  )
}

步骤3：登录 IM 服务端

如上文的初始化所述，当Provider渲染和销毁时，IM UIKit 内部会完成登录和登出云信 IM 服务端（即与云信 IM 服务端建立连接或断开连接）。

如需手动连接，请参考登录登出。

步骤4：搭建界面

IM UIKit 已提供会话列表页面和聊天消息等页面。IM UIKit 中提供的组件如下：

组件	描述
会话列表组件	代码中的名称为`ConversationContainer`，负责会话列表的展示与相关操作，相关集成说明详见集成会话列表界面
聊天（会话）组件	代码中的名称为`ChatContainer`，负责单聊、群聊相关的操作以及相关的权限管理，相关集成说明详见集成会话消息界面
通讯录组件	内含 `ContactListContainer`、`ContactInfoContainer` 等子组件，负责通讯录导航、好友列表、黑名单列表以及群组列表。相关集成说明请参见集成通讯录界面
搜索组件	内含 `SearchContainer` 和 `AddContainer` 两个子组件，负责搜索好友、群组以及添加好友、群组。相关集成说明详见集成搜索组件
用户资料组件	代码中的名称为`MyAvatarContainer`，负责用户资料的显示与相关操作。相关集成说明请参见集成用户资料组件。

组件默认提供自定义渲染函数，具体请参考各组件的详情说明。另外还提供自定义主题设置，详情请参见主题样式设置。

以搭建会话列表界面和会话消息界面为例，搭建界面的示例代码如下：

import React, { useMemo } from 'react'
import {
  Provider,
  ConversationContainer,
  ChatContainer,
} from '@xkit-yx/im-kit-ui'

import '@xkit-yx/im-kit-ui/es/style'

import './index.less'

const App = () => {
  const initOptions = useMemo(() => {
    return {
      appkey: '',
      account: '',
      token: '',
      debugLevel: 'debug',
      // ……
    }
  }, [])

  return (
    <Provider initOptions={initOptions} sdkVersion={2}>
      <div className="app">
        <div className="conversation">
          <ConversationContainer />
        </div>
        <div className="chat">
        <ChatContainer />
        </div>
      </div>
    </Provider>
  )
}

调整界面尺寸的示例代码如下：

组件内部宽高默认 100%，使用时需要包裹在div内，div需要设置组件的宽高等样式信息，如不设置会导致过长或者无法滚动等问题。

// index.less
.app {
  width: 100%;
  height: 100%;
}

.conversation {
  float: left;
  width: 30vw;
  height: 100%;
}

.chat {
  float: left;
  width: 70vw;
  height: 100%;
}

后续步骤

为保障通信安全，如果您在调试环境中的使用的是云信控制台生成的测试用 IM 账号和 token，请确保在后续的正式生产环境中，将其替换为通过 IM 服务端 API 生成的正式 IM 账号（accid）和 token。