实时音视频 uni-app (客户端)

TUIRoomKit 是腾讯云提供的一站式多人视频会议解决方案，集成了完整的 UI 组件和核心功能。通过本文档，开发者可以快速了解如何将 TUIRoomKit 集成到项目中，实现多人视频会议功能。本文还将详细介绍如何快速接入 UI 项目，替换图片资源，自定义样式，帮助开发者打造符合品牌特色的音视频应用。
房间准备页
房间主页
成员管理
﻿
﻿
﻿
﻿
﻿
﻿
﻿
﻿
﻿
前提条件
开通服务
请参考 开通服务 领取 TUIRoomKit 体验版，并在 应用管理 页面获取以下信息：
SDKAppID：应用标识（必填），腾讯云基于 SDKAppID 完成计费统计。
SDKSecretKey：应用密钥，用于初始化配置文件的密钥信息。
环境准备
说明：
HBuilderX 4.64 和 4.65 版本对 UTS 插件打包存在已知兼容性问题，建议使用 4.66 或更高版本。
﻿HBuilderX：HBuilderX 是 uni-app 官方的集成开发环境（IDE），我们需要用它来导入、配置和运行我们的 Demo。
2个移动设备： Android 5.0 以上的设备 / iOS 13.0 及以上设备。
快速接入
步骤1：下载 TUIRoomKit 组件
1. 克隆项目源码
git clone https://github.com/Tencent-RTC/TUIKit_uni-app.git﻿
2. 导入 atomic-x 组件
将源码中 TUIKit_uni-app/App/uni_modules 目录下的 tuikit-atomic-x 文件夹，完整拷贝到您项目根目录下的 uni_modules 文件夹中。
将源码中 TUIKit_uni-app/App/components 下的文件，完整的拷贝到您项目的 components 文件夹中。
将源码中 TUIKit_uni-app/App/static 目录下的文件，完整拷贝到您项目根目录下的同名文件夹下。
3. 拷贝创建房间，加入房间，房间主界面等页面
将源码中 TUIKit_uni-app/App/pages 目录下的文件，完整拷贝到您项目根目录下的同名文件夹中。
将源码中 TUIKit_uni-app/App/debug 文件夹拷贝到您项目的根目录下，这个目录提供有可以方便您在客户端快速生成的 UserSig 的快捷函数。
4. 合并 App.vue 配置
TUIKit_uni-app/App/App.vue 文件中包含多人视频会议能力的初始化逻辑，因此您需要将 TUIKit_uni-app/App/App.vue 文件和您项目下的 App.vue 文件进行合并。
注意：
不要直接覆盖 App.vue 文件！ 打开源码中的 TUIKit_uni-app/App/App.vue， 将其 <script> 部分的 ts 内容追加到您自己项目的 App.vue 的 <script>  标签内。
步骤2：工程配置
1. 配置 manifest.json
打开您项目的 manifest.json 文件，在 app-plus > distribute 节点下，确保添加了以下必要的权限：
Android 平台（android 节点）：在 permissions 数组中，请确保包含以下权限：
"<uses-permission android:name=\\"android.permission.CAMERA\\"/>",
"<uses-permission android:name=\\"android.permission.RECORD_AUDIO\\" />",
"<uses-permission android:name=\\"android.permission.INTERNET\\"/>",
"<uses-permission android:name=\\"android.permission.ACCESS_NETWORK_STATE\\"/>",
"<uses-permission android:name=\\"android.permission.WRITE_EXTERNAL_STORAGE\\"/>"
iOS 平台（ios 节点）：在 privacyDescription 对象中，请确保包含以下描述：
"NSCameraUsageDescription" : "应用需要访问您的相机以进行多人音视频互动",
"NSMicrophoneUsageDescription" : "应用需要访问您的麦克风以进行多人音视频互动"  
在 UIBackgroundModes 数组中，添加 audio 以支持后台播放音频。
"UIBackgroundModes" : [ "audio" ]
2. 制作自定义基座。
说明：
由于 TUIRoomKit 包含原生代码（UTS 插件），您必须制作自定义调试基座才能在真机上运行。
2.1 在 HBuilderX 顶部菜单选择运行 > 运行到手机或模拟器 > 制作自定义调试基座。
2.2 制作成功后，再次选择运行 > 运行到手机或模拟器，在弹窗中勾选使用自定义调试基座后运行到您的手机。
具体操作指引参见 编译并运行 Demo。
步骤3：登录
集成完成后，您需要完成登录。在您项目中需要使用到多人视频会议能力的地方进行登录，这是使用 TUIRoomKit 的关键步骤，因为只有在登录成功后才能正常使用 TUIRoomKit 的各项功能，故请您耐心检查相关参数是否配置正确：
import { useLoginState } from "@/uni_modules/tuikit-atomic-x/state/LoginState";
﻿
const { login } = useLoginState();
﻿
onMounted(() => {
  login({
	sdkAppID: 1400000001,     // 请替换为开通服务控制台的 SDKAppID
	userID: "your userID",        // 请替换为您的 UserID
	userSig: "xxxxxxxxxxx",  // 您可以在控制台中计算一个 UserSig 并填在这个位置
  });
});
﻿
登录接口参数说明
参数
类型
说明
SDKAppID
Number
从 TRTC 控制台 > 应用管理 获取。
userID
String
当前用户的唯一 ID，仅包含英文字母、数字、连字符和下划线。
userSig
String
用于腾讯云鉴权的票据。请注意：
开发环境：您可以采用本地 GenerateTestUserSig.genTestSig 函数生成 UserSig 或者通过 UserSig 辅助工具 生成临时的 UserSig。
生产环境：为了防止密钥泄露，请务必采用服务端生成 UserSig 的方式。详细信息请参见 服务端生成 UserSig。
更多信息请参见 如何计算及使用 UserSig。
步骤4：注册多人视频会议主页面
现在，您需要在 pages.json 文件中告诉您的应用，这个新页面是存在的。
打开您项目根目录下的 pages.json 文件，在 "pages" 数组中，添加以下对象来注册多人视频会议主页面。
{
    "pages": [
        // ... 您项目已有的其他页面配置
        {
            "path": "pages/scenes/room/main/index",
            "style": {
                "navigationBarTitleText": "",
                "disableSwipeBack": true, // 禁止右滑返回，防止会中误操作退出
                "app-plus": {
                    "titleNView": false // 隐藏原生导航栏，使用页面内的自定义导航
                }
            }
        }
    ]
    // ... 其他配置
}
步骤5：跳转多人视频会议主页面
创建房间
在您需要创建多人视频会议的地方（具体由您的业务决定，在其点击事件里执行），调用 uni.navigateTo 或 uni.redirectTo 方法，即可进入多人视频会议主页面。
// 示例：在一个按钮的点击事件中
function startBroadcast() {
  const roomID = '123456'; //房间id
  const roomName = '123456'; //房间名称
  const query = [
    'mode=create',
    `roomID=${encodeURIComponent(roomID)}`,
    `roomName=${encodeURIComponent(roomName)}`,
    'autoEnableCamera=1',     //进房是否开启摄像头（1 开启， 0 关闭）
    'autoEnableMicrophone=1', //进房是否开启麦克风（1 开启， 0 关闭）
    'autoEnableSpeaker=1',    //进房是否开启扬声器（1 开启， 0 关闭）
  ].join('&');
  uni.navigateTo({ url: `/pages/scenes/room/main/index?${query}` }); // URL 对应 pages.json 中配置的 path
}
说明：
navigateTo 与 redirectTo
uni.navigateTo：保留当前页面，跳转到新页面，用户可以从多人视频会议主页返回到上一页。适用于创建房间前可以取消的场景。
uni.redirectTo：关闭当前页面，跳转到新页面，用户无法返回。适用于支持人直接进入主流程的场景，不需要保存上个界面， 您可以根据自己的业务需求选择使用。
加入房间
在您需要加入多人视频会议的地方（具体由您的业务决定，在其点击事件里执行），调用 uni.navigateTo 或 uni.redirectTo 方法，即可进入多人视频会议主页面。
// 示例：在一个按钮的点击事件中
function startBroadcast() {
  const roomID = '123456'; //房间id
  const query = [
    'mode=join',
    `roomID=${encodeURIComponent(roomID)}`,
    'autoEnableCamera=1',     //进房是否开启摄像头（1 开启， 0 关闭）
    'autoEnableMicrophone=1', //进房是否开启麦克风（1 开启， 0 关闭）
    'autoEnableSpeaker=1',    //进房是否开启扬声器（1 开启， 0 关闭）
  ].join('&');
  uni.navigateTo({ url: `/pages/scenes/room/main/index?${query}` }); // URL 对应 pages.json 中配置的 path
}
定制您的 UI
替换主界面底部栏，顶部栏和视频流用户信息界面图标
TUIRoomKit 用到的所有图标都存放于 static/images 目录下，部分示例如下，您可以根据您的诉求来替换目录下的图标。
顶部栏：
﻿
图标路径
详细描述
/static/images/room/room_switch_camera.png
顶部操作栏切换摄像头图标。
/static/images/room/room_speakerphone.png
顶部操作栏扬声器图标。
/static/images/room/room_earpiece.png
顶部操作栏听筒图标。
底部栏：
﻿
图标路径
详细描述
/static/images/room/room_member.png
底部操作栏成员图标。
/static/images/room/room_mic_on.png
底部操作栏麦克风开启图标。
/static/images/room/room_mic_off.png
底部操作栏麦克风关闭图标。
/static/images/room/room_camera_on.png
底部操作栏摄像头开启图标。
/static/images/room/room_camera_off.png
底部操作栏摄像头关闭图标。
视频流区域用户状态信息：
﻿
图标路径
详细描述
/static/images/room/room_video_view_mic_on.png
视频流用户麦克风开启图标。
/static/images/room/room_video_view_mic_off.png
视频流用户麦克风关闭图标。
/static/images/room/room_video_view_owner.png
视频流用户主持人角色图标。
/static/images/room/room_video_view_admin.png
底部操作栏管理员角色图标。
设置字体的大小/颜色
uni-app 官方对 nvue 页面限制字体的大小和颜色只能在 text 标签上设置，对于您想修改的文案，直接修改其 css 样式即可，示例如下
以 “解除静音” 文字为例：
<template>
  <text class="bottom-text">解除静音</text>
