开发环境要求
- HBuilderX
- Vue 3
- TypeScript
- sass(sass-loader 版本 ≤ 10.1.1)
- node(12.13.0 ≤ node 版本 ≤ 17.0.0, 推荐使用 Node.js 官方 LTS 版本 16.17.0)
- npm(版本请与 node 版本匹配)
注意:
如果您需要集成 vue2 TUIKit,请参见 vue2 TUIKit 源码集成。
TUIKit 源码集成
步骤1:创建项目 (已有项目可忽略)
注意:
请在项目 mianfest.json > 基础配置里边确认 Vue 版本选择。

HBuilder 不会默认创建 package.json 文件,因此您需要先创建 package.json 文件。请执行以下命令:
npm init -y
步骤2:下载并引入 TUIKit
通过 npm 方式下载 TUIKit 并集成组件。 chat-uikit-uniapp github 源码集成
注意:
uni-app 打包到小程序涉及到体积问题,因此我们提供了以下两种集成方案:
- 打包 APP 或者 H5 端推荐方案一,主包集成
- TUIKit 如果作为 tabbar 页面,推荐方案一,主包集成(主包体积 1M)
- 客户线上环境,如果不需要本地换算 userSig ,可删除 debug 文件(节省 150kb)
- 打包小程序端,有体积限制需求,推荐方案二,分包集成(分包可节约 170kb)
方案一:主包集成
在 App.vue 页面引用 TUIKit 组件,为此您需要修改 App.vue 和 pages.json 文件。
为了方便您后续的拓展,建议您将 TUIKit 组件复制到自己工程的 pages 目录下,在自己的项目目录下执行以下命令:
# macOS
npm i @tencentcloud/chat-uikit-uniapp
mkdir -p ./pages/TUIKit && cp -r ./node_modules/@tencentcloud/chat-uikit-uniapp/ ./pages/TUIKit
# windows
npm i @tencentcloud/chat-uikit-uniapp
xcopy .\node_modules\@tencentcloud\chat-uikit-uniapp .\pages\TUIKit /i /e
成功后目录结构如图所示:

<script>
import { genTestUserSig, aegisID } from "./pages/TUIKit/debug/index.js";
import { TIM, TIMUploadPlugin, Aegis } from './pages/TUIKit/debug/tim.js';
const aegis = new Aegis({
id: aegisID,
reportApiSpeed: true,
});
uni.$aegis = aegis;
const config = {
userID: "",
SDKAppID: 0,
secretKey: "",
};
const userSig = genTestUserSig(config).userSig;
uni.$chat_SDKAppID = config.SDKAppID;
uni.$chat_userID = config.userID;
uni.$chat_userSig = userSig;
uni.$TUIKit = TIM.create({
SDKAppID: uni.$chat_SDKAppID,
});
uni.$TIM = TIM;
uni.$TUIKit.registerPlugin({
"tim-upload-plugin": TIMUploadPlugin,
});
uni.$TUIKit.registerPlugin({
"cos-wx-sdk": TIMUploadPlugin,
});
export default {
onLaunch: function () {
this.bindTIMEvent();
this.login();
},
methods: {
login() {
uni.$TUIKit.login({ userID: config.userID, userSig }).then((res) => {
uni.showLoading({
title: "初始化...",
});
});
},
bindTIMEvent() {
uni.$TUIKit.on(uni.$TIM.EVENT.SDK_READY, this.handleSDKReady);
uni.$TUIKit.on(uni.$TIM.EVENT.SDK_NOT_READY,this.handleSDKNotReady);
uni.$TUIKit.on(uni.$TIM.EVENT.KICKED_OUT, this.handleKickedOut);
},
handleSDKReady(event) {
uni.$chat_isSDKReady = true;
uni.hideLoading();
},
handleSDKNotReady(event) {
uni.showToast({
title: "SDK 未完成初始化",
});
},
handleKickedOut(event) {
uni.clearStorageSync();
uni.showToast({
title: `${this.kickedOutReason(event.data.type)}被踢出。`,
icon: "none",
});
},
kickedOutReason(type) {
switch (type) {
case uni.$TIM.TYPES.KICKED_OUT_MULT_ACCOUNT:
return "多实例登录";
case uni.$TIM.TYPES.KICKED_OUT_MULT_DEVICE:
return "多设备登录";
case uni.$TIM.TYPES.KICKED_OUT_USERSIG_EXPIRED:
return "userSig 过期";
case uni.$TIM.TYPES.KICKED_OUT_REST_API:
return "REST API kick 接口踢出";
default:
return "";
}
},
},
};
</script>
<style>
</style>
{
"pages": [
{
"path": "pages/TUIKit/TUIPages/TUIConversation/index",
"style": {
"navigationBarTitleText": "云通信 IM",
}
},
{
"path": "pages/TUIKit/TUIPages/TUIConversation/create",
"style": {
"navigationBarTitleText": "选择联系人",
"app-plus": {
"scrollIndicator": "none"
}
}
},
{
"path": "pages/TUIKit/TUIPages/TUIChat/index",
"style": {
"navigationBarTitleText": "云通信 IM",
"app-plus": {
"scrollIndicator": "none",
"softinputNavBar": "none",
"bounce": "none",
}
}
},
{
"path": "pages/TUIKit/TUIPages/TUIChat/components/message-elements/video-play",
"style": {
"navigationBarTitleText": "云通信 IM",
"app-plus": {}
}
},
{
"path": "pages/TUIKit/TUIPages/TUIGroup/index",
"style": {
"navigationBarTitleText": "群管理",
"app-plus": {
"scrollIndicator": "none"
}
}
},
{
"path": "pages/TUIKit/TUIPages/TUIGroup/memberOperate",
}
],
"globalStyle": {
"navigationBarTextStyle": "black",
"navigationBarTitleText": "uni-app",
"navigationBarBackgroundColor": "#F8F8F8",
"backgroundColor": "#F8F8F8"
}
}
方案二:分包集成
在 App.vue 页面引用 TUIKit 组件,为此您需要修改 App.vue 和 pages.json文件。
为了方便您后续的拓展,建议您将 TUIKit 组件复制到自己工程的根目录下,在自己的项目目录下执行以下命令:
# macOS
npm i @tencentcloud/chat-uikit-uniapp
mkdir -p ./TUIKit && cp -r ./node_modules/@tencentcloud/chat-uikit-uniapp/ ./TUIKit && mv ./TUIKit/debug ./debug
# windows
npm i @tencentcloud/chat-uikit-uniapp
xcopy .\node_modules\@tencentcloud\chat-uikit-uniapp .\TUIKit /i /e
move .\TUIKit\debug .\debug
成功后目录结构如图所示:

在 App.vue 文件引用 TUIKit 组件
<script>
<script>
import { genTestUserSig, aegisID } from "./debug/index.js";
import { TIM, TIMUploadPlugin, Aegis } from "./debug/tim.js";
const aegis = new Aegis({
id: aegisID,
reportApiSpeed: true,
});
uni.$aegis = aegis;
const config = {
userID: "",
SDKAppID: 0,
secretKey: "",
};
const userSig = genTestUserSig(config).userSig;
uni.$chat_SDKAppID = config.SDKAppID;
uni.$chat_userID = config.userID;
uni.$chat_userSig = userSig;
uni.$TUIKit = TIM.create({
SDKAppID: uni.$chat_SDKAppID,
});
uni.$TIM = TIM;
uni.$TUIKit.registerPlugin({
"tim-upload-plugin": TIMUploadPlugin,
});
uni.$TUIKit.registerPlugin({
"cos-wx-sdk": TIMUploadPlugin,
});
export default {
onLaunch: function () {
this.bindTIMEvent();
this.login();
},
methods: {
login() {
uni.$TUIKit.login({ userID: config.userID, userSig }).then((res) => {
uni.showLoading({
title: "初始化...",
});
});
},
bindTIMEvent() {
uni.$TUIKit.on(uni.$TIM.EVENT.SDK_READY, this.handleSDKReady);
uni.$TUIKit.on(uni.$TIM.EVENT.SDK_NOT_READY, this.handleSDKNotReady);
uni.$TUIKit.on(uni.$TIM.EVENT.KICKED_OUT, this.handleKickedOut);
},
handleSDKReady(event) {
uni.$chat_isSDKReady = true;
uni.hideLoading();
uni.navigateTo({
url: "/TUIKit/TUIPages/TUIConversation/index",
});
},
handleSDKNotReady(event) {
uni.showToast({
title: "SDK 未完成初始化",
});
},
handleKickedOut(event) {
uni.clearStorageSync();
uni.showToast({
title: `${this.kickedOutReason(event.data.type)}被踢出。`,
icon: "none",
});
},
kickedOutReason(type) {
switch (type) {
case uni.$TIM.TYPES.KICKED_OUT_MULT_ACCOUNT:
return "多实例登录";
case uni.$TIM.TYPES.KICKED_OUT_MULT_DEVICE:
return "多设备登录";
case uni.$TIM.TYPES.KICKED_OUT_USERSIG_EXPIRED:
return "userSig 过期";
case uni.$TIM.TIM.TYPES.KICKED_OUT_REST_API:
return "REST API kick 接口踢出";
default:
return "";
}
},
},
};
</script>
<style>
</style>
在 pages.json 文件中的更新 pages 路由:
{
"pages": [
{
"path": "pages/index/index"
}
],
"subPackages": [
{
"root": "TUIKit",
"pages": [
{
"path": "TUIPages/TUIConversation/index",
"style": {
"navigationBarTitleText": "云通信 IM",
}
},
{
"path": "TUIPages/TUIConversation/create",
"style": {
"navigationBarTitleText": "选择联系人",
"app-plus": {
"scrollIndicator": "none"
}
}
},
{
"path": "TUIPages/TUIChat/index",
"style": {
"navigationBarTitleText": "云通信 IM",
"app-plus": {
"scrollIndicator": "none",
"softinputNavBar": "none",
"bounce": "none",
}
}
},
{
"path": "TUIPages/TUIChat/components/message-elements/video-play",
"style": {
"navigationBarTitleText": "云通信 IM",
"app-plus": {}
}
},
{
"path": "TUIPages/TUIGroup/index",
"style": {
"navigationBarTitleText": "群管理",
"app-plus": {
"scrollIndicator": "none"
}
}
},
{
"path": "TUIPages/TUIGroup/memberOperate",
}
]
}
],
"globalStyle": {
"navigationBarTextStyle": "black",
"navigationBarTitleText": "uni-app",
"navigationBarBackgroundColor": "#F8F8F8",
"backgroundColor": "#F8F8F8"
}
}
步骤3: 获取 SDKAppID 、密钥与 userID
设置 App.vue 文件示例代码中的相关参数 SDKAppID、secretKey 以及 userID ,其中 SDKAppID 和密钥等信息,可通过 即时通信 IM 控制台 获取,单击目标应用卡片,进入应用的基础配置页面。例如:

userID 信息,可通过 即时通信 IM 控制台 进行创建和获取,单击目标应用卡片,进入应用的账号管理页面,即可创建账号并获取 userID。例如:

步骤4:运行效果

注意:
如果您需要 github 下载集成,请参见 chat-uikit-uniapp github 源码。
更多高级特性
音视频通话 TUICallKit 插件
说明:
TUIKit 中默认没有集成 TUICallKit 音视频组件。如果您需要集成通话功能,可参考以下文档实现。
TUICallKit 主要负责语音、视频通话。
客户端通话示意图:
小程序通话示意图
TUIOfflinePush 离线推送插件
说明:
TUIKit 中默认没有集成 TUIOfflinePush 离线推送插件。如果您需要在 APP 中集成离线推送能力,请参考官网文档 uni-app 离线推送 实现。
TUIOfflinePush 是腾讯云即时通信 IM Push 插件。目前离线推送支持 Android 和 iOS 平台,设备有:华为、小米、OPPO、vivo、魅族 和 苹果手机。
效果如下图所示:

常见问题
1. 什么是 UserSig?
UserSig 是用户登录即时通信 IM 的密码,其本质是对 UserID 等信息加密后得到的密文。
2. 如何生成 UserSig?
UserSig 签发方式是将 UserSig 的计算代码集成到您的服务端,并提供面向项目的接口,在需要 UserSig 时由您的项目向业务服务器发起请求获取动态 UserSig。更多详情请参见 服务端生成 UserSig。
注意:
本文示例代码采用的获取 UserSig 的方案是在客户端代码中配置 SECRETKEY,该方法中 SECRETKEY 很容易被反编译逆向破解,一旦您的密钥泄露,攻击者就可以盗用您的腾讯云流量,因此该方法仅适合本地跑通功能调试。 正确的 UserSig 签发方式请参见上文。
3. 运行在小程序端:选择运行时压缩代码
4. 运行在小程序端出现异常报错
可能和微信开发者工具版本有关,请使用最新的开发者工具,以及确认稳定的调试基础库版本。
5. 小程序如果需要上线或者部署正式环境怎么办?
请在微信公众平台 > 开发 > 开发管理 > 开发设置 > 服务器域名中进行域名配置:
从v2.11.2起 SDK 支持了 WebSocket,WebSocket 版本须添加以下域名到 socket 合法域名:
域名 |
说明 |
是否必须 |
wss://wss.im.qcloud.com |
Web IM 业务域名 |
必须 |
wss://wss.tim.qq.com |
Web IM 业务域名 |
必须 |
将以下域名添加到 request 合法域名:
域名 |
说明 |
是否必须 |
https://web.sdk.qcloud.com |
Web IM 业务域名 |
必须 |
https://webim.tim.qq.com |
Web IM 业务域名 |
必须 |
https://api.im.qcloud.com |
Web IM 业务域名 |
必须 |
将以下域名添加到 uploadFile 合法域名:
域名 |
说明 |
是否必须 |
https://cos.ap-shanghai.myqcloud.com |
文件上传域名 |
必须 |
https://cos.ap-shanghai.tencentcos.cn |
文件上传域名 |
必须 |
https://cos.ap-guangzhou.myqcloud.com |
文件上传域名 |
必须 |
将以下域名添加到 downloadFile 合法域名:
域名 |
说明 |
是否必须 |
https://cos.ap-shanghai.myqcloud.com |
文件上传域名 |
必须 |
https://cos.ap-shanghai.tencentcos.cn |
文件上传域名 |
必须 |
https://cos.ap-guangzhou.myqcloud.com |
文件上传域名 |
必须 |
参考文档
技术咨询
了解更多详情您可 QQ 咨询:309869925技术交流群