即时通信 IM 微信小程序（uni-app）

二、环境要求

·微信 App iOS 最低版本要求：8.0.40。

·微信 App Android 最低版本要求：8.0.40。

·小程序基础库最低版本要求：2.10.0。

三、开通服务

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

四、开通企业类小程序

小程序推拉流标签不支持个人小程序，只支持企业类小程序。需要在 注册 时填写主体类型为企业：

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

·小程序推拉流标签使用权限暂时只开放给有限类目，具体支持类目参见该地址。

·符合类目要求的小程序，需要在 微信公众平台 > 开发 > 开发管理 > 接口设置中自助开通该组件权限。

·登录小程序控制台更新隐私保护政策，勾选麦克风、摄像头。

六、在小程序控制台配置域名

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

·将以下域名添加到 socket 合法域名：

·将以下域名添加到 request 合法域名：

·将以下域名添加到 uploadFile 合法域名：

·将以下域名添加到 downloadFile 合法域名：

七、快速接入

注意：说明：

注意：Demo：GitHub 完整 Demo 开箱即用，3 分钟跑通音视频通话全功能。

八、步骤1：创建小程序项目（可选）

注意：TUICallKit 组件支持 HBuilderX 和 CLI 脚手架两种集成方式。

HbuilderXCLI 脚手架1. 在 HBuilder 中创建小程序项目。2. 在终端输入 npm init -y，创建 package.json 文件。npm init -y1. 全局安装 vue-cli：npm install -g @vue/cli2. 通过 CLI 创建项目：Vue3（推荐）Vue2创建 js 项目（推荐）创建 ts 项目npx degit dcloudio/uni-preset-vue#vite chat-examplenpx degit dcloudio/uni-preset-vue#vite-ts chat-example推荐选择 TypeScript 模板创建项目。vue create -p dcloudio/uni-preset-vue chat-example3. 创建完成后，切换到项目所在目录：cd chat-example

九、步骤2：下载 TUICallKit 组件

1. 下载组件。

Vue3Vue2 npm i @trtc/calls-uikit-wx-uniapp npm i @trtc/calls-uikit-wx-uniapp unplugin-vue2-script-setup @vue/composition-api

2. 拷贝源码。

HbuilderXCLI 脚手架MacOS 端Windows 端 mkdir -p ./TUICallKit && cp -r node_modules/@trtc/calls-uikit-wx-uniapp/TUICallKit/* ./TUICallKit/ xcopy node_modules\\@trtc\\calls-uikit-wx-uniapp\\TUICallKit .\\TUICallKit /i /eMacOS 端Windows 端mkdir -p ./TUICallKit && cp -r node_modules/@trtc/calls-uikit-wx-uniapp/TUICallKit/* ./src/TUICallKitxcopy node_modules\\@trtc\\calls-uikit-wx-uniapp\\TUICallKit .\\src\\TUICallKit /i /e

十一、1. 配置页面路由

在 pages.json 文件注册全局监听页面。在原有代码中追加如下配置。

{ "path": "TUICallKit/components/CallView/CallView", "style": { "navigationBarTitleText": "uni-app" } }, { "path": "TUICallKit/plugin/groupCall/components/GroupCallView", "style": { "navigationBarTitleText": "uni-app" } }

十二、2. 修改 vue.config.js 文件（Vue3 项目请忽略）

修改 vue.config.js 文件，进行 unplugin-vue2-script-setup 插件的使用，若没有 vue.config.js 文件请新建。

const ScriptSetup = require('unplugin-vue2-script-setup/webpack').default;module.exports = { parallel: false, configureWebpack: { plugins: [ ScriptSetup({}), ], resolve: { // Prevent webpack from following pnpm symlinks to their real .pnpm store // paths. UniApp's compiler uses the resolved path to generate component // references in the output JSON. Without this, it produces unresolvable // paths like `node-modules/.pnpm/@tencentcloud+trtc-component-uniapp@…/…`. symlinks: false, }, }, chainWebpack(config) { config.plugins.delete('fork-ts-checker'); },};

十三、3. 修改 main.js 文件（Vue3 项目请忽略）

修改 main.js 文件，进行 @vue/composition-api 插件的使用。

import vueComposition from "@vue/composition-api" Vue.use(vueComposition)

十四、步骤4：登录组件

注意：说明：

import { useLoginState } from '../../TUICallKit/states/LoginState';const { login } = useLoginState();const loginHandler = async () => { const userID = 'denny'; // 请替换为你的 UserID const SDKAppID = 1400000001; // 请替换为开通服务控制台的 SDKAppID await login({ userId: userID, userSig: 'xxxxxxxxxxx', // 你可以在控制台中计算一个 UserSig 并填在这个位置 sdkAppId: SDKAppID, }); wx.$globalCallPagePath = 'TUICallKit/components/CallView/CallView'; // 配置全局监听页面路径};

登录接口参数说明

十五、步骤5：发起通话

拨打方可以通过调用 calls 函数，并指定通话类型和被叫方的 userID，来发起语音或视频通话。calls 接口同时支持一对一通话和多人通话。当 userIDList 中包含一个 userID 时，为一对一通话；当 userIDList 包含多个 userID 时，则为多人通话。

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

十六、步骤6：接听通话

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

HbuilderXCli 脚手架1. 以编译开发模式的微信小程序为例（编译至其他平台请参考 package.json 文件中 scripts 脚本配置）：npm run build:mp-weixin2. 编译成功后，启动微信开发者工具导入到 dist/build/mp-weixin 目录。

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

十八、设置昵称和头像

首次登录的用户没有头像和昵称信息，你可以通过 setSelfInfo 接口设置头像和昵称。

try { await TUICallKitAPI.setSelfInfo({ nickName: "jack", avatar: "http://xxx", });} catch (error: any) { alert(`[TUICallKit] Failed to call the setSelfInfo API. Reason: ${error}`);}

注意：因为用户隐私限制，非好友之间的通话，被叫的昵称和头像更新可能会有延迟，一次通话成功后就会顺利更新。

十九、铃声设置

你可通过以下方式设置默认铃声、来电静音模式。

·设置默认铃声：通过 setCallingBell 接口设置被叫端收到的来电铃声。

注意：传入本地铃声文件应为相对当前小程序项目的绝对路径。

try { await TUICallKitAPI.setCallingBell('/static/ring.mp3'); // 相对当前小程序项目的绝对路径} catch (error: any) { alert(`[TUICallKit] setCallingBell API failed. Reason: ${error}`);}

·来电静音模式：你可以通过 enableMuteMode 设置静音模式。

try { await TUICallKitAPI.enableMuteMode(enable: boolean);} catch (error: any) { alert(`[TUICallKit] enableMuteMode API failed. Reason: ${error}`);}

20、开启悬浮窗功能

注意：说明：

注意：悬浮窗功能是 TUICallKit 提供的通话最小化能力。该功能仅能用在将 TUICallKit 组件挂载到你自己的业务页面场景下使用，不能用在全局唤醒通话的场景下。

注意：开启后，通话中点击最小化按钮可将通话界面缩小为悬浮窗，自由拖拽且不影响底层页面操作；点击悬浮窗即可恢复全屏通话。推荐在业务页面中集成。

·修改业务页面：在你的业务页面中完成以下改动：

// ===== <template> 新增（与业务内容同级） =====<view v-if="isInCall" class="call-overlay"> <CallView /> <GroupCallView /></view>// ===== <script> 新增 =====import CallView from '../../TUICallKit/components/CallView/CallView.vue';import GroupCallView from '../../TUICallKit/plugin/groupCall/components/GroupCallView.vue';import { useCallParticipantState } from '../../TUICallKit/states/CallParticipantState';import { CallStatus } from '../../TUICallKit/constants/call';const { callParticipantInfo } = useCallParticipantState();const isInCall = computed(() => { const status = callParticipantInfo.value.selfInfo?.status; return status === CallStatus.CALLING || status === CallStatus.CONNECTED;});// ===== <style> 新增 =====.call-overlay { position: fixed; top: 0; left: 0; width: 100vw; height: 100vh; z-index: 1000; pointer-events: none;}

注意：pointer-events: none 不可省略，否则最小化后浮层会拦截底层页面的触摸事件。

·启用悬浮窗。回到 步骤 4 的登录逻辑，将 wx.$globalCallPagePath = '…' 替换为以下内容：

TUICallKitAPI.enableFloatWindow(true);

·移除 pages.json 中的通话页面注册。开启悬浮窗后不再需要页面跳转路由，删除以下两项：

{ "pages": [ // 删除以下两项 // { "path": "TUICallKit/components/CallView/CallView", … }, // { "path": "TUICallKit/plugin/groupCall/components/GroupCallView", … } ]}

21、组件体积速查与插件裁剪指南

TUICallkit 组件接入后以下的功能模块是全量集成的，你可以按需进行裁剪。

23、替换图标按钮

你可以直接修改 TUICallKit/Components/assets 文件夹下的图标组件，以确保整个应用中的图标色调风格保持一致，请在替换时保持图标文件的名字不变。

注意：v3.2.2+ 支持。

24、隐藏按钮

调用 hideFeatureButton 接口隐藏按钮，目前支持 Camera、Microphone、SwitchCamera、InviteUser，具体看枚举类型 FeatureButton。

注意：v3.2.9+ 支持。

以隐藏摄像头按钮为例。

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

25、自定义通话背景图

通话背景图会在语音通话或者视频通话关闭摄像头后出现，通过调用 setLocalViewBackgroundImage 修改本地用户通话界面背景图，setRemoteViewBackgroundImage 修改远端用户通话界面背景图。

注意：v3.2.9+ 支持。

import { TUICallKitAPI } from "../../TUICallKit/index";TUICallKitAPI.setLocalViewBackgroundImage('http://xxx.png');TUICallKitAPI.setRemoteViewBackgroundImage('remoteUserId', 'http://xxx.png');

26、常见问题

如果你的接入和使用中遇到问题，请参见 常见问题。

27、Vue2 iOS 小程序播放铃声没有声音？

Vue2 的铃声播放只支持线上地址，可以在 TUICallKit/plugin/ring/index.ts 中，将本地的相对路径地址改为你的铃声线上地址。

28、Vue2 & Vue3 缺少 sass 预处理器报错：Preprocessor dependency "sass" not found. Did you install it?

请按照以下步骤操作：

npm install sass –save-dev

29、Vue2 & Vue3 装饰器报错： Transforming JavaScript decorators to the configured target environment is not supported yet

可在 tsconfig.json 中添加相关配置，示例：

{ "compilerOptions": { "experimentalDecorators": true }}

30、Vue2 项目报错 TS 编译器类型检查错误

·main.js 中引入组合式 API。

import VueCompositionAPI from "@vue/composition-api";Vue.use(VueCompositionAPI);

·安装 unplugin-vue2-script-setup 依赖。

npm i unplugin-vue2-script-setup

·新建或修改项目根目录的 vue.config.js 文件。

const ScriptSetup = require('unplugin-vue2-script-setup/webpack').default;module.exports = { parallel: false, configureWebpack: { plugins: [ ScriptSetup({}), ], }, chainWebpack(config) { config.plugins.delete('fork-ts-checker'); // disable type check and let `vue-tsc` handles it },};

31、如何适配通过 CLI 创建 Vue2 的 JS 项目？

按照这篇的步骤集成后，需要在项目的根目录下执行：

vue add typescript

按照如下配置项进行选择（为了保证能同时支持原有 js 代码 与 TUICallKit 中 ts 代码，请你务必严格按照以下五个选项进行配置），安装完成后检查 App.vue 文件代码并重新编译。

32、交流与反馈

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