文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>实时互动-教育版>开发指南>Web 无 UI SDK 接入

Web 无 UI SDK 接入

最近更新时间：2026-05-27 09:48:00

我的收藏

本页目录：

概述

本文档面向希望构建定制化在线互动课堂产品的前端开发者，介绍腾讯云实时互动-教育版 无 UI SDK 的接入方式。
SDK 封装了音视频通信、课堂管理、成员管理、课件白板等底层能力，并以响应式状态驱动数据与时间、灵活简便的方法调用提供能力。您只需关注 UI 层的实现，即可快速完成在线互动课堂的集成开发。
您也可以直接参考 完整版文档 了解更多高级用法。
AI 辅助开发：
为简化并加速接入，我们还提供 AI Skill 辅助，您可以使用主流 AI 编码工具（Cursor / Claude / Copilot 等），通过 Vibe Coding 方式最快速度完成项目开发。AI 辅助开发文档
npx skills add InteractiveClassroom/skills --skill tcic-sdk-helper

前提条件

已完成 接入准备，了解如何获取 schoolId、classId、userId、token。
Node.js >= 16。
支持 ES Module 的现代浏览器（Chrome 85+ / Edge 86+ / Safari 15+ / Firefox 80+）。
目前暂仅支持 Web 浏览器项目, Electron 及 移动端 Mobile Native 接入将于后期提供扩展。

安装

npm install @tencent-classroom/sdk
# 或
pnpm add @tencent-classroom/sdk

课堂生命周期

SDK 的核心调用流程如下：


基本使用流程

步骤1：创建实例

import { TencentClassroom, TEvent, StreamType } from '@tencent-classroom/sdk';

const classroom = new TencentClassroom({
  language: 'zh-CN',
  board: {
    domId: 'board-container', // 白板挂载容器（不需要白板可去掉）
  },
});
创建后可通过 TencentClassroom.instance 在任意位置访问实例。

步骤2：初始化

const initResult = await classroom.init();
if (!initResult.ok) {
  console.error('初始化失败:', initResult.message);
  return;
}

步骤3：注册事件监听

说明：
事件必须在 joinClass() 之前注册，否则可能丢失进房过程中触发的事件。
classroom.on(TEvent.KICK_OUT, ({ message }) => {
  alert(message); // 被踢出课堂
});

classroom.on(TEvent.CLASS_END, () => {
  // 课堂结束
});
完整事件列表：全局事件 API

步骤4：加入课堂

调用 joinClass() 加入完成加入课堂流程。
// classId / userId / token 通过接入准备文档获取
const joinResult = await classroom.joinClass({
  classId: 123456789,
  userId: 'user_001',
  token: 'your-token',
});

if (!joinResult.ok) {
  console.error('进房失败:', joinResult.message);
  return;
}

步骤5：音视频推流

调用 startCamera 及 startMicrophone 完成开启本地摄像头及麦克风。
// 开启摄像头（传入本地预览 DOM）
await classroom.startCamera(document.getElementById('local-video')!);

// 开启麦克风
await classroom.startMicrophone();
注意：
学生角色必须上台后（stageStatus$ = 'active'）才能推流。
详细音视频用法：音视频指南

步骤6：远端流渲染

监听台上成员变化，并动态为台上成员绑定 DOM 完成展示画面和声音。完整流程细节可参考详细说明。
const bindings = new Map();

classroom.state.stageList$.subscribe((stageMembers) => {
  const currentIds = new Set(stageMembers.map(m => m.userId));

  // 解绑已下台成员
  for (const [userId, binding] of bindings) {
    if (!currentIds.has(userId)) {
      classroom.unbindRemoteView(binding);
      bindings.delete(userId);
    }
  }

  // 绑定新上台成员
  for (const member of stageMembers) {
    if (member.userId === myUserId) continue; // 跳过自己
    if (bindings.has(member.userId)) continue;

    const dom = document.getElementById(`video-${member.userId}`);
    const binding = classroom.bindRemoteView(member.userId, dom, StreamType.Camera);
    bindings.set(member.userId, binding);
  }
});

步骤7：离开课堂

// 解绑所有远端流
for (const [, binding] of bindings) {
  classroom.unbindRemoteView(binding);
}

// 离房 + 销毁（两者都必须调用）
await classroom.leaveClass();
await classroom.destroy();

各角色接入要点

老师（Teacher）

步骤
操作
加入课堂
joinClass({ role: 'teacher' })
开启音视频
startCamera() + startMicrophone()（自动上台）
开始上课
startClass()
课中管理
muteAudioAll() / setSilenceMode() / memberAction()
结束上课
endClass()
退出
leaveClass() → destroy()

学生（Student）

步骤
操作
加入课堂
joinClass({ role: 'student' })
等待开课
订阅 classStatus$
观看远端流
bindRemoteView(teacherId, DOM, StreamType.Camera)
举手连麦
handUp() → 等待老师同意
上台推流
stageStatus$ = 'active' 后调用 startCamera()
退出
leaveClass() → destroy()

助教（Assistant）

与老师相同管理权限，默认在台上。
可直接开启音视频，可执行成员管理操作。

巡课（Supervisor）

只读模式：可观看音视频、查看白板、浏览花名册。
不可发消息、不可操作成员、不出现在成员列表中。

互动消息聊天

// 发送文本消息
await classroom.sendTextMessage('Hello');

// 订阅消息列表
classroom.state.messageList$.subscribe((messages) => {
  renderChatList(messages);
});
更多消息类型（图片/文件/自定义消息/撤回/私聊）及更多用法：互动消息聊天指南。

互动白板及课件

在构造实例时配置白板容器，进房后自动初始化：
const classroom = new TencentClassroom({
  board: {
    domId: 'board-container',
    ratio: '16:9',
  },
});
白板工具操作、翻页、课件管理等：白板及课件指南。

国际化

SDK 内置 9 种语言支持：
const classroom = new TencentClassroom({
  language: 'en', // zh-CN | zh-TW | en | ja | ko | vi | ar | id | es
});
详细用法（运行时切换/词条覆盖/新增语言）：国际化指南。

完整示例

import { TencentClassroom, TEvent, StreamType } from '@tencent-classroom/sdk';

async function main() {
  const classroom = new TencentClassroom({
    language: 'zh-CN',
    board: { domId: 'board-container' },
  });

  const initResult = await classroom.init();
  if (!initResult.ok) return console.error(initResult.message);

  // 注册事件（进房前）
  classroom.on(TEvent.KICK_OUT, ({ message }) => alert(message));

  // 进房（参数通过接入准备文档获取）
  const joinResult = await classroom.joinClass({
    classId: 123456789,
    userId: 'user_001',
    token: 'your-token',
  });
  if (!joinResult.ok) return console.error(joinResult.message);

  // 开启音视频
  await classroom.startCamera(document.getElementById('local-video')!);
  await classroom.startMicrophone();

  // 渲染远端流
  const binding = classroom.bindRemoteView(
    'teacher_001',
    document.getElementById('remote-video')!,
    StreamType.Camera,
  );

  // 页面卸载时清理
  window.addEventListener('beforeunload', async () => {
    classroom.unbindRemoteView(binding);
    await classroom.leaveClass();
    await classroom.destroy();
  });
}

main();

打包部署

开发完成后，您可以将项目编译打包并部署到自己的 Web 服务器上运行。
更多细节及高级用法，请参考完整版文档。

开发者支持与反馈

在开发过程中，如果您遇到任何技术难题或 API 使用疑问，欢迎通过 联系我们 加入官方开发者微信群。我们的技术与产品专家将在线为您答疑解惑。
中国站