uni-app(小程序)

最近更新时间:2025-10-31 16:09:12

我的收藏
本文将介绍如何快速接入 TUICallKit 组件。您可以在 10 分钟内完成以下关键步骤,最终获得一个功能完备的音视频通话界面。
聊天页面
语音通话
视频通话






注意:
如果您使用 uni-app(小程序)脚手架工具创建的项目,集成指引请点击 uni-app(小程序)脚手架 查看。

准备工作

环境要求

微信 App iOS 最低版本要求:8.0.40。
微信 App Android 最低版本要求:8.0.40。
小程序基础库最低版本要求:2.10.0。
注意:
由于小程序测试号不具备 <live-pusher> 和 <live-player> 的使用权限,请使用企业小程序账号申请相关权限进行开发。
由于微信开发者工具不支持原生组件(即 <live-pusher> 和 <live-player> 标签),需要在真机上进行运行体验。

开通服务

在使用腾讯云提供的音视频服务前,您需要前往控制台,为应用开通音视频服务。具体步骤详见 开通服务。开通服务后,请记录获取 SDKAppID、SecretKey,在后续的步骤中会用到。

开通企业类小程序

小程序推拉流标签不支持个人小程序,只支持企业类小程序。需要在 注册 时填写主体类型为企业,如下图所示:


在小程序控制台开启实时音视频接口

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


在小程序控制台配置域名

微信公众平台 > 开发 > 开发管理 > 开发设置 > 服务器域名中设置 request 合法域名 socket 合法域名

将以下域名添加到 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
文件下载域名
必须

快速接入

创建小程序项目(可选)

1. 在 HBuilder 中创建小程序项目。

2. 在终端输入npm init -y,创建 package.json 文件。
npm init -y

下载 TUICallKit 组件

1. 下载组件。
Vue3
Vue2
npm i tuikit-atomicx-uniapp-wx
npm i tuikit-atomicx-uniapp-wx@vue2
2. 拷贝源码。
MacOS 端
Windows 端
mkdir -p ./TUICallKit && cp -r node_modules/tuikit-atomicx-uniapp-wx/ ./TUICallKit && cp node_modules/@trtc/call-engine-lite-wx/RTCCallEngine.wasm.br ./static
xcopy node_modules\\tuikit-atomicx-uniapp-wx .\\TUICallKit /i /e
xcopy node_modules\\@trtc\\call-engine-lite-wx\\RTCCallEngine.wasm.br .\\static

配置页面路由

在 pages.json 文件注册全局监听页面。
{
"path": "TUICallKit/components/CallView/CallView",
"style": {
"navigationBarTitleText": "uni-app"
}
}

填写 SDKAPPID 以及 SECRETKEY

修改 TUICallKit/debug/GenerateTestUserSig-es.js 文件的 SDKAPPID 以及 SECRETKEY
说明:
鉴权文件在生产环境下需要移除,使用后台生成 UserSig,可以减少 150 KB 包体积。


登录组件

说明:
1. 如果您的应用要求用户启动后必须立即登录,建议将登录初始化代码放置在应用入口组件(如 App.vue)的 onLaunch 生命周期钩子中。
2. 如果您的应用有一个明确的登录按钮,则这段代码应作为该按钮的 onClick 或 @click 事件的处理函数。
import { useLoginState } from '../../TUICallKit';
import * as GenerateTestUserSig from '../../TUICallKit/debug/GenerateTestUserSig-es.js';

const { login } = useLoginState();

const loginHandler = async () => {
const userID = ''; // 填写登录的 userID
const { userSig, SDKAppID } = GenerateTestUserSig.genTestUserSig({ userID });
await login({
userId: userID,
userSig,
sdkAppId: SDKAppID,
});
wx.$globalCallPagePath = 'TUICallKit/components/CallView/CallView'; // 配置全局监听页面路径
};

设置昵称和头像(可选)

首次登录的用户没有头像和昵称信息,您可以通过 setSelfInfo 接口设置头像和昵称。
try {
await TUICallKitAPI.setSelfInfo({
nickName: "jack",
avatar: "http://xxx",
});
} catch (error: any) {
alert(`[TUICallKit] Failed to call the setSelfInfo API. Reason: ${error}`);
}
注意:
因为用户隐私限制,非好友之间的通话,被叫的昵称和头像更新可能会有延迟,一次通话成功后就会顺利更新。

