文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>实时音视频>视频会议 SDK>含 UI 集成>多人会议>快速接入>Web&H5 (Vue3）

Web&H5 (Vue3）

最近更新时间：2026-03-30 17:40:41

我的收藏

本页目录：

TUIRoomKit 是腾讯云推出的音视频房间 UI 应用。本次升级引入了全新的原子化组件接入方案，开发者可以灵活组合这些原子化组件，以构建个性化的音视频房间界面。
推荐使用更高效的 AI 集成助手
我们为您提供了全新的 AI 集成方式，只需要描述您的需求，即可自动生成集成代码，大幅提升开发效率。
本文档介绍如何将 TUIRoomKit 集成到现有的 Vue3 项目中，同时介绍如何对 TUIRoomKit 的样式、布局及功能进行自定义修改。
桌面端多人会议

H5 多人会议


前提条件

开通服务

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

环境准备

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

源码接入

步骤1：安装项目依赖

在您的业务项目中安装以下依赖。
npm
pnpm
yarn
npm install @tencentcloud/roomkit-web-vue3@5 tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/universal-api 
pnpm install @tencentcloud/roomkit-web-vue3@5 tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/universal-api
yarn add @tencentcloud/roomkit-web-vue3@5 tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/universal-api

步骤2：引用 TUIRoomKit 组件

<template>
  <UIKitProvider theme="light" language="zh-CN">
    <ConferenceMainView v-if="isPC"></ConferenceMainView>
    <ConferenceMainViewH5 v-else></ConferenceMainViewH5>
  </UIKitProvider>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { UIKitProvider } from '@tencentcloud/uikit-base-component-vue3';
import { ConferenceMainView, ConferenceMainViewH5 } from '@tencentcloud/roomkit-web-vue3';
import { getPlatform } from '@tencentcloud/universal-api';

const isPC = ref(getPlatform() === 'pc');
</script>


步骤3：登录

请在业务登录阶段单独调用 login，确保后续进房动作在登录成功后触发。
注意：
在配置代码中，请务必填入生成的 UserSig。在正式的生产环境中，建议在您的服务端生成 UserSig，在需要 UserSig 时由您的客户端向业务服务器发起请求获取动态 UserSig 来进行鉴权。详见 正式运行阶段如何计算 UserSig。
import { useLoginState } from 'tuikit-atomicx-vue3/room';

const { login, setSelfInfo } = useLoginState();
const SDKAppID = 0;    // 注意：请替换为实时音视频控制台获取的 SDKAppID 信息
const userId = '填入您真实的 userId';    // 注意：请替换为真实的 userId
const userName = '填入您真实的 userName';  // 注意：请替换为真实的 userName
const userSig = '填入您真实的 userSig';    // 注意：生成临时 userSig 请参考 https://cloud.tencent.com/document/product/647/17275#console
onMounted(async () => {
  try {
    await login({
      userId,
      userSig,
      sdkAppId: SDKAppID,
    });
    await setSelfInfo({
      userName,
      avatarUrl: '',
    });
  } catch (error: any) {
    console.error('Login failed:', error);
  }
});

接入问题：登录与进房分属不同路由页面如何监听登录成功的状态？

当登录页面与进房页面是两个独立路由时，进房页面加载时登录可能尚未完成。推荐通过 watch 监听 loginUserInfo.value?.userId，该字段非空即视为登录成功。
import { watch } from 'vue';
import { useLoginState } from 'tuikit-atomicx-vue3/room';
import { conference } from '@tencentcloud/roomkit-web-vue3';

const { loginUserInfo } = useLoginState();

watch(() => loginUserInfo.value?.userId, async (userId) => {
  if (userId) {
    await conference.start({ roomId: '123456' });
  }
}, { immediate: true });

步骤4：创建会议

创建会议是接入中最关键的环节，请根据业务模型选择合适的方式。
业务场景
推荐方式
快速会议、临时沟通、ChatKit 融合场景
方案一：客户端 SDK API 创建
预定会议、政务/医疗/大型企业会议管理后台、通过会议列表进房
方案二：服务端 REST API 创建

方案一：通过客户端 SDK API 创建会议

登录成功后，由发起人调用 conference.createAndJoinRoom 创建并进入房间：
import { conference } from '@tencentcloud/roomkit-web-vue3';

await conference.createAndJoinRoom({
  roomId: '123456',
  options: {
    roomName: '我的会议',
  },
});
注意：
conference.createAndJoinRoom 具有"不存在则创建，已存在则加入"的语义：若指定 roomId 的房间尚未创建，调用者将以房主身份创建并进入；若房间已存在，则以参会人身份直接加入。
若仅希望参会人加入已存在的房间，请使用 conference.joinRoom，语义更明确。

方案二：通过服务端 REST API 创建会议

由业务服务端调用腾讯云 服务端 REST API 创建房间。
POST /v4/room_engine_http_srv/create_room
{
  "roomId": "your-room-id",
  "roomName": "会议名称",
  "startTime": 1710000000,
  "endTime": 1710003600,
  "invitees": ["userId1", "userId2"]
}
注意：
服务端统一创建房间，此时所有客户端成员均调用 conference.joinRoom 加入即可。
服务端创建完成后，客户端参会人可展示会议列表并入会。关于会议列表实现可参考 预定房间 > 获取预定列表。

步骤5：加入会议

根据业务侧是否能确定房间已存在，选择对应的加入方式。
业务场景
推荐方式
参会人收到邀请（含房间号/链接），房间确定已存在
方案一：直接 joinRoom
会议双方都可能先进入，无法预先确定谁创建房间（在线问诊、视频面试、1v1 客服等双向发起场景）
方案二：直接 createAndJoinRoom

方案一：直接 joinRoom

适用于：参会人收到邀请（房间号/链接/通知），房间由发起人或服务端预先创建，可以确定房间已存在。
import { conference } from '@tencentcloud/roomkit-web-vue3';

await conference.joinRoom({
  roomId: '123456',
});

方案二：直接 createAndJoinRoom（双向发起场景）

适用于：双方都可能先进入（如在线问诊、视频面试、1v1 客服），无法预先确定房间是否已创建。
createAndJoinRoom 内部已封装了"不存在则创建，已存在则加入"的逻辑，双方统一调用同一个方法即可，无需提前查询房间状态：
import { conference } from '@tencentcloud/roomkit-web-vue3';

// SDK 内部自动判断：房间不存在则创建（调用方成为房主），房间已存在则直接加入
await conference.createAndJoinRoom({
  roomId: '123456',
  options: {
    roomName: '我的会议',
  },
});

启动项目

npm
pnpm
yarn
npm run dev
pnpm run dev
yarn run dev
启动成功后，请在浏览器中打开调试地址（通常为 http://localhost:5173）访问应用。您将看到如下所示的会议界面：


UI 快速自定义

在完成基础集成后，您可以根据业务需求进一步定制 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 预定会议用户选择列表和会中呼叫用户选择列表默认展示用户关系链列表，批量导入用户关系链请参考以下步骤：
1. 使用 账号管理 > 导入多个账号 REST API 接口批量导入用户账号。
2. 使用 好友管理 > 导入好友 REST API 接口批量导入用户关系链。


TUIRoomKit 界面定制

源码导出

Vue3
1. 执行源码导出脚本，默认拷贝路径为 ./src/components/RoomKit
  node ./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, ConferenceMainViewH5, 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.vue
import { 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 界面上的「解散房间」按钮；
客户端 API：调用 conference.dismiss() 方法；
服务端 API：通过 REST API 进行远程销毁。
注意：若未主动解散，系统会在会议结束时间后 6 小时，且房间内人数为 0 时自动回收资源。

多个设备能否使用同一个 userId 同时加入同一场会议？

不支持。 TUIRoomKit 不允许同一 userId 在多个设备上同时进入同一房间。
互踢机制：若后到的设备使用相同 userId 尝试进房，先前已在房内的设备会被强制下线（踢出）。
解决方案：如需实现多端（如手机、PC）同时加入会议，请确保为每个设备分配唯一的 userId。

在本地开发时使用正常，但部署到线上环境后无法正常采集用户的摄像头或麦克风设备？

原因分析：浏览器出于安全和隐私保护的考虑，对音视频设备（麦克风、摄像头）的采集有着严格限制。只有在安全环境下，采集操作才会被允许。安全环境协议包括：https://、localhost、file:// 等。HTTP 协议被视为不安全，浏览器会默认禁止访问媒体设备。
解决方案：若您在本地（localhost）测试一切正常，但部署后出现采集失败，请立即检查您的网页是否部署在 HTTP 协议上。必须使用 HTTPS 协议部署您的网页，并确保具备有效的安全证书。
相关资源：更多关于 URL 域名及协议的限制详情，请参见 URL 域名及协议限制说明。

是否支持使用 iframe 集成?

支持。使用 iframe 集成 TUIRoomKit 时, 需要在 iframe 标签中配置 allow 属性以授予必要的浏览器权限（麦克风、摄像头、屏幕共享、全屏等），示例如下: 
// 开启麦克风、摄像头、屏幕分享、全屏权限
<iframe src="https://your-domain.com/index.html" allow="microphone; camera; display-capture; display; fullscreen;">
更多信息可参考 内嵌页面 （iframe)。

是否支持设置内网代理？

支持。请参考如下指引设置内网代理参数。更多内网代理信息请参考 应对防火墙受限。
// 请在进房前设置内网代理参数
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',
    },
  }));
});

联系我们

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