uni-app

最近更新时间:2025-12-24 15:25:31

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


前提条件

开通服务

步骤1:创建 IM 应用

登录 即时通信 IM 控制台,在应用管理页面,单击创建新应用。如果您已有应用,可省略创建应用过程。


步骤2:获取 SDKAppID 与密钥

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


步骤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 文件夹下。
macOS 端
Windows 端
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.jsonvue.config.js 文件,确保 TUIKit 运行的环境正常。
manifest.json 文件
vue.config.js(仅 Vue2 项目)
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 it
config.plugins.delete('fork-ts-checker');
},
};
2. 集成 TUIKit:本步骤配置 app.vuepages.jsonmain.js 文件,确保 TUIKit 可以正常加载。
App.vue 文件
pages.json 文件
main.js(仅 Vue2 项目)
在 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 VUE3
import 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>
<input
class="input-field"
type="text"
v-model="userID"
placeholder="请输入用户ID"
/>
</view>
</view>
<view class="button-section">
<button
class="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 VUE3
vueVersion = 3;
// #endif

const SDKAppID = 0; // Your SDKAppID
const secretKey = ''; // Your secretKey

export 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">
<img
class="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
选中后单击完成,即可进入聊天界面并发送您的第一条消息。


更多高级特性(强烈推荐)

说明:
如果您的 app 需要推送功能,推荐您接入 uni-app 腾讯云推送服务(Push),支持 iOS 和 Android 推送,同时适配各大厂商推送。对 FCM 也有完善的支持,出海必备

说明:
@tencentcloud/chat-uikit-uniapp ≥ 2.0.6 默认支持, 只需要进入 控制台 > 插件市场 > 云端搜索 ,单击免费试用购买插件即可使用消息云端搜索功能。


音视频通话 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 运行和功能调试​​,绝对不能用于生产环境
请在项目发布前删除 Debug 脚本,使用后台生成 UserSig,具体原因和操作步骤请参考文档:生成 UserSig

uniapp 打包 App 中 Chat 的实例是 web 实例还是 native 实例?

chat-uikit-uniapp 即使打包为 App,其 Chat 实例依然是 ​​web 实例​​,而非 native 实例。

Conversation 中 groupProfile 或 userProfile 信息不全是为什么,如何获取?

原因:会话(Conversation)中携带的群组资料(groupProfile)或用户资料(userProfile)通常是简化版本,主要包含最核心的信息,例如基本的群名称、群头像或用户的昵称、头像等。这样设计的首要目的是为了​​提升性能和应用响应速度。
解决方案:
获取完整的群组资料​:通过 TUIGroupService.getGroupProfile 获取。
获取完整的用户资料​:通过 TUIUserService.getUserProfile 获取。
说明:
群组或用户的自定义字段的获取都需要在完整信息中获取。
更多常见问题请参见:uni-app 相关问题

参考信息

TUIKit GitHub 源码:
实现更多功能,请参考 ChatEngine API 文档:

联系我们

如遇任何问题,可联系 官网售后 反馈,享有专业工程师的支持,解决您的难题。