发起通话

拨打方可以通过调用 calls 函数,并指定通话类型和被叫方的 userID,来发起语音或视频通话。calls 接口同时支持一对一通话和多人通话。当 userIDList 中包含一个 userID 时,为一对一通话;当 userIDList 包含多个 userID 时,则为多人通话。
import { useCallListState } from '../../TUICallKit';

const { calls } = useCallListState();

const callHandler = async () => {
await calls({
userIDList: ['mike'], // 请输入被呼叫用户的 userID(需确保该用户已完成一次登录),当前仅支持一对一通话
type: 2, // 通话类型:1: 语音通话 2: 视频通话
});
};

注意:
第一次使用小程序通话,需要获取摄像头和麦克风权限。

接听通话

接听端完成登录后,拨打端发起通话,接收端就可以收到通话邀请,同时伴随铃声。

集成完整版本(可选)

说明:
如果您需要更丰富的功能,可以选择集成完整版。下表对比了精简版和完整版的功能与体积。
功能区分
精简版
完整版
1v1 视频、音频通话
全局监听来电
微信同款 UI 设计
呼叫/接听/拒绝/挂断
群组通话(9人及以下)
-
中途呼叫/加入三方通话
-
自定义呼叫铃声
-
体积大小
0.6 MB
1.65 MB
1. 下载并导入 TUICallKit 组件
注意:
如果您当前使用的是精简版,请先移除之前配置的相关代码,然后再进行完整版的集成。
MacOS 端
Windows 端
npm i @trtc/calls-uikit-wx-uniapp
mkdir -p ./TUICallKit && cp -r node_modules/@trtc/calls-uikit-wx-uniapp/ ./TUICallKit && cp node_modules/@trtc/call-engine-lite-wx/RTCCallEngine.wasm.br ./static
npm i @trtc/calls-uikit-wx-uniapp
xcopy node_modules\\@trtc\\calls-uikit-wx-uniapp .\\TUICallKit /i /e
xcopy node_modules\\@trtc\\call-engine-lite-wx\\RTCCallEngine.wasm.br .\\static
2. 填写 SDKAPPID 以及 SECRETKEY
修改 TUICallKit/debug/GenerateTestUserSig-es.js文件 的 SDKAPPID 以及 SECRETKEY。



3. 调用 TUICallKit 组件
说明:
根据您的项目类型选择合适的集成方式
Vue3 的 uniapp 小程序使用 vite 打包,分包中的依赖会被打入主包中,可以参考 @uni-ku/bundle-optimizer 这个插件进行优化。
接入方式
主包接入
分包接入
能否使用全局监听
是否占用主包体积
主包接入
分包接入
注意:
主包接入的方式默认集成全局监听。
在 pages.json 文件注册全局监听页面。
{
"path": "TUICallKit/src/Components/TUICallKit",
"style": {
"navigationBarTitleText": "uni-app"
}
}
Vue3
Vue2
1. 修改 pages/index/index.vue 文件。
<template>
<view class="loginBox">
<input
class="input-box"
v-model="userID"
:placeholder="!isLogin ? '请输入用户ID' : '搜索用户ID'"
placeholder-style="color:#BBBBBB;"
/>
<view class="login">
<button
class="loginBtn"
@click="!isLogin ? loginHandler() : callHandler()"
>
{{ !isLogin ? "登录" : "呼叫" }}
</button>
</view>
</view>
</template>
<script setup>
import { ref } from "vue";
import * as GenerateTestUserSig from "../../TUICallKit/debug/GenerateTestUserSig-es.js";
// 导入 TUICallKitAPI 模块,使您的应用具有全局呼叫的能力
import { TUICallKitAPI } from "../../TUICallKit/src/index";
// 导入 CallManager 模块,使您的应用具有全局监听来电的能力
import { CallManager } from "../../TUICallKit/src/TUICallService/serve/callManager";
uni.CallManager = new CallManager();
let userID = ref("");
let isLogin = ref(false);
const loginHandler = async () => {
if (!userID.value) return;
const { userSig, SDKAppID } = GenerateTestUserSig.genTestUserSig({
userID: userID.value,
});
await uni.CallManager.init({
sdkAppID: SDKAppID,
userID: userID.value,
userSig: userSig,
globalCallPagePath: "TUICallKit/src/Components/TUICallKit",
});
isLogin.value = true;
userID.value = "";
};

