chat-uikit-uniapp 是一款基于腾讯云 Chat SDK 的 uniapp UI 组件库,提供了一些通用的 UI 组件,包含会话、聊天、群组等功能。基于这些精心设计的 UI 组件,您可以快速构建优雅的、可靠的、可扩展的 Chat 应用。 chat-uikit-uniapp 界面效果如下图所示:

前提条件
开通服务
步骤1:创建 IM 应用

步骤2:获取 SDKAppID 与密钥
在应用管理的应用列表中,获取新应用的
SDKAppID 和 SecretKey (密钥) 信息。注意:
查看密钥信息需要验证身份。
密钥信息为敏感信息,为防止他人盗用,请妥善保管,谨防泄露。

步骤3:创建测试账号
在账号管理中创建两个预设账号用于互相发送消息,以便后续的开发和调试。


环境要求
IDE: HBuilderX,需升级到新版本。
语言: TypeScript / JavaScript。TUIKit 使用 TS 开发,支持在 JS 或 TS 项目中集成。
框架: Vue2 / Vue3。
CSS 预处理器: sass (sass-loader 版本 ≤ 10.1.1)。
运行环境: Node.js v12 版本及以上。
包管理: npm (版本需与 Node 版本匹配)。
支持平台: Uniapp 打包 App。
说明:
Uniapp 打包微信小程序请另外参考 uniapp 精简版。
TUIKit v2.2.0 起,请按照本文所述步骤接入。
TUIKit v2.1.3 起,支持通过 cli 脚手架工具创建的项目集成,集成指引请点击 uniapp vue2/vue3(cli 脚手架)查看。
集成步骤
完成以下步骤即可发送您的第一条消息。
步骤1:创建项目
打开 HBuilderX,在菜单栏中选择 “文件 > 新建 > 项目”,创建一个名为 
chat-example 的 uni-app 项目。
步骤2:下载 TUIKit 组件
1. 创建
package.json 文件:HBuilderX 默认不创建该文件,请在项目根目录下执行命令:npm init -y
2. 下载 TUIKit 和依赖:通过 NPM 方式下载 TUIKit 组件和 unplugin-vue2-script-setup 依赖:
npm i @tencentcloud/chat-uikit-uniapp unplugin-vue2-script-setup
3. 拷贝 TUIKit 源码:为了方便开发者对 UI 进行扩展,需要将 TUIKit 源码复制到项目目录中的 ./TUIKit 文件夹下。
mkdir -p ./TUIKit && rsync -av --exclude={'node_modules','excluded-list.txt'} ./node_modules/@tencentcloud/chat-uikit-uniapp/ ./TUIKit && rsync -av ./node_modules/@tencentcloud/chat-uikit-uniapp/static ./
xcopy .\\node_modules\\@tencentcloud\\chat-uikit-uniapp .\\TUIKit /i /e /exclude:.\\node_modules\\@tencentcloud\\chat-uikit-uniapp\\excluded-list.txt && xcopy node_modules\\@tencentcloud\\chat-uikit-uniapp\\static .\\static /i /e
步骤3:集成 TUIKit 组件
1. 工程配置:本步骤配置
manifest.json 和 vue.config.js 文件,确保 TUIKit 运行的环境正常。在
manifest.json 文件的源码视图中手动关闭 H5 treeShaking 选项。{"name" : "chat-example",/* 其他配置 */"h5" : {"optimization" : {"treeShaking" : {"enable" : false}}},/* 其他配置 */}
Vue2 项目必须在根目录下修改 vue.config.js (如果没有该文件,请创建该文件并写入以下代码)。
const ScriptSetup = require('unplugin-vue2-script-setup/webpack').default;module.exports = {parallel: false,configureWebpack: {plugins: [ScriptSetup({/* options */}),],},chainWebpack(config) {// disable type check and let `vue-tsc` handles itconfig.plugins.delete('fork-ts-checker');},};
2. 集成 TUIKit:本步骤配置
app.vue、pages.json 和 main.js 文件,确保 TUIKit 可以正常加载。在 App.vue 中引入并初始化
TUIChatKit。<script lang="ts">import { TUIChatKit } from './TUIKit';TUIChatKit.init();export default {onLaunch: function () {}};</script><style>/* common css for page */uni-page-body,html,body,page {width: 100% !important;height: 100% !important;overflow: hidden;}</style>
配置
pages.json 路由是集成 TUIKit 的必备步骤。同时,配置 TabBar 以展示“消息”、“通讯录”和“个人中心”。{"pages": [{"path": "pages/index/index", // 您的项目首页"style": {"navigationBarTitleText": "腾讯云 IM","navigationBarBackgroundColor": "#EBF0F6"}},{"path": "pages/profile/profile","style": {"navigationBarTitleText": "腾讯云 IM","navigationBarBackgroundColor": "#EBF0F6"}},{"path": "TUIKit/components/TUIConversation/index","style": {"navigationStyle": "custom"}},{"path": "TUIKit/components/TUIChat/index","style": {"navigationStyle": "custom","app-plus": {"softinputMode": "adjustResize"}}},{"path": "TUIKit/components/TUIContact/index","style": {"navigationStyle": "custom"}},{"path": "TUIKit/components/TUIChat/video-play","style": {"navigationBarTitleText": "腾讯云 IM","navigationBarBackgroundColor": "#EBF0F6"}},{"path": "TUIKit/components/TUIChat/web-view","style": {"navigationBarTitleText": "腾讯云 IM","navigationBarBackgroundColor": "#EBF0F6"}},{"path": "TUIKit/components/TUIGroup/index","style": {"navigationStyle": "custom"}},{"path": "TUIKit/components/TUISearch/index","style": {"navigationBarTitleText": "聊天记录","navigationBarBackgroundColor": "#EBF0F6"}}],"tabBar": {"backgroundColor": "#EBF0F6","height": "70px","list": [{"pagePath": "TUIKit/components/TUIConversation/index","text": "消息","iconPath": "./static/message.png","selectedIconPath": "./static/message-selected.png"},{"pagePath": "TUIKit/components/TUIContact/index","text": "通讯录","iconPath": "./static/relation.png","selectedIconPath": "./static/relation-selected.png"},{"pagePath": "pages/profile/profile","text": "个人中心","iconPath": "./static/profile.png","selectedIconPath": "./static/profile-selected.png"}]},"globalStyle": {"navigationBarTextStyle": "black","navigationBarTitleText": "uni-app","navigationBarBackgroundColor": "#F8F8F8","backgroundColor": "#F8F8F8"},"uniIdRouter": {}}
如果您是 Vue2 项目,请在
main.js 中引入组合式API。// #ifndef VUE3import VueCompositionAPI from '@vue/composition-api';Vue.use(VueCompositionAPI);// #endif
步骤4:配置登录和登出
1. 登录配置:请将以下内容复制到首页文件
pages/index/index.vue 中并配置前提条件 > 开通服务 > 步骤2:获取 SDKAppID 与密钥 中获取的SDKAppID、secretKey 完成登录逻辑配置。说明:
代码中使用的
genTestUserSig 是通过本地脚本使用 secretKey 生成 UserSig。用于方便开发和调试,不适合生成环境。该方法仅适用于本地 Demo 运行和功能调试,因为
secretKey 容易被反编译逆向破解,一旦密钥泄露,攻击者可以盗用您的腾讯云流量,绝对不能用于生产环境。生产环境下,请将
UserSig 的计算代码集成到您的服务端,并提供面向项目的接口, 正确的UserSig签发方式参见 服务端生成 UserSig。<template><view class="login-container"><view class="login-form"><view class="title-section"><text class="title">登录</text></view><view class="input-section"><view class="input-group"><text class="input-label">用户ID</text><inputclass="input-field"type="text"v-model="userID"placeholder="请输入用户ID"/></view></view><view class="button-section"><buttonclass="login-btn":disabled="!canLogin || isLoading"@tap="handleLogin">{{ isLoading ? '登录中...' : '登录' }}</button></view></view></view></template><script>import { TUILogin } from '@tencentcloud/tui-core-lite';import { genTestUserSig } from '../../TUIKit/debug';let vueVersion = 2;// #ifdef VUE3vueVersion = 3;// #endifconst SDKAppID = 0; // Your SDKAppIDconst secretKey = ''; // Your secretKeyexport default {data() {return {userID: '',isLoading: false,}},computed: {canLogin() {return this.userID.trim().length > 0}},methods: {async handleLogin() {if (!this.canLogin || this.isLoading) return;this.isLoading = true;try {const { userSig } = genTestUserSig({SDKAppID: SDKAppID,userID: this.userID,secretKey: secretKey,});TUILogin.login({SDKAppID: SDKAppID,userID: this.userID,userSig: userSig,framework: `vue${vueVersion}` // framework used vue2 / vue3}).then(() => {uni?.switchTab({url: '/TUIKit/components/TUIConversation/index',});}).catch((error) => {console.error(error);});} catch (error) {uni.showToast({title: '登录失败',icon: 'error'})} finally {this.isLoading = false}}}}</script><style lang="scss" scoped>.login-container{display:flex;align-items:center;justify-content:center;}.login-form{width:100%;padding:80rpx 60rpx;}.title-section{text-align:center;margin-bottom:80rpx;}.title{font-size:48rpx;font-weight:bold;color:#333333;}.input-section{margin-bottom:60rpx;}.input-group{margin-bottom:40rpx;}.input-label{display:block;font-size:28rpx;color:#666666;margin-bottom:16rpx;}.input-field{width:100%;height:88rpx;border:2rpx solid #e0e0e0;border-radius:8rpx;padding:0 24rpx;font-size:32rpx;color:#333333;box-sizing:border-box;&:focus{border-color:#007aff;}}.button-section{margin-top:40rpx;}.login-btn{width:100%;height:88rpx;background-color:#007aff;color:#ffffff;border:none;border-radius:8rpx;font-size:32rpx;font-weight:600;}</style>
2. 登出配置:在项目
pages 目录下新建 profile 页面,并将以下代码复制到 pages/profile/profile.vue,完成个人中心和登出逻辑配置。<template><div class="profile"><div class="profile-basic"><imgclass="profile-basic-avatar":src="userProfile.avatar ||'https://web.sdk.qcloud.com/component/TUIKit/assets/avatar_21.png'"><div class="profile-basic-info"><div class="profile-basic-info-nick">{{ userProfile.nick || "-" }}</div><div class="profile-basic-info-id"><label class="profile-basic-info-id-label">{{ "用户ID" }}:</label><div class="profile-basic-info-id-value">{{ userProfile.userID }}</div></div></div></div><div class="profile-footer"><button class="logout-btn" @click="logout">退出登录</button></div></div></template><script>import { TUIUserService } from '@tencentcloud/chat-uikit-engine-lite';import { TUILogin } from '@tencentcloud/tui-core-lite';export default {data() {return {userProfile: {}}},methods: {logout() {TUILogin.logout().then(() => {uni.reLaunch({url: '/pages/index/index',})});}},mounted() {TUIUserService.getUserProfile().then((res) => {this.userProfile = res.data;});}}</script><style lang="scss" scoped>.profile{height:100%;flex:1;display:flex;flex-direction:column;&-basic{display:flex;gap:10px;box-sizing:border-box;padding:14px 18px;flex-direction:row;align-items:flex-start;border-bottom:10px solid #f5f5f5;&-avatar{flex:0 0 auto;width:78px;height:78px;border-radius:8px;}&-info{padding:10px 0;box-sizing:border-box;height:100%;flex:1;display:flex;flex-direction:column;justify-content:space-between;min-width:0;&-nick{font-size:14px;word-break:keep-all;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;font-family:PingFangSC-Medium;font-weight:500;color:#000;letter-spacing:0;}&-id{display:flex;align-items:center;font-family:PingFangSC-Regular;color:#999;letter-spacing:0;font-size:14px;word-break:keep-all;&-value{white-space:nowrap;overflow:hidden;text-overflow:ellipsis;}}}}&-footer{flex:1;display:flex;align-items:center;padding:20px 18px;margin-top:auto;.logout-btn{width:100%;padding:10px 20px;background-color:#ff4757;color:#ffffff;border:none;border-radius:8px;font-size:16px;font-weight:500;text-align:center;}}}</style>
运行和测试
步骤1:运行项目
使用 HBuilderX 启动该项目,单击菜单栏中的:运行 > 运行到手机或模拟器 > 运行到“指定”基座。

步骤2:发送您的第一条消息
登录页输入 前提条件 > 开通服务 > 步骤3:创建测试账号 中创建的测试账号,点击登录进入 TUIKit。
点击发起单聊后并在搜索栏输入 前提条件 > 开通服务 > 步骤3:创建测试账号 中创建的另一个测试账号
userID。选中后单击完成,即可进入聊天界面并发送您的第一条消息。

更多高级特性(强烈推荐)
消息推送
说明:

消息云端搜索
说明:

音视频通话 TUICallKit 插件
说明:
TUIKit 中默认没有集成 TUICallKit 音视频组件。
TUICallKit 主要负责语音、视频通话。
运行平台 | 集成方案 | 文档链接 |
移动端应用 (App) | 请集成 uni-app (客户端) TUICallKit。 | |
H5 环境 | 请集成 uni-app (H5) TUICallKit。 |
客户端通话示意图:


H5 通话示意图:

智能客服
说明:
进入智能客服控制台,选择应用后,通过领取试用(每个应用都可领取2次、每次有效期7天的免费试用)或者直接购买,开通智能客服。如果您没有可选择的应用,可参见 创建应用 步骤操作,再为新建应用开通智能客服。
单独购买智能客服时,仅支持用户和客服号收发消息,账号数和 DAU 无上限。如需 C2C 聊天、群聊等功能,请加购 IM 套餐包。
集成请参考 用户端 SDK 轻量接入。

云端审核
在消息发送、资料修改场景中,很有可能会扩散不合适的内容,特别是与敏感事件/人物相关、黄色不良内容等令人反感的内容,不仅严重损害了用户们的身心健康,更很有可能违法并导致业务被监管部门查封。即时通信 IM 支持云端内容审核(反垃圾信息)功能,可针对不安全、不适宜的内容进行自动识别、处理,为您的产品体验和业务安全保驾护航。
云端审核:在服务端检测由单聊、群聊、资料场景中产生的文本、图片、音频、视频内容,支持针对不同场景的不同内容分别配置审核策略,并对识别出的不安全内容进行拦截。此功能已提供默认预设拦截词库和审核场景,只需在 IM 控制台打开功能开关,即可直接使用。
常见问题
Debug 文件的作用?
主要作用:在开发阶段,TUIKit 提供了 debug 文件夹中的本地 UserSig 生成脚本,用于方便开发和调试。
警告:(该方法仅适合本地跑通 Demo 和功能调试)
该方法中的
SECRETKEY 容易被反编译逆向破解。一旦密钥泄露,攻击者可以盗用您的腾讯云流量。
仅适用于本地 Demo 运行和功能调试,绝对不能用于生产环境。
uniapp 打包 App 中 Chat 的实例是 web 实例还是 native 实例?
chat-uikit-uniapp 即使打包为 App,其 Chat 实例依然是 web 实例,而非 native 实例。
Conversation 中 groupProfile 或 userProfile 信息不全是为什么,如何获取?
原因:会话(Conversation)中携带的群组资料(groupProfile)或用户资料(userProfile)通常是简化版本,主要包含最核心的信息,例如基本的群名称、群头像或用户的昵称、头像等。这样设计的首要目的是为了提升性能和应用响应速度。
解决方案:
获取完整的群组资料:通过 TUIGroupService.getGroupProfile 获取。
获取完整的用户资料:通过 TUIUserService.getUserProfile 获取。
说明:
群组或用户的自定义字段的获取都需要在完整信息中获取。
参考信息
TUIKit GitHub 源码:
实现更多功能,请参考 ChatEngine API 文档: