本文档介绍如何在 Vue 3 业务项目中集成 TUIRoomKit 在线课堂场景,快速获得开箱即用的 1v1 在线课堂能力,包括老师开课、学生进入课堂、安排课堂、白板与屏幕分享等。

前提条件
开通服务
SDKAppID:应用标识,腾讯云基于
SDKAppID 完成计费统计。SDKSecretKey:应用密钥,仅用于本地调试时生成 UserSig,不可写入生产代码。
环境准备
Node.js:≥ 18.19.1 (推荐使用官方 LTS 版本)。
浏览器:推荐使用最新版 Chrome,或其他支持 WebRTC API 的浏览器。
媒体设备:建议配备摄像头、麦克风和扬声器。缺少相应设备时仍可进入课堂,但对应音视频能力不可用。
安装与初始化
安装 SDK
# 在已有 Vue 3 项目根目录执行;若需新建项目,可先运行 npm create vite@5 roomkit-demo -- --template vue-tsnpm 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-tspnpm 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-tsyarn add @tencentcloud/roomkit-web-vue3 tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/universal-api
初始化实例
在业务页面的
<script setup> 中初始化课堂实例:<script setup>import { RoomKit, genTestUserSig } from '@tencentcloud/roomkit-web-vue3';const SDKAppID = 0; // 替换为您在开通服务阶段获取的 SDKAppIDconst SDKSecretKey = ''; // 替换为您在开通服务阶段获取的 SDKSecretKeyconst userId = 'teacherA'; // 业务侧用户唯一标识const { userSig } = genTestUserSig({ sdkAppId: SDKAppID, secretKey: SDKSecretKey, userId });const room = RoomKit.getInstance({ sdkAppId: SDKAppID, userId, userSig });</script>
说明:
配置白板 PDF 与 PPT 解析插件资源
在线课堂的白板支持上传 PDF 与 PPT 课件,课件解析依赖 TRTC SDK 的 assets 资源,需要您自行部署。未部署时仅无法上传 PDF 与 PPT,白板的其他基础能力不受影响。如需使用该功能,请在调用
RoomKit.getInstance() 创建实例前完成以下配置:将
node_modules/trtc-sdk-v5/assets 目录下的资源文件发布至 CDN 或静态资源服务器中,并确保文件处于同一个公共路径下。调用以下接口,将上述公共路径传入 TUIRoomKit:
import { callExperimentalAPI } from 'tuikit-atomicx-vue3/room';callExperimentalAPI({api: 'setRtcAssetsPath',params: { assetsPath: 'XXXXX/assets/' }, // assets 资源所在的公共路径});
开始上课
老师点击开始上课时,调用
createAndJoin 创建并进入课堂。创建课堂的用户即为老师(房主),拥有课堂内的管理权限。传入以下参数:roomId: 业务生成的课堂号,同一应用内不能重复,长度为 1~48 字节,仅支持英文字母(区分大小写)、数字、下划线 _ 和连字符 -。scene: 场景类型,在线课堂场景固定传 RoomScene.Education,RoomKit 将展示课堂界面。roomName: 课堂名称,可不传。container: 课堂界面的显示位置。appendTo 传入页面元素或元素选择器时,课堂界面挂载到该元素内;传入 body 并指定 width、height 时,以固定尺寸弹窗显示。<script setup>import { RoomScene } from '@tencentcloud/roomkit-web-vue3';const startClass = async () => {// room 为“安装与初始化”中创建的实例await room.createAndJoin({roomId: 'class_001', // 替换为业务生成的唯一课堂号roomName: 'Jason的课堂', // 课堂名称,可不传scene: RoomScene.Education, // 在线课堂场景固定传 RoomScene.Education// 方式一:页面指定区域显示container: { appendTo: '#classroom' },// 方式二:固定尺寸弹窗显示// container: { appendTo: 'body', width: '1280px', height: '720px' },});};</script><template><button @click="startClass">开始上课</button><!-- 仅方式一需要,用于显示课堂界面 --><div id="classroom" style="width: 1280px; height: 720px"></div></template>
进入课堂
学生调用
join 并传入老师已创建或安排的课堂号 roomId,同时传入 scene: RoomScene.Education,即可进入课堂。<script setup>import { RoomScene } from '@tencentcloud/roomkit-web-vue3';const joinClass = async () => {// room 为“安装与初始化”中创建的实例await room.join({roomId: 'class_001', // 老师创建或安排的课堂号scene: RoomScene.Education,// 方式一:页面指定区域显示container: { appendTo: '#classroom' },// 方式二:固定尺寸弹窗显示// container: { appendTo: 'body', width: '1280px', height: '720px' },});};</script><template><button @click="joinClass">进入课堂</button><!-- 仅方式一需要,用于显示课堂界面 --><div id="classroom" style="width: 1280px; height: 720px"></div></template>
安排课堂
客户端排课
老师调用
scheduleRoom 安排课堂,通过 scheduleStartTime、scheduleEndTime 指定上课时间,通过 scheduleAttendees 指定上课学生。1v1 课堂只能指定一名学生。排课成功后,学生可在课程列表中看到该课堂,到时间后进入课堂。import { useLoginState, useRoomState } from 'tuikit-atomicx-vue3/room';const { login } = useLoginState();const { scheduleRoom } = useRoomState();const scheduleClass = async () => {await login({sdkAppId: 0, // 控制台获取的 SDKAppIDuserId: 'teacherA', // 老师的用户 IDuserSig: 'your_user_sig', // 由业务服务端签发并下发});const start = Math.floor(Date.now() / 1000) + 3600;await scheduleRoom({roomId: 'class_002', // 业务生成的唯一课堂号,规则同“开始上课”options: {roomName: '高二数学 · 椭圆的标准方程', // 课堂名称scheduleStartTime: start, // 秒级时间戳,示例为 1 小时后开始scheduleEndTime: start + 2700, // 秒级时间戳,示例为上课 45 分钟后结束scheduleAttendees: ['studentB'], // 上课学生的 userId,1v1 课堂只能指定一名学生},});};
服务端排课
常见问题
老师关闭网页或异常退出后,课堂会立即结束吗?
不会。老师关闭浏览器或因网络异常离开页面时,课堂不会立即解散,学生仍可留在课堂中,老师可重新进入。
为节省资源,建议在课程实际结束时,通过以下任一方式主动结束课堂:
界面操作:老师点击离开课堂 > 下课;
客户端 API:调用
room.end() 方法;服务端 API:通过 REST API 进行远程销毁。
注意:若未主动结束,系统会在课堂结束时间后 6 小时,且课堂内人数为 0 时自动回收资源。
多个设备能否使用同一个 userId 同时进入同一节课?
不支持。同一 userId 同一时间只能在一台设备上登录。
互踢机制:同一 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>
是否支持设置内网代理?
是否可以直接修改 TUIRoomKit 的底层源码?
我们非常不推荐您进行源码导出。导出源码意味着您的项目将脱离 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