非 React 框架集成 IM UIKit

更新时间: 2023/07/21 06:56:54

本文介绍如何基于 React 框架以外的其他 Web 开发框架(例如 Vue 和 Angular)或者原生 HTML 集成 IM UIKit。

前提条件

使用限制

集成 IM UIKit 后,如果需要自定义渲染,自定义渲染的逻辑需要使用 JSX 编写, 并使用如下工具将 JSX 转换成 JS。

工具 说明
jsx-web-compilter 云信提供的转换函数,请前往 jsx-web-compilter 下载该工具

实现流程

将所需的组件引入您的项目,并初始化。初始化过程默认已包含登录 IM 服务端。

具体说明
  1. 引入IMUIKit类,并按需引入组件。

    IM UIKit 中提供的组件如下:

    组件 描述
    会话列表组件 代码中的名称为ConversationContainer,负责会话列表的展示与相关操作
    聊天(会话)组件 代码中的名称为ChatContainter,负责单聊、群聊相关的操作以及相关的权限管理
    通讯录组件 内含 ContactListContainerContactInfoContainer 等子组件,负责通讯录导航、好友列表、黑名单列表以及群组列表
    搜索组件 内含 SearchContainerAddContainer 等子组件,负责搜索好友、群组以及添加好友、群组
    用户资料组件 代码中的名称为MyAvatarContainer,负责用户资料的展示与相关操作

    此处以引入会话列表组件ConversationContainer和聊天(会话)组件ChatContainer为例,示例代码如下:


    import { IMUIKit, ConversationContainer, ChatContainer } from '@xkit-yx/im-kit-ui'
    
  2. 引入组件的 css 或 less 样式(两者选其一)。

    • 如果您希望引入组件 css:

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

      import "@xkit-yx/im-kit-ui/es/style";
      
  3. 初始化 IM UIKit 实例。

    初始化参数如下:

    参数
    类型
    说明
    initOptions Object 初始化配置项,包括必传项appkeyaccounttoken以及重连配置等其他可选项,具体见如下示例代码的注释
    singleton boolean 是否开启单实例模式。基于 React 框架以外的 Web 框架开发时,必须 设置为true,开启单实例模式 IM UIKit 的内部上下文由 Provider 提供,后者通过 React.Context API 获取上下文。基于 React 框架开发时,每一个 Provider 都会生成新的 NimKitCoreStore 实例,以保证多个 Provider 互相隔离。因此,如果基于其他 Web 框架开发,初始化时请务必singleton设置为true,开启单实例模式。开启后 NimKitCoreStore 都使用单实例模式,以保证多个 Provider 数据一致、行为一致。
    sdkVersion 1|2 1 或 2。1 为 NIM Web SDK;2 为 NIM Web Elite SDK(IM 即时通讯增强版 Web SDK)
    const uikit = new IMUIKit({
    initOptions: {
        appkey: '',  // 传入您的应用的 App Key,必传
        account: '',  // 传入 accid,必传
        token: '', // 传入 token,必传
        lbsUrls: '', // lbs 地址,非必传。默认为云信公网提供的链接,SDK 连接时会向 lbs 地址请求得到 socket 连接地址。为防止 lbs 链接被网络运营商劫持,可传入自己代理的地址做备份,格式如 ['公网地址', '代理地址']
        linkUrl: '', // socket 备用地址,非必传。当 lbs 请求失败时,尝试直接连接 socket 备用地址。如不传,SDK 会有内部默认的备用地址
        debugLevel: 'debug', // 日志级别,非必传。可选值包括off、error、warn、log和debug"
        needReconnect: true, // 是否开启断网自动重连,非必传
        reconnectionAttempts: 5, // 自动重连的最大次数,非必传
    },
    singleton: true, // 单实例模式,需要传入 true,开启后内部 NimKitCore 和 Store 都会使用单实例模式
    sdkVersion: 1,
    })
    
  4. 获取 DOM 节点。此处以 “待获取的 DOM 节点的 ID 为wrapper1wrapper2” 为例。

    const wrapper1 = document.getElementById('wrapper1')
    const wrapper2 = document.getElementById('wrapper2')
    
  5. 调用render方法,将待渲染组件指定到 DOM 节点中进行渲染,完成组件的默认界面的搭建。

    如下示例代码中的null参数指使用对应组件自定义参数的默认值。以会话列表组件和会话组件为例,其具体自定义参数可分别参见会话列表界面自定义参数会话消息界面自定义参数


    uikit.render(ConversationContainer, null, wrapper1) // null 表示使用默认参数
    uikit.render(ChatContainer, null, wrapper2) // null 表示使用默认参数
    
  6. (可选)调用getStateContext方法获取上下文。

    const { nim, store, initOptions } = uikit.getStateContext()
    
  7. (可选)调用unmount方法卸载组件。

    uikit.unmount(wrapper1)
    uikit.unmount(wrapper2)
    
完整示例代码
// 引入组件和 IMUIKit 类
import { IMUIKit, ConversationContainer, ChatContainer } from '@xkit-yx/im-kit-ui'

// 引入样式
import '@xkit-yx/im-kit-ui/es/style';
import 'antd/dist/antd.less';

// 初始化实例,传入初始化参数
const uikit = new IMUIKit({
  initOptions: {
    appkey: '',
    account: '',
    token: '',
    lbsUrls: '',
    linkUrl: '',
    debugLevel: 'debug',
    needReconnect: true,
    reconnectionAttempts: 5,
  },
  singleton: true, // 单实例模式,需要传入 true 开启,开启后内部 NimKitCore 和 Store 都会使用单实例模式
  sdkVersion: 1,
})

// 获取 dom 节点
const wrapper1 = document.getElementById('wrapper1')
const wrapper2 = document.getElementById('wrapper2')

// 渲染需要渲染的组件到指定的 dom 节点中,完成组件的默认界面搭建
uikit.render(ConversationContainer, null, wrapper1)
uikit.render(ChatContainer, null, wrapper2)

// 获取上下文
const { nim, store, initOptions } = uikit.getStateContext()

// 卸载组件
uikit.unmount(wrapper1)
uikit.unmount(wrapper2)

后续步骤

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

相关参考

Demo 源码

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

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

自定义渲染示例

如果您需要在非 React 框架下对界面进行自定义渲染,可参考非 React 框架自定义渲染中的示例。

此文档是否对你有帮助?
有帮助
去反馈
  • 前提条件
  • 使用限制
  • 实现流程
  • 后续步骤
  • 相关参考
  • Demo 源码
  • 自定义渲染示例