</template>
﻿
<style>
  .bottom-text {
    color: #FFFFFF;
    font-size: 20rpx;
    margin-top: 6rpx;
    text-overflow: ellipsis;
  }
</style>
修改其 css 样式：
<template>
  <text class="bottom-text">开启音频</text>
</template>
﻿
﻿
<style>
 .bottom-text {
    color: red;
    font-size: 24rpx;
    margin-top: 6rpx;
    text-overflow: ellipsis;
  }
</style>
﻿
最终效果：
﻿
设置按钮的大小
设置按钮的大小，也可以直接通过修改 css 属性来进行设置，示例如下：
以底部操作栏麦克风按钮为例：
<template>
<image class="bottom-icon" src="/static/images/room/room_mic_on.png" mode="aspectFit"/>
<text class="bottom-text">解除静音</text>
</template>
﻿
<style>
  .bottom-icon {
    width: 48rpx;
    height: 48rpx;
  }
</style>
设置对应的 css 属性：
<template>
<image class="bottom-icon" src="/static/images/room/room_mic_off.png" mode="aspectFit"/>
<text class="bottom-text">解除静音</text>
</template>
﻿
﻿
<style>
  .bottom-icon {
    width: 70rpx;
    height: 70rpx;
  }
</style>
﻿
最终效果：
﻿
隐藏按钮
隐藏按钮可以通过注释代码的方式来进行直接隐藏，示例如下
以底部操作栏的麦克风按钮为例：
<!-- 底部操作栏 -->
<view class="bottom-bar">
  <MembersButton />
   <!-- <MicButton /> -->   <!-- 隐藏麦克风图标 -->
  <CameraButton />
</view>
将其注释掉即可实现隐藏按钮。
新增按钮
在您需要新增的位置，插入对应的按钮实现。
以底部栏新增“更多”按钮为例：
<template>   
  ......
 <!-- 底部操作栏 -->
    <view class="bottom-bar">
    ......
	  <view class="action-button-item">
	    <image class="bottom-icon" src="/static/images/more.png" mode="aspectFit" />
	    <text class="bottom-text">更多</text>
	  </view>
    </view>
</template>
﻿
<style>
  .bottom-icon {
    width: 48rpx;
    height: 48rpx;
  }
  .bottom-text {
    color: #FFFFFF;
    font-size: 20rpx;
    margin-top: 6rpx;
    text-overflow: ellipsis;
	text-align: center;
  }
</style>
常见问题
Q：该 TUIKit 插件是否支持编译到 H5 或微信小程序？
A：不支持。由于新版 TUIKit 基于 UTS (Uni-app Type Script) 插件架构开发，深度依赖 Android 和 iOS 的原生能力（如原生渲染引擎、本地数据库、音视频编解码），因此仅支持打包为 App (Android/iOS)。
Q：我的现有项目全是 .vue 页面（Webview 渲染），能直接集成吗？
A：可以混用，但需要注意页面模式。
nvue 页面和 vue 页面可以互相跳转，但是 vue 页面的子组件不建议是 nvue 组件。TUIKit 的 UI 组件是 nvue 组件，因此使用 TUIKit 所在的页面（pages）必须也是 nvue 文件。
Q：页面样式错乱、布局塌陷？
A：没有严格遵守 nvue 的 Flex 布局规范。
nvue 页面中：
默认 flex-direction 是 column（纵向），而非 Web 的 row。
文本必须包裹在 <text> 组件中，不能直接写在 <div> 或 <view> 里。
不支持简写属性（例如 margin: 10px 20px），必须写全（margin-top, margin-left 等）。
Q：运行报错 "uni is not defined" 或组件无法加载？
A：请检查是否制作并使用了自定义调试基座。
由于插件包含原生代码（Java/Objective-C），标准基座不包含这些原生库。
解决步骤： 请严格按照文档“运行和测试-步骤2”操作，在 HBuilderX 中点击 运行 > 运行到手机或模拟器 > 制作自定义调试基座。制作完成后，运行时请务必选择运行到 Android/iOS 基座，并勾选“使用自定义基座”。
Q：制作自定义基座时一直失败或卡顿怎么办？
A：这通常是本地原生编译环境（Gradle 或 CocoaPods）配置问题导致的。
Android： 请检查本地 JDK 版本是否兼容，以及网络是否能正常访问 Maven/Google 仓库。
iOS： 请确保已安装 CocoaPods 且版本更新，同时检查网络环境是否能访问 GitHub 或 CDN 库。
联系我们
如果您在接入或使用过程有任何疑问或者建议，欢迎 联系我们 提交反馈。

uni-app (客户端)

本页目录：

前提条件

开通服务

环境准备

快速接入

步骤1：下载 TUIRoomKit 组件

1. 克隆项目源码

2. 导入 atomic-x 组件

3. 拷贝创建房间，加入房间，房间主界面等页面

4. 合并 App.vue 配置

步骤2：工程配置

步骤3：登录

步骤4：注册多人视频会议主页面

步骤5：跳转多人视频会议主页面

创建房间

加入房间

定制您的 UI

替换主界面底部栏，顶部栏和视频流用户信息界面图标

设置字体的大小/颜色

设置按钮的大小

隐藏按钮

新增按钮

常见问题

Q：该 TUIKit 插件是否支持编译到 H5 或微信小程序？

Q：我的现有项目全是 `.vue` 页面（Webview 渲染），能直接集成吗？

Q：页面样式错乱、布局塌陷？

Q：运行报错 "uni is not defined" 或组件无法加载？

Q：制作自定义基座时一直失败或卡顿怎么办？

联系我们

参数	类型	说明
SDKAppID	Number	从 TRTC 控制台 > 应用管理获取。
userID	String	当前用户的唯一 ID，仅包含英文字母、数字、连字符和下划线。
userSig	String	用于腾讯云鉴权的票据。请注意：开发环境：您可以采用本地 `GenerateTestUserSig.genTestSig` 函数生成 UserSig 或者通过 UserSig 辅助工具生成临时的 UserSig。生产环境：为了防止密钥泄露，请务必采用服务端生成 UserSig 的方式。详细信息请参见服务端生成 UserSig。更多信息请参见如何计算及使用 UserSig。

图标路径	详细描述
/static/images/room/room_switch_camera.png	顶部操作栏切换摄像头图标。
/static/images/room/room_speakerphone.png	顶部操作栏扬声器图标。
/static/images/room/room_earpiece.png	顶部操作栏听筒图标。

图标路径	详细描述
/static/images/room/room_member.png	底部操作栏成员图标。
/static/images/room/room_mic_on.png	底部操作栏麦克风开启图标。
/static/images/room/room_mic_off.png	底部操作栏麦克风关闭图标。
/static/images/room/room_camera_on.png	底部操作栏摄像头开启图标。
/static/images/room/room_camera_off.png	底部操作栏摄像头关闭图标。

图标路径	详细描述
/static/images/room/room_video_view_mic_on.png	视频流用户麦克风开启图标。
/static/images/room/room_video_view_mic_off.png	视频流用户麦克风关闭图标。
/static/images/room/room_video_view_owner.png	视频流用户主持人角色图标。
/static/images/room/room_video_view_admin.png	底部操作栏管理员角色图标。