TUIRoomKit 是腾讯云推出的音视频房间 UI 应用。本次升级引入了全新的原子化组件接入方案,开发者可以灵活组合这些原子化组件,以构建个性化的音视频房间界面。
本文档介绍如何将 TUIRoomKit 集成到现有的 Vue3 项目中,同时介绍如何对 TUIRoomKit 的样式、布局及功能进行自定义修改。
桌面端多人会议

H5 多人会议

前提条件
开通服务
SDKAppID: 应用标识,腾讯云基于
SDKAppID 完成计费统计。SDKSecretKey: 应用密钥,用于初始化配置文件的密钥信息。
环境准备
Node.js: ≥ 18.19.1 (推荐使用官方 LTS 版本)。
Vue: ≥ 3.4.21。
现代浏览器:支持 WebRTC APIs 的现代浏览器。
设备:摄像头、麦克风、扬声器。
源码接入
步骤1:安装项目依赖
在您的业务项目中安装以下依赖。
npm install @tencentcloud/roomkit-web-vue3@latest tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/universal-api
pnpm install @tencentcloud/roomkit-web-vue3@latest tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/universal-api
yarn add @tencentcloud/roomkit-web-vue3@latest tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/universal-api
步骤2:引用 TUIRoomKit 组件
<template><ConferenceMainView v-if="isPC"></ConferenceMainView><ConferenceMainViewH5 v-else></ConferenceMainViewH5></template><script setup>import { ref } from 'vue';import { ConferenceMainView, ConferenceMainViewH5 } from '@tencentcloud/roomkit-web-vue3';import { getPlatform } from '@tencentcloud/universal-api';const isPC = ref(getPlatform() === 'pc');</script>
步骤3:配置 App.vue 文件
将以下内容合并到项目的 App.vue 文件中,以配置全局 UI 样式和用户登录逻辑:
配置全局
UIKitProvider:引入 UIKitProvider 组件,并设置默认主题和语言;用户登录: 在
onMounted 钩子中执行 login 和 setSelfInfo;<template><!-- Step 1: 配置全局 UIKitProvider --><UIKitProvider theme="light" language="zh-CN"><!-- 您包含 ConferenceMainView 的业务组件 --></UIKitProvider></template><script setup>import { UIKitProvider } from '@tencentcloud/uikit-base-component-vue3';import { onMounted } from 'vue';import { useLoginState } from 'tuikit-atomicx-vue3/room';// step 2: 用户登陆const { login, setSelfInfo } = useLoginState();const SDKAppID = 0; // 注意:请替换为实时音视频控制台获取的 SDKAppID 信息const userId = '填入您真实的 userId'; // 注意:请替换为真实的 userIdconst userName = '填入您真实的 userName'; // 注意:请替换为真实的 userNameconst userSig = '填入您真实的 userSig'; // 注意:生成临时 userSig 请参考 https://cloud.tencent.com/document/product/647/17275#consoleonMounted(async () => {try {await login({userId,userSig,sdkAppId: SDKAppID,});await setSelfInfo({userName,avatarUrl: '',});} catch (error: any) {console.error('Login failed:', error);}});</script><!-- Step 3: 配置全局样式(此样式用来覆盖脚手架搭建的新项目的默认样式,可按需配置)--><style>html, body {padding: 0 !important;margin: 0 !important;}#app {width: 100% !important;height: 100% !important;padding: 0 !important;margin: 0 !important;max-width: 100% !important;max-height: 100% !important;text-align: left !important;overflow: hidden;}</style>
步骤4:发起新的会议
注意:
请参考步骤 3 在用户登录成功后调用
conference.start 接口发起会议。import { conference } from '@tencentcloud/roomkit-web-vue3';const startConference = async () => {await conference.start({roomId: '123456', // 请替换为您真实的 roomIdoptions: {roomName: '我的临时会议',},});}startConference();
步骤5:进入已有会议
注意:
请参考步骤 3 在用户登录成功后调用
conference.join 接口加入会议。import { conference } from '@tencentcloud/roomkit-web-vue3';const joinConference = async () => {await conference.join({roomId: '123456', // 请替换为您真实的 roomId});}joinConference();
启动项目
npm run dev
pnpm run dev
yarn run dev
启动成功后,请在浏览器中打开调试地址(通常为 http://localhost:5173)访问应用。您将看到如下所示的会议界面:

UI 快速自定义
主题及语言
通过配置 App.vue 中
UIKitProvider 的入参,修改主题及语言的默认值。UIKitProvider 参数 | 可选值 | 默认值 |
theme | "light" | "dark" | "light" |
language | "zh-CN" | "en-US" | "en-US" |
<UIKitProvider theme="light" language="zh-CN"><router-view /></UIKitProvider><script setup lang="ts">import { UIKitProvider } from '@tencentcloud/uikit-base-component-vue3';
配置用户联系人列表
TUIRoomKit 预定会议用户选择列表和会中呼叫用户选择列表默认展示用户关系链列表,批量导入用户关系链请参考以下步骤:

TUIRoomKit 界面定制
源码导出
1. 执行源码导出脚本,默认拷贝路径为
./src/components/RoomKitnode ./node_modules/@tencentcloud/roomkit-web-vue3/scripts/eject.js
2. 根据脚本提示确认是否要将 TUIRoomKit 源码拷贝到
./src/components/RoomKit 目录。如您需要自定义拷贝目录请输入 'y', 否则输入'n'。
3. 源码导出后,在您指定的项目路径中会新增 TUIRoomKit 源码。此时,您需要手动将 ConferenceMainView 组件,ConferenceMainViewH5 组件的 conference 对象的引用从 npm 包地址更改为 TUIRoom 源码的相对路径地址。
- import { ConferenceMainView, conference } from '@tencentcloud/roomkit-web-vue3';// 替换引用路径为 TUIRoomKit 源码的真实路径+ import { ConferenceMainView, ConferenceMainViewH5, conference } from './components/RoomKit/index.ts';
4. 配置 ESLint 校验
如果您导出 TUIRoomKit 源码后运行项目出现 ESLint 报错,您可以在
.eslintignore文件中添加 RoomKit 文件夹忽略 ESLint 检测。// 请替换为 TUIRoomKit 源码真实路径src/components/RoomKit
自定义房间流布局
TUIRoomKit 目前支持九宫格、侧边栏及顶部栏三种流布局,默认为九宫格布局。
// RoomKit/views/ConferenceMainView/index.vueimport { RoomLayoutTemplate } from 'tuikit-atomicx-vue3/room';// 修改默认视频流布局为侧边栏布局const participantViewLayout = ref(RoomLayoutTemplate.SidebarLayout);function handleLayoutUpdate(layout: RoomLayoutTemplate) {participantViewLayout.value = layout;}// 修改默认视频流布局为顶部栏布局const participantViewLayout = ref(RoomLayoutTemplate.CinemaLayout);function handleLayoutUpdate(layout: RoomLayoutTemplate) {participantViewLayout.value = layout;}
自定义视频流挂件
TUIRoomKit 默认视频流挂件如图所示,如需自定义视频流挂件请修改
RoomKit/components/RoomLayoutView/ParticipantViewUI/ParticipantViewUI.vue 组件。
常见问题
TUIRoomKit 在本地开发时使用正常,但部署到线上环境后无法正常采集用户的摄像头或麦克风设备?
原因分析:浏览器出于安全和隐私保护的考虑,对音视频设备(麦克风、摄像头)的采集有着严格限制。只有在安全环境下,采集操作才会被允许。安全环境协议包括:https://、localhost、file:// 等。HTTP 协议被视为不安全,浏览器会默认禁止访问媒体设备。
解决方案:若您在本地(localhost)测试一切正常,但部署后出现采集失败,请立即检查您的网页是否部署在 HTTP 协议上。您必须使用 HTTPS 协议部署您的网页,并确保具备有效的安全证书。
相关资源:更多关于 URL 域名及协议的限制详情,请参见 URL 域名及协议限制说明。
TUIRoomKit 是否支持使用 iframe 集成?
支持。使用 iframe 集成 TUIRoomKit 时, 需要在 iframe 标签中配置 allow 属性以授予必要的浏览器权限(麦克风、摄像头、屏幕共享、全屏等),示例如下:
// 开启麦克风、摄像头、屏幕分享、全屏权限<iframe allow="microphone; camera; display-capture; display; fullscreen;">
TUIRoomKit 是否支持设置内网代理?
// 请在进房前设置内网代理参数import TUIRoomEngine from '@tencentcloud/tuiroom-engine-js';import { useRoomEngine } from 'tuikit-atomicx-vue3/room';const { roomEngine } = useRoomEngine();TUIRoomEngine.once('ready', () => {const trtcCloud = roomEngine.instance?.getTRTCCloud();trtcCloud.callExperimentalAPI(JSON.stringify({api: 'setNetworkProxy',params: {websocketProxy: "wss://proxy.example.com/ws/",turnServer: [{url: '14.3.3.3:3478',username: 'turn',credential: 'turn',}],iceTransportPolicy: 'relay',},}));});