const callHandler = async () => {
await TUICallKitAPI.calls({
userIDList: [userID.value],
type: 2,
});
};
</script>
<style>
.loginBox {
margin-top: 200px;
display: flex;
flex-direction: column;
align-items: center;
justify-content: center;
}

input {
display: flex;
font-size: 20px;
}

.login {
width: 100vw;
bottom: 5vh;
margin: 70rpx;
}

.login button {
width: 80%;
background-color: #006eff;
border-radius: 50px;
color: white;
}
</style>
1. 下载依赖。
npm i unplugin-vue2-script-setup
2. 修改 vue.config.js 文件。
const ScriptSetup = require('unplugin-vue2-script-setup/webpack').default;
module.exports = {
parallel: false,
configureWebpack: {
plugins: [
ScriptSetup({
/* options */
}),
],
},
chainWebpack(config) {
config.plugins.delete('fork-ts-checker');
},
};
3. 修改 main.js 文件。
import vueComposition from "@vue/composition-api"
Vue.use(vueComposition)
4. 修改 pages/index/index.vue 文件。
<template>
<view>
<view class="loginBox">
<input
class="input-box"
v-model="userID"
:placeholder="!isLogin ? '请输入用户ID' : '搜索用户ID'"
placeholder-style="color:#BBBBBB;"
/>
<view class="login">
<button
class="loginBtn"
@click="!isLogin ? loginHandler() : callHandler()"
>
{{ !isLogin ? "登录" : "呼叫" }}
</button>
</view>
</view>
</view>
</template>
<script>
import * as GenerateTestUserSig from "../../TUICallKit/debug/GenerateTestUserSig-es.js";
// 导入 TUICallKitAPI 模块,使您的应用具有全局呼叫的能力
import { TUICallKitAPI } from "../../TUICallKit/src/index";
// 导入 CallManager 模块,使您的应用具有全局监听来电的能力
import { CallManager } from "../../TUICallKit/src/TUICallService/serve/callManager";
uni.CallManager = new CallManager();
export default {
data() {
return {
isLogin: false,
userID: "",
};
},
methods: {
async loginHandler() {
if (!this.userID) return;
const { userSig, SDKAppID } = GenerateTestUserSig.genTestUserSig({
userID: this.userID,
});
await uni.CallManager.init({
sdkAppID: SDKAppID,
userID: this.userID,
userSig: userSig,
globalCallPagePath: "TUICallKit/src/Components/TUICallKit",
});
this.isLogin = true;
this.userID = "";
},

async callHandler() {
await TUICallKitAPI.calls({
userIDList: [this.userID],
type: 2,
});
},
},
};
</script>
<style>
.loginBox {
margin-top: 200px;
display: flex;
flex-direction: column;
align-items: center;
justify-content: center;
}

input {
display: flex;
font-size: 20px;
}

.login {
width: 100vw;
bottom: 5vh;
margin: 70rpx;
}

.login button {
width: 80%;
background-color: #006eff;
border-radius: 50px;
color: white;
}
</style>
1. 修改 manifest.json 小程序相关配置。
"mp-weixin": {
"usingComponents": true,
"optimization": {
"subPackages": true
}
},
2. 新建 /TUICallKit/pages/call.vue 目录。



3. 修改 pages.json,添加分包页面。
"subPackages": [
{
"root": "TUICallKit",
"pages": [
{
"path": "pages/call",
"style": {
"navigationBarTitleText": "uni-app"
}
}
]
}
],
4. 集成 TUICallKit。
Vue3 环境
Vue2 环境
修改 TUICallKit/pages/call.vue 文件。
<template>
<view>
<TUICallKit></TUICallKit>
<view class="loginBox">
<input
class="input-box"
v-model="userID"
:placeholder="!isLogin ? '请输入用户ID' : '搜索用户ID'"
placeholder-style="color:#BBBBBB;"
/>
<view class="login">
<button
class="loginBtn"
@click="!isLogin ? loginHandler() : callHandler()"
>
{{ !isLogin ? "登录" : "呼叫" }}
</button>
</view>
</view>
</view>
</template>
<script setup>
import { ref } from "vue";
import * as GenerateTestUserSig from "../debug/GenerateTestUserSig-es.js";
import { TUICallKitAPI } from "../src/index";
import TUICallKit from "../src/Components/TUICallKit";
let userID = ref("");
let isLogin = ref(false);
const loginHandler = async () => {
if (!userID.value) return;
const { userSig, SDKAppID } = GenerateTestUserSig.genTestUserSig({
userID: userID.value,
});
await TUICallKitAPI.init({
sdkAppID: SDKAppID,
userID: userID.value,
userSig: userSig,
});
isLogin.value = true;
userID.value = "";
};

const callHandler = async () => {
await TUICallKitAPI.calls({
userIDList: [userID.value],
type: 2,
});
};
</script>
<style>
.loginBox {
margin-top: 200px;
display: flex;
flex-direction: column;
align-items: center;
justify-content: center;
}

input {
display: flex;
font-size: 20px;
}

.login {
width: 100vw;
bottom: 5vh;
margin: 70rpx;
}

.login button {
width: 80%;
background-color: #006eff;
border-radius: 50px;
color: white;
}
</style>

1. 下载依赖。
npm i unplugin-vue2-script-setup
2. 修改vue.config.js文件。
const ScriptSetup = require('unplugin-vue2-script-setup/webpack').default;
module.exports = {
parallel: false,
configureWebpack: {
plugins: [
ScriptSetup({
/* options */
}),
],
},
chainWebpack(config) {
config.plugins.delete('fork-ts-checker');
},
};
3. 修改main.js文件。
import vueComposition from "@vue/composition-api"
Vue.use(vueComposition)
4. 修改 TUICallKit/pages/call.vue 文件。
<template>
<view>
<TUICallKit></TUICallKit>
<view class="loginBox">
<input
class="input-box"
v-model="userID"
:placeholder="!isLogin ? '请输入用户ID' : '搜索用户ID'"
placeholder-style="color:#BBBBBB;"
/>
<view class="login">
<button
class="loginBtn"
@click="!isLogin ? loginHandler() : callHandler()"
>
{{ !isLogin ? "登录" : "呼叫" }}
</button>
</view>
</view>
</view>
</template>
<script>
import * as GenerateTestUserSig from "../debug/GenerateTestUserSig-es.js";
import { TUICallKitAPI } from "../src/index";
import TUICallKit from "../src/Components/TUICallKit.vue";
export default {
components: {
TUICallKit,
},
data() {
return {
isLogin: false,
userID: "",
};
},
methods: {
async loginHandler() {
if (!this.userID) return;
const { userSig, SDKAppID } = GenerateTestUserSig.genTestUserSig({
userID: this.userID,
});
await TUICallKitAPI.init({
sdkAppID: SDKAppID,
userID: this.userID,
userSig: userSig,
});
this.isLogin = true;
this.userID = "";
},

async callHandler() {
await TUICallKitAPI.calls({
userIDList: [this.userID],
type: 2,
});
},
},
};
</script>
<style>
.loginBox {
margin-top: 200px;
display: flex;
flex-direction: column;
align-items: center;
justify-content: center;
}

input {
display: flex;
font-size: 20px;
}

.login {
width: 100vw;
bottom: 5vh;
margin: 70rpx;
}

.login button {
width: 80%;
background-color: #006eff;
border-radius: 50px;
color: white;
}
</style>
5. 修改 pages/index/index.vue 文件。
说明:
此处的代码的作用是,主包路由跳转到 TUICallKit 分包页面,注意需要根据您的业务进行调整,此处以空项目举例。
<template>
<view>
<button @click="jumpUrl">跳转分包</button>
</view>
</template>
<script>
export default {
methods: {
jumpUrl() {
uni.navigateTo({ url: "/TUICallKit/pages/call" });
},
},
};
</script>
注意:
如果使用 HBuilder X 4.x 以上版本运行 Vue3 出现如下报错:



可在 tsconfig.json 中添加相关配置,示例:
{
"compilerOptions": {
"experimentalDecorators": true
}
}

更多功能(完整版支持)

开启悬浮窗功能

您可以通过调用 enableFloatWindow 开启/关闭悬浮窗功能,在初始化 TUICallKit 组件时启用该功能,默认状态为关闭(false)。可通过点击通话界面左上角的悬浮窗按钮,将通话界面缩小为悬浮窗形式。

调用 enableFloatWindow(enable: boolean) API 开启/关闭悬浮窗。
TUICallKitAPI.enableFloatWindow(true)

铃声设置

您可通过以下方式设置默认铃声、来电静音模式。
设置默认铃声(方式1):通过 setCallingBell 接口设置被叫端收到的来电铃声。
注意:
传入本地铃声文件应为相对当前小程序项目的绝对路径。
uni-app 打包 Vue2 项目没有铃声,具体参见:Vue2 uni-app 打包微信小程序项目中,铃声没有声音?。
try {
await TUICallKitAPI.setCallingBell('/static/ring.mp3'); // 相对当前小程序项目的绝对路径
} catch (error: any) {
alert(`[TUICallKit] setCallingBell API failed. Reason: ${error}`);
}
设置默认铃声(方式2):如果您通过源码集成 TUICallKit 组件,通过替换铃声文件来达到替换铃声的目的。替换 'TUICallKit/src/TUICallService/assets/' 文件。
文件名
用途
phone_dialing.mp3
发起呼叫时的铃音
phone_ringing.mp3
接到呼叫时的铃音
来电静音模式:您可以通过 enableMuteMode 设置静音模式。
try {
await TUICallKitAPI.enableMuteMode(enable: boolean)
} catch (error: any) {
alert(`[TUICallKit] enableMuteMode API failed. Reason: ${error}`);
}

自定义您的 UI(完整版支持)

替换图标按钮

您可以直接修改 TUICallKit/Components/assets 文件夹下的图标组件,以确保整个应用中的图标色调风格保持一致,请在替换时保持图标文件的名字不变。
注意:
v3.2.2+ 支持


序号
资源路径
1
/TUICallKit/Components/assets/button/mobile/minimize.svg
2
/TUICallKit/Components/assets/button/hangup.svg
3
/TUICallKit/Components/assets/button/accept.svg
4
/TUICallKit/Components/assets/button/microphone-open.svg
5
/TUICallKit/Components/assets/button/speaker-open.svg
6
/TUICallKit/Components/assets/button/camera-close.svg
7
/TUICallKit/Components/assets/button/switchCamera.svg

隐藏按钮

调用 hideFeatureButton 接口隐藏按钮,目前支持 Camera、Microphone、SwitchCamera、InviteUser,具体看枚举类型 FeatureButton
注意:
v3.2.9+ 支持
以隐藏摄像头按钮为例。

// 替换成 TUICallKit 源码中的地址
import { TUICallKitAPI, FeatureButton } from "../../TUICallKit/src/index";

TUICallKitAPI.hideFeatureButton(FeatureButton.Camera);

自定义通话背景图

通话背景图会在语音通话或者视频通话关闭摄像头后出现,通过调用 setLocalViewBackgroundImage 修改本地用户通话界面背景图,setRemoteViewBackgroundImage 修改远端用户通话界面背景图。
注意:
v3.2.9+ 支持

import { TUICallKitAPI } from "../../TUICallKit/src/index";

TUICallKitAPI.setLocalViewBackgroundImage('http://xxx.png');
TUICallKitAPI.setRemoteViewBackgroundImage('remoteUserId', 'http://xxx.png');

常见问题

如果您的接入和使用中遇到问题,请参见 常见问题

交流与反馈

如果您在使用过程中,有什么建议或者意见,可以 联系我们,感谢您的反馈。