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


前提条件
开通服务
SDKAppID: 应用标识,腾讯云基于
SDKAppID 完成计费统计。SDKSecretKey: 应用密钥,用于初始化配置文件的密钥信息。
环境准备
Node.js: ≥ 18.19.1 (推荐使用官方 LTS 版本)。
Vue: ≥ 3.4.21。
现代浏览器:支持 WebRTC APIs 的现代浏览器。
设备:摄像头、麦克风、扬声器。
源码接入
步骤1:安装项目依赖
在您的业务项目中安装以下依赖。
npm install tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/tuiroom-engine-js vue-router
pnpm install tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/tuiroom-engine-js vue-router
yarn add tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/tuiroom-engine-js vue-router
步骤2:配置开发环境
如果您的项目尚未支持 TypeScript 和 SCSS,请先安装相应的环境依赖。如果已安装,您可以略过此步骤。
npm install typescript sass -S -D
pnpm install typescript sass -S -D
yarn add typescript sass -S -D
步骤3:拷贝核心源码文件
克隆 TUIRoomKit 的 GitHub 仓库,并进入 PC 端 Vue3 示例目录。
git clone https://github.com/Tencent-RTC/TUIRoomKit.git --depth=1cd TUIRoomKit/Web/example/atomicx-vite-vue3-ts
拷贝
TUIRoomKit/Web/example/atomicx-vite-vue3-ts/src 路径下核心源码文件到您的业务项目中。注意:
拷贝源码文件时,请确保与您项目已有的文件夹进行合并,避免直接覆盖已有的同名文件夹。
源路径 (示例项目) | 目标路径 (您的项目) | 说明 |
src/assets/ | src/assets/ | 包含背景图、图标等静态资源。 |
src/components/ | src/components/ | 包含 TUIRoomKit 所有原子 UI 组件 |
src/hooks/ | src/hooks/ | 包含 TUIRoomKit 业务逻辑处理 |
src/i18n/ | src/i18n/ | 包含多语言配置文件 |
src/utils/ | src/utils/ | 包含通用工具函数 |
src/config/ | src/config/ | 包含 basic-info-config.js 等应用配置信息(首次接入请重点关注此文件) |
src/views/home.vue | src/views/home.vue | 该页面包含了设备检测、房间创建/加入的入口功能 |
src/views/room.vue | src/views/room.vue | 该页面是 TUIRoomKit 的核心会议界面,集成了完整的头部、视频布局、控制栏和侧边面板 |
步骤4:配置页面路由
请配置您的 Vue Router,将 home.vue 映射到主页,将 room.vue 映射到会议室页面。
注意:
如果您的业务项目中已有
src/router/index.ts 文件,请将以下内容合并到已有代码中。如果尚未配置路由,请新建
src/router/index.ts 文件并添加以下配置。// src/router/index.ts 示例配置import { createRouter, createWebHistory } from 'vue-router';import Home from '../views/home.vue';import Room from '../views/room.vue';const router = createRouter({history: createWebHistory(),routes: [{path: '/',redirect: '/home',},{path: '/home',name: 'Home',component: Home,},{path: '/room',name: 'Room',component: Room,},],});export default router;
步骤5:配置 App.vue 文件
您需要将以下内容合并到您项目中的 App.vue 文件,以配置全局 UI 样式和用户登录逻辑:
配置全局
UIKitProvider: 引入 UIKitProvider 组件,并设置默认主题和语言;引入页面路由: 渲染 <router-view />;
用户登录: 在
onMounted 钩子中执行 login 和 setSelfInfo;<template><!-- Step 1: 配置全局 UIKitProvider --><UIKitProvider theme="light" language="zh-CN"><!-- Step 2: 引入页面路由 --><router-view /></UIKitProvider></template><!-- 注意添加 lang="ts" 来启用 TypeScript 支持 --><script setup lang="ts">import { UIKitProvider } from '@tencentcloud/uikit-base-component-vue3';import { onMounted } from 'vue';import { SDKAPPID, genTestUserSig } from './config/basic-info-config';import { RoomEvent, useLoginState, useRoomModal } from 'tuikit-atomicx-vue3/room';// step 3: 用户登陆const { login, setSelfInfo } = useLoginState();const { handleErrorWithModal } = useRoomModal();const userId = `user_${Math.ceil(Math.random(0,1)*999)}`;const userName = userId;const userSig = genTestUserSig(userId);onMounted(async () => {try {await login({userId,userSig,sdkAppId: SDKAPPID,});await setSelfInfo({userName,avatarUrl: '',});} catch (error: any) {console.error('Login failed:', error);handleErrorWithModal(error);}});</script><!-- Step 4: 配置全局样式(此样式用来覆盖脚手架搭建的新项目的默认样式,可按需配置) --><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>
步骤6:配置 src/main.ts 文件
将路由和多语言配置合并到您项目中的入口文件 src/main.ts 中:
注意:
如果您项目中的入口文件为 js 文件,请修改文件后缀为 src/main.ts。
// Step 1: 配置页面路由import router from './router/index';const app = createApp(App);// --- 以下为新增代码 ----app.use(router);// --- 以上为新增代码 ----app.mount('#app');// Step 2: 配置多语言资源import { i18next } from '@tencentcloud/uikit-base-component-vue3';import { enResource, zhResource } from './i18n';export const addI18n = (lng: string, resource: any, deep = true, overwrite = false) => {i18next.addResourceBundle(lng, 'translation', resource.translation, deep, overwrite);};addI18n('en-US', { translation: enResource }, true, true);addI18n('zh-CN', { translation: zhResource }, true, true);
启动项目
配置应用信息
在您的项目目录中找到
src/config/basic-info-config.js 配置文件,并将您在腾讯云控制台获取的 SDKAppID 和 SDKSecretKey 填入对应的变量中。
警告:
本文的 Demo 示例中通过在客户端代码中配置
SDKSecretKey 进行鉴权,但 SDKSecretKey 很容易被反编译逆向破解,一旦密钥泄露,攻击者就可以盗用您的腾讯云流量,因此该方法仅适合本地跑通 Demo 和功能调试。 在正式的生产环境中,建议在您的服务端生成 UserSig,在需要 UserSig 时由您的 App 向业务服务器发起请求获取动态 UserSig 来进行鉴权。详见 正式运行阶段如何计算 UserSig?
启动开发服务器
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 目前支持九宫格、侧边栏及顶部栏三种流布局,默认为九宫格布局。
// src/views/room.vue// 修改默认视频流布局为侧边栏布局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 默认视频流挂件如图所示,如您需要自定义视频流挂件请修改
src/components/RoomLayoutView/ParticipantViewUI/ParticipantViewUI.vue 组件。
配置用户联系人列表
TUIRoomKit 预定会议用户选择列表和会中呼叫用户选择列表默认展示用户关系链列表,批量导入用户关系链请参考以下步骤:

常见问题
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',},}));});