Web (Atomicx 版本)

最近更新时间:2025-12-12 18:00:12

我的收藏
TUIRoomKit 是腾讯云推出的音视频会议 UI 应用。本次升级引入了全新的 Atomicx 组件接入方案,开发者可以灵活组合这些原子化组件,以构建个性化的会议界面。
本文档将帮助您集成 TUIRoomKit (Atomicx 版本) 到现有的 Vue 3 项目中,同时介绍如何对 TUIRoomKit 的样式、布局及功能进行自定义修改。
说明:
TUIRoomKit (Atomicx 版本) 目前仅支持 PC 端 Vue3 项目,如果您的业务需要支持 Vue2.x 框架或 H5 平台,请参考 旧版本 TUIRoomKit 快速接入



前提条件

开通服务

请参考 开通服务 领取 TUIRoomKit 体验版,并在 应用管理 页面获取以下信息:
SDKAppID: 应用标识,腾讯云基于 SDKAppID 完成计费统计。
SDKSecretKey: 应用密钥,用于初始化配置文件的密钥信息。

环境准备

Node.js: ≥ 18.19.1 (推荐使用官方 LTS 版本)。
Vue: ≥ 3.4.21。
现代浏览器:支持 WebRTC APIs 的现代浏览器。
设备:摄像头、麦克风、扬声器。

源码接入

步骤1:安装项目依赖

在您的业务项目中安装以下依赖。
npm
pnpm
yarn
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
pnpm
yarn
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=1
cd 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 配置文件,并将您在腾讯云控制台获取的 SDKAppIDSDKSecretKey 填入对应的变量中。

警告:
本文的 Demo 示例中通过在客户端代码中配置 SDKSecretKey 进行鉴权,但 SDKSecretKey 很容易被反编译逆向破解,一旦密钥泄露,攻击者就可以盗用您的腾讯云流量,因此该方法仅适合本地跑通 Demo 和功能调试。
在正式的生产环境中,建议在您的服务端生成 UserSig,在需要 UserSig 时由您的 App 向业务服务器发起请求获取动态 UserSig 来进行鉴权。详见 正式运行阶段如何计算 UserSig?

启动开发服务器

npm
pnpm
yarn
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 预定会议用户选择列表和会中呼叫用户选择列表默认展示用户关系链列表,批量导入用户关系链请参考以下步骤:
步骤1:使用 账号管理 > 导入多个账号 REST API 接口批量导入用户账号;
步骤2:使用 好友管理 > 导入好友 REST API 接口批量导入用户关系链;


常见问题

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',
},
}));
});

联系我们

如果您在接入或使用过程有任何疑问或者建议,欢迎 联系我们 提交反馈。