实时音视频 Web&H5 (Vue3）

本文档介绍如何在 Vue 3 业务项目中集成 TUIRoomKit，快速获得开箱即用的多人音视频会议能力。
﻿
﻿
前提条件
开通服务
请参考 开通服务 领取 TUIRoomKit 体验版或开通 TUIRoomKit 正式版，并在 应用管理 页面获取以下信息：
SDKAppID：应用标识，腾讯云基于 SDKAppID 完成计费统计。
SDKSecretKey：应用密钥，仅用于本地调试时生成 UserSig，不可写入生产代码。
环境准备
Node.js：≥ 18.19.1 (推荐使用官方 LTS 版本)。
浏览器：推荐使用最新版 Chrome，或其他支持 WebRTC API 的浏览器。
媒体设备：建议配备摄像头、麦克风和扬声器。缺少相应设备时仍可入会，但对应音视频能力不可用。
安装与初始化
1. 安装 SDK
npm
pnpm
yarn
# 在已有 Vue 3 项目根目录执行；若需新建项目，可先运行 npm create vite@5 roomkit-demo -- --template vue-ts
npm install @tencentcloud/roomkit-web-vue3 tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/universal-api 
# 在已有 Vue 3 项目根目录执行；若需新建项目，可先运行 pnpm create vite@5 roomkit-demo --template vue-ts
pnpm install @tencentcloud/roomkit-web-vue3 tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/universal-api
# 在已有 Vue 3 项目根目录执行；若需新建项目，可先运行 yarn create vite@5 roomkit-demo --template vue-ts
yarn add @tencentcloud/roomkit-web-vue3 tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/universal-api
2. 初始化实例
在业务页面的 <script setup> 中初始化会议实例：
<script setup>
import { RoomKit, genTestUserSig } from '@tencentcloud/roomkit-web-vue3';
const SDKAppID = 0;  // 替换为您在开通服务阶段获取的 SDKAppID
const SDKSecretKey = '';  // 替换为您在开通服务阶段获取的 SDKSecretKey
const userId = 'your_user_id';  // 业务侧用户唯一标识
﻿
const { userSig } = genTestUserSig({ sdkAppId: SDKAppID, secretKey: SDKSecretKey, userId });
const room = RoomKit.getInstance({ sdkAppId: SDKAppID, userId, userSig });
</script>
说明：
示例采用客户端生成 UserSig 的方式，仅可用于本地开发调试。正式环境请改为由业务服务端生成 UserSig，详见 正式运行阶段如何计算 UserSig。
发起会议
用户点击“发起会议”时，调用 createAndJoin 创建并进入会议，传入以下参数：
roomId： 业务生成的房间号，同一应用内不能重复，长度为 1～48 字节，仅支持英文字母（区分大小写）、数字、下划线 _ 和连字符 -。
password： 参会密码，可不传；设置后，其他用户调用 join 时，RoomKit 会自动弹出密码输入框，验证通过后即可入会。
<script setup>
const hostMeeting = async () => {
  // room 为“安装与初始化”中创建的实例
  await room.createAndJoin({
    roomId: 'meeting_001', // 替换为业务生成的唯一房间号
    password: '123456', // 参会密码
    // 方式一：页面指定区域显示
    container: { appendTo: '#meeting' }, 
    // 方式二：固定尺寸弹窗显示
    // container: { appendTo: 'body', width: '960px', height: '640px' }, 
  });
};
</script>
<template>
  <button @click="hostMeeting">发起会议</button>
  <!-- 仅方式一需要，用于显示会议界面 -->
  <div id="meeting" style="width: 1080px; height: 720px"></div>
</template>
加入会议
调用 join 并传入已预定或创建的房间号 roomId，即可加入会议。
<script setup>
const joinMeeting = async () => {
  // room 为“安装与初始化”中创建的实例
  await room.join({
    roomId: 'meeting_001',
    // 方式一：页面指定区域显示
    container: { appendTo: '#meeting' }, 
    // 方式二：固定尺寸弹窗显示
    // container: { appendTo: 'body', width: '960px', height: '640px' }, 
  });
}
</script>
<template>
  <button @click="joinMeeting">加入会议</button>
  <!-- 仅方式一需要，用于显示会议界面 -->
  <div id="meeting" style="width: 1080px; height: 720px"></div>
</template>
预定会议
客户端预定
调用 scheduleRoom 预定会议，通过 scheduleStartTime 指定开始时间、scheduleAttendees 指定参会人、password 设置参会密码。
import { useLoginState, useRoomState } from 'tuikit-atomicx-vue3/room';
const { login } = useLoginState();
const { scheduleRoom } = useRoomState();
const schedule = async () => {
  await login({
    sdkAppId: 0, // 控制台获取的 SDKAppID
    userId: 'your_user_id', // 业务侧用户唯一标识
    userSig: 'your_user_sig', // 由业务服务端签发并下发
  });
  const start = Math.floor(Date.now() / 1000) + 3600;
  await scheduleRoom({
    roomId: 'meeting_002', // 业务生成的唯一房间号，规则同“发起会议”
    options: {
      roomName: '产品需求评审', // 会议名称
      scheduleStartTime: start, // 秒级时间戳，示例为 1 小时后开始
      scheduleEndTime: start + 1800, // 秒级时间戳，示例为开会 30 分钟后结束
      scheduleAttendees: ['userA', 'userB'], // 参会人的 userId 列表
      password: '739251', // 参会密码；不设置密码时省略
    },
  });
}
服务端预定
如果您希望由后台业务系统而不是客户端来预定会议，可以使用我们提供的 REST API。
界面定制
TUIRoomKit 支持定制视频画面信息、主题、字体、语言和联系人列表，均通过 setUIConfig 配置。该方法在入会前和会议过程中均可调用，每次只更新传入的配置项，未传入的保持不变。
视频画面信息
TUIRoomKit 会在每路视频画面上叠加一层信息，默认展示参会者的头像、显示名、麦克风状态和主持人标识，屏幕共享画面则显示共享提示。如果默认的内容或样式不满足需求，可通过 participantViewUI 自行定义这层信息。
﻿
步骤1：编写视频画面信息组件。
// ParticipantOverlay.vue
<template>
  <div class="overlay">
    <div v-if="streamType === VideoStreamType.Screen" class="sharing">正在共享屏幕</div>
    <div v-else class="info">
      <span class="name">{{ participant.nameCard || participant.userName || participant.userId }}</span>
      <span v-if="participant.microphoneStatus === DeviceStatus.Off" class="muted">已静音</span>
    </div>
  </div>
</template>
<script setup lang="ts">
import { DeviceStatus, VideoStreamType } from 'tuikit-atomicx-vue3/room';
import type { RoomParticipant } from 'tuikit-atomicx-vue3/room';
defineProps<{
  participant: RoomParticipant;
  streamType: VideoStreamType;
}>();
</script>
步骤2：通过 setUIConfig 方法传入该组件。
import ParticipantOverlay from './ParticipantOverlay.vue';
﻿
// room 为 RoomKit.getInstance() 返回的会议实例
room.setUIConfig({ participantViewUI: ParticipantOverlay });
说明：
1. participantViewUI 传入的组件会同时用于摄像头画面和屏幕共享画面，如需对两者做不同展示，可在组件内通过 streamType 区分。
2. 视频流的采集、订阅、渲染，以及宫格、演讲者等画面布局仍由 TUIRoomKit 负责，不受 participantViewUI 影响。
主题与语言
TUIRoomKit 支持通过 setUIConfig 调整界面的主题、字体和语言。
// room 为 RoomKit.getInstance() 返回的会议实例
room.setUIConfig({
  theme: {
    themeStyle: 'light',
    primaryColor: '#07C160',
    backgroundColor: '#F2FAF5',
    textColor: '#122B1C',
  },
  fontFamily: "'Avenir Next', Avenir, 'Helvetica Neue', 'PingFang SC', sans-serif",
  language: 'en-US',
});
配置项
默认值
说明
theme
浅色主题、蓝色主色
themeStyle 可切换 'light'、'dark' 两套风格。也可通过 primaryColor、backgroundColor、textColor 自定义主色、背景色和文字色。
fontFamily
'PingFang SC', 'Microsoft YaHei', 'Noto Sans SC', sans-serif
会议界面的全局字体。
language
跟随浏览器语言
可指定为 'zh-CN' 或 'en-US'。
导入联系人
会中邀请他人加入会议时，默认显示当前用户的腾讯云 IM 好友。如需使用您的业务联系人，可参考以下代码配置 contactList。
// room 为 RoomKit.getInstance() 返回的会议实例
room.setUIConfig({
  contactList: () => [
    { userId: 'denny', userName: 'Denny' },
    { userId: 'tommy', userName: 'Tommy' },
    { userId: 'lucy', userName: 'Lucy' },
  ],
});
﻿
常见问题
创建房间的用户（房主）关闭网页或异常退出后，会议会立即结束吗？
不会。房主关闭浏览器或因网络异常离开页面时，会议不会立即解散，其他在房成员仍可继续会议。
为节省资源，建议在会议实际结束时，通过以下任一方式主动销毁房间：
界面操作：房主点击 TUIRoomKit 界面上的「解散房间」按钮；
客户端 API：调用 room.end() 方法；
服务端 API：通过 REST API 进行远程销毁。
注意：若未主动解散，系统会在会议结束时间后 6 小时，且房间内人数为 0 时自动回收资源。
多个设备能否使用同一个 userId 同时加入同一场会议？
不支持。TUIRoomKit 不允许同一 userId 在多个设备上同时进入同一房间。
互踢机制：若后到的设备使用相同 userId 尝试进房，先前已在房内的设备会被强制下线（踢出）。
解决方案：如需实现多端（如手机、PC）同时加入会议，请确保为每个设备分配唯一的 userId。
在本地开发时使用正常，但部署到线上环境后无法正常采集用户的摄像头或麦克风设备？
原因：浏览器出于安全与隐私考虑，仅允许在安全环境（https://、localhost、file:// 等）下采集摄像头、麦克风。HTTP 协议下浏览器会默认禁止访问媒体设备。
解决方案：若本地（localhost）测试正常但部署后采集失败，请检查页面是否使用 HTTPS 协议部署，并确保证书有效。
相关资源：更多关于 URL 域名及协议的限制详情，请参见 URL 域名及协议限制说明。
是否支持使用 iframe 集成?
支持。使用 iframe 集成 TUIRoomKit 时, 需要在 iframe 标签中配置 allow 属性以授予必要的浏览器权限（麦克风、摄像头、屏幕共享、全屏等），示例如下:
<!-- 开启麦克风、摄像头、屏幕分享、全屏权限 -->
<iframe src="https://your-domain.com/index.html" allow="microphone; camera; display-capture; display; fullscreen;"></iframe>
更多信息可参考 内嵌页面 （iframe）。
是否支持设置内网代理？
支持。更多内网代理信息请参考 内网代理（Web）。
是否可以直接修改 TUIRoomKit 的底层源码？
TUIRoomKit 已提供丰富的 UI 自定义能力，包括 主题及语言、界面微调、视频布局及挂件、水印配置 等，可满足大多数业务的个性化需求。
我们非常不推荐您进行源码导出。导出源码意味着您的项目将脱离 TUIRoomKit 的常规 npm 版本升级路径。您不仅需要自行承担后续极高的代码维护成本，也将无法直接通过更新版本来享受我们后续推出的新功能和底层音视频引擎的性能优化。
推荐方案：优先查阅 UI 自定义系列文档，使用标准自定义接口。
需求反馈：若现有接口无法满足业务诉求，欢迎 联系我们 提交场景需求，我们将评估并提供更合理的标准 API 支持。
若您已充分评估维护风险，且业务存在必须修改底层结构的深度定制需求，可按以下步骤导出源码：
源码导出步骤
1. 执行源码导出脚本，默认拷贝路径为 ./src/components/RoomKit。
  node ./node_modules/@tencentcloud/roomkit-web-vue3/scripts/eject.js
2. 根据脚本提示确认是否要将 TUIRoomKit 源码拷贝到 ./src/components/RoomKit 目录。如您需要自定义拷贝目录请输入 'y', 否则输入'n'。
﻿
3. 源码导出后，在您指定的项目路径中会新增 TUIRoomKit 源码。此时，您需要手动将 RoomKit 的引用从 npm 包地址更改为 TUIRoomKit 源码的相对路径地址。
- import { RoomKit } from '@tencentcloud/roomkit-web-vue3';
// 替换引用路径为 TUIRoomKit 源码的真实路径
+ import { RoomKit } from './components/RoomKit/index.ts';
4. 配置 ESLint 校验。
如果您导出 TUIRoomKit 源码后运行项目出现 ESLint 报错，您可以在 .eslintignore 文件中添加 RoomKit 文件夹忽略 ESLint 检测。
// 请替换为 TUIRoomKit 源码真实路径
src/components/RoomKit 
联系我们
如果您在接入或使用过程有任何疑问或者建议，欢迎 联系我们 提交反馈。
配置项	默认值	说明
`theme`	浅色主题、蓝色主色	`themeStyle` 可切换 `'light'`、`'dark'` 两套风格。也可通过 `primaryColor`、`backgroundColor`、`textColor` 自定义主色、背景色和文字色。
`fontFamily`	`'PingFang SC', 'Microsoft YaHei', 'Noto Sans SC', sans-serif`	会议界面的全局字体。
`language`	跟随浏览器语言	可指定为 `'zh-CN'` 或 `'en-US'`。
Web&H5 (Vue3）

本页目录：

前提条件

开通服务

环境准备

安装与初始化

发起会议

加入会议

预定会议

客户端预定

服务端预定

界面定制

视频画面信息

主题与语言

导入联系人

常见问题

创建房间的用户（房主）关闭网页或异常退出后，会议会立即结束吗？

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

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

是否支持使用 iframe 集成?

是否支持设置内网代理？

是否可以直接修改 TUIRoomKit 的底层源码？

联系我们
