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

本文介绍如何基于 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：按需导入组件

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

   示例代码如下：

   $ npm install @xkit-yx/im-kit-ui --save
   

   目前仅支持 npm 方式集成，暂不支持 CDN 方式集成。

2. 按需将 IM UIKit 组件导入到您的 React 项目，详细说明可参考组件导入。

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

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

步骤2：初始化

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

• sdkVersion：传入1或2。1 为 NIM Web SDK；2为 NIM Web Elite SDK（IM 即时通讯含圈组版）
• 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
    // 参考 IM Elite SDK 的 initOptions
  }

  return (
    <Provider initOptions={initOptions} sdkVersion={2}>
      <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。

相关参考

Demo 源码

网易云信在 Github 上提供了开源的IM Demo 源码供您参考。

源码跑通流程说明，参见跑通 IM Demo 源码。

使用原生 SDK 中方法

如果您需要在 IM UIKit 中自行实现目前 UIKit 还未实现，但原生 IM Web SDK 已提供的能力。您可以通过调用原生 IM Web SDK 中提供的接口来实现。例如，您想对 IM UIKit 的消息历史进行全文检索，可以调用原生 IM Web SDK 中的 ftsCloudMsgLogs 方法，示例代码如下：

import { useStateContext } from '@xkit-yx/im-kit-ui'
const { nim } = useStateContext()
nim.nim.ftsCloudMsgLogs({keyword: '2', done: (err, data) => {
    console.log('=============data===========', data);
}})

原生 IM Web SDK 中的接口请参考对应的 API 文档。

问题排查

如果遇到无法跑通的问题，可尝试把node_modules/@xkit-yx包以及package-lock.json文件删掉，并在package.json中将@xkit-yx/im-kit-ui包写死为最新版本重新安装。

如果尝试后仍无法解决，请联系云信技术支持或点击下方的提交工单。