TUIKit 是基于 IM SDK 的一款 UI 组件库,可通过 UI 组件快速实现聊天、会话、搜索、关系链、群组等功能。本文介绍如何快速集成 TUIKit 并实现核心功能。
精简版界面效果如下图所示:
聊天页面 | 语音通话 | 视频通话 |
![]() | ![]() | ![]() |
关键概念
针对用户不同场景的诉求和体积要求,我们推出了多个版本的 UI 组件 ,您可以根据实际业务需求选择集成最适合的版本。
前提条件
HBuilderX 需要升级到最新版本
TypeScript / JavaScript (TUIKit 使用 ts 语言开发,支持在 js 或者 ts 项目中集成)
Vue2/Vue3
sass(sass-loader 版本 ≤ 10.1.1)
node(12.13.0 ≤ node,推荐使用 Node.js 官方 LTS 版本 16.17.0)
npm(版本请与 node 版本匹配)
创建项目
1. 打开 HBuilderX,在菜单栏中选择 “文件 > 创建 > 项目”,创建一个名为 chat-example 的 uni-app 项目。

2. 在终端输入
npm init -y,创建package.json文件。npm init -y
下载并导入组件
步骤1:安装依赖
1. 下载组件。
npm i tuikit-atomicx-uniapp-wx
npm i tuikit-atomicx-uniapp-wx@vue2
2. 拷贝源码。
mkdir -p ./TUIKit && cp -r node_modules/tuikit-atomicx-uniapp-wx/ ./TUIKit && cp node_modules/@trtc/call-engine-lite-wx/RTCCallEngine.wasm.br ./static
xcopy node_modules\\tuikit-atomicx-uniapp-wx .\\TUIKit /i /excopy node_modules\\@trtc\\call-engine-lite-wx\\RTCCallEngine.wasm.br .\\static
步骤2:引入组件
请将以下内容复制到 pages/index/index.vue 文件中。
<template><view class="container"><div v-if="!showChat" class="simple-view"><input style="width: 90%; height: 60px; font-size: 18px; padding: 0 15px;" v-model="userID":placeholder="isLoggedIn ? '输入对方ID' : '输入你的ID'" /><button :style="{ backgroundColor: isLoggedIn ? '#07C160' : '#006EFF' }"@click="isLoggedIn ? startChat() : handleLogin()">{{ isLoggedIn ? '开始聊天' : '登录' }}</button></div><div class="TUIChat"><MessageList /><MessageInput /></div></view></template><script lang="ts" setup>import { ref } from 'vue';import MessageInput from '../../TUIKit/components/MessageInput/MessageInput.vue';import MessageList from '../../TUIKit/components/MessageList/MessageList.vue';import { useLoginState, useConversationListState } from '../../TUIKit';const userID = ref('');const isLoggedIn = ref(false);const showChat = ref(false)const { login } = useLoginState();const { setActiveConversation } = useConversationListState();const handleLogin = async () => {// 必填信息// 测试TUIKit时可以从腾讯云IM控制台获取userSig// 生产环境部署请从您的服务器获取// 查看文档:https://cloud.tencent.com/document/product/269/32688await login({userId: userID.value,userSig: '',sdkAppId: 0,});wx.$globalCallPagePath = 'TUIKit/components/CallView/CallView';isLoggedIn.value = true;userID.value = ''};const startChat = () => {if (!userID.value) return;const conversationID = `C2C${userID.value}`;setActiveConversation(conversationID);showChat.value = true};</script><style scoped>.TUIChat {display: flex;flex-direction: column;width: 100vw;height: 100vh;}</style>
<template><view class="container"><div v-if="!showChat" class="simple-view"><input style="width: 90%; height: 60px; font-size: 18px; padding: 0 15px;" v-model="userID":placeholder="isLoggedIn ? '输入对方ID' : '输入你的ID'" /><button :style="{ backgroundColor: isLoggedIn ? '#07C160' : '#006EFF' }"@click="isLoggedIn ? startChat() : handleLogin()">{{ isLoggedIn ? '开始聊天' : '登录' }}</button></div><div v-else class="TUIChat"><MessageList class="message-list" /><MessageInput /></div></view></template><script lang='ts'>// @ts-nocheckimport MessageInput from '../../TUIKit/components/MessageInput/MessageInput.vue';import MessageList from '../../TUIKit/components/MessageList/MessageList.vue';import { useLoginState, useConversationListState } from '../../TUIKit';export default {name: 'ChatContainer',components: {MessageInput,MessageList},data() {return {userID: '',isLoggedIn: false,showChat: false}},methods: {async handleLogin() {const { login } = useLoginState();try {// 必填信息// 测试TUIKit时可以从腾讯云IM控制台获取userSig// 生产环境部署请从您的服务器获取// 查看文档:https://cloud.tencent.com/document/product/269/32688await login({userId: this.userID,userSig: '',sdkAppId: 0,});// 设置全局通话页面路径wx.$globalCallPagePath = 'TUIKit/components/CallView/CallView';this.isLoggedIn = true;this.userID = '';} catch (error) {console.error('登录失败:', error);}},startChat() {if (!this.userID) return;const { setActiveConversation } = useConversationListState();const conversationID = `C2C${this.userID}`;setActiveConversation(conversationID);this.showChat = true;}}}</script><style lang="scss" scoped>.TUIChat {display: flex;flex-direction: column;width: 100vw;height: 100vh;.message-list {display: flex;flex: 1;min-height: 0;width: 100%;height: 100%;}}</style>
步骤3:获取 SDKAppID、userID 和 userSig
注意:
SDKAppID:在 即时通信 IM 控制台 > 应用管理 单击创建新应用,获取 SDKAppID。

userID:单击 即时通信 IM 控制台 > 消息服务 Chat > 账号管理,切换至目标应用所在账号,您可以创建 2~3 个账号用于体验单聊、群聊的功能。

userSig:单击 即时通信 IM 控制台 > 开发工具 > UserSig生成校验,切换至目标应用所在账号,填写创建的 userID,即可生成 userSig。

运行和测试
步骤1:运行

步骤2:发送第一条消息

注意:
如果集成音视频通话功能,将增加 400KB 的体积增量。
步骤3:增加音视频通话(可选)
功能 | 音视频通话组件 |
1v1 视频、音频通话 | ✓ |
全局监听来电 | ✓ |
呼叫/接听/拒绝/挂断 | ✓ |
1. 开通服务
2. 配置微信开放平台
开通企业类小程序

在小程序控制台开启实时音视频接口
小程序推拉流标签使用权限暂时只开放给有限类目,具体支持类目参见该地址。
符合类目要求的小程序,需要在 微信公众平台 > 开发 > 开发管理 > 接口设置中自助开通该组件权限。

3. 在小程序控制台配置域名

将以下域名添加到 socket 合法域名:
域名 | 说明 | 是否必须 |
wss://${SDKAppID}w4c.my-imcloud.com | v3.4.6起,SDK 支持独立域名,可更好地保障服务稳定性。 例如您的 SDKAppID 是 1400xxxxxx,则独立域名为: wss://1400xxxxxxw4c.my-imcloud.com | 必须 |
wss://wss.im.qcloud.com | Web IM 业务域名 | 必须 |
wss://wss.tim.qq.com | Web IM 业务域名 | 必须 |
wss://wssv6.im.qcloud.com | Web IM 业务域名 | 必须 |
将以下域名添加到 request 合法域名:
域名 | 说明 | 是否必须 |
https://web.sdk.qcloud.com | Web IM 业务域名 | 必须 |
https://boce-cdn.my-imcloud.com | Web IM 业务域名 | 必须 |
https://api.im.qcloud.com | Web IM 业务域名 | 必须 |
https://events.im.qcloud.com | Web IM 业务域名 | 必须 |
https://webim.tim.qq.com | Web IM 业务域名 | 必须 |
https://wss.im.qcloud.com | Web IM 业务域名 | 必须 |
https://wss.tim.qq.com | Web IM 业务域名 | 必须 |
将以下域名添加到 uploadFile 合法域名:
域名 | 说明 | 是否必须 |
https://${SDKAppID}-cn.rich.my-imcloud.com | 从 2024年9月10日起,新增应用默认分配 COS 独立域名。 例如您的 SDKAppID 是 1400xxxxxx,则 COS 独立域名为: https://1400xxxxxx-cn.rich.my-imcloud.com | 必须 |
https://cn.rich.my-imcloud.com | 文件上传域名 | 必须 |
https://cn.imrich.qcloud.com | 文件上传域名 | 必须 |
https://cos.ap-shanghai.myqcloud.com | 文件上传域名 | 必须 |
https://cos.ap-shanghai.tencentcos.cn | 文件上传域名 | 必须 |
https://cos.ap-guangzhou.myqcloud.com | 文件上传域名 | 必须 |
将以下域名添加到 downloadFile 合法域名:
域名 | 说明 | 是否必须 |
https://${SDKAppID}-cn.rich.my-imcloud.com | 从 2024年9月10日起,新增应用默认分配 COS 独立域名。 例如您的 SDKAppID 是 1400xxxxxx,则 COS 独立域名为: https://1400xxxxxx-cn.rich.my-imcloud.com | 必须 |
https://cn.rich.my-imcloud.com | 文件下载域名 | 必须 |
https://cn.imrich.qcloud.com | 文件下载域名 | 必须 |
https://cos.ap-shanghai.myqcloud.com | 文件下载域名 | 必须 |
https://cos.ap-shanghai.tencentcos.cn | 文件下载域名 | 必须 |
https://cos.ap-guangzhou.myqcloud.com | 文件下载域名 | 必须 |
4. 配置页面路由
在 pages.json 文件注册全局监听页面。
{"path": "TUIKit/components/CallView/CallView","style": {"navigationBarTitleText": "uni-app"}}
常见问题
如何移除音视频通话功能
移除
static/RTCCallEngine.wasm.br 文件。移除 TUIKit/index.ts 中的模块导出

移除 TUIKit/components/MessageInput/MessageInput.vue 中的通话按钮

移除在 pages.json 中为音视频通话添加的全局页面监听配置。
// {// "path": "TUIKit/components/CallView/CallView",// "style": {// "navigationBarTitleText": "uni-app"// }// }
Debug 脚本的作用
出于体积和安全双重因素考虑,请在发布前删除项目目录下
/TUIKit/debug 文件夹。在开发阶段为了方便开发,项目提供生成本地 UserSig 的脚本文件存放于TUIKit/debug文件夹中,但这并不安全,该方法中 SECRETKEY 很容易被反编译逆向破解,一旦您的密钥泄露,攻击者就可以盗用您的腾讯云流量,因此该方法仅适合本地跑通 Demo 和功能调试。因此,请在项目发布前删除 Debug 脚本,使用后台生成 UserSig,具体原因和操作步骤请参考文档:生成 UserSig。

