快速接入

本指南帮助你快速完成腾讯云实时互动-教育版无 UI SDK 的接入，实现创建实例、进房和离房的完整流程。

环境要求

• Node.js >= 16
• 支持 ES Module 的现代浏览器（Chrome 85+ / Edge 86+ / Safari 15+ / Firefox 80+）
• 若需音视频功能，浏览器必须支持 WebRTC

安装

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

课堂生命周期概览

基本使用流程

Step 1：导入 SDK

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

Step 2：创建实例

const classroom = new TencentClassroom({
  language: 'zh-CN',            // UI 语言：zh-CN | zh-TW | en | ja | ko | vi | ar | id | es
  debug: true,                  // 开启调试日志
  board: {
    domId: 'board-container',   // 白板挂载容器 DOM ID
  },
  behavior: {
    autoLoadDefaultDocument: true,  // 进房后自动加载默认课件
  },
});

提示：new TencentClassroom() 后即可通过 TencentClassroom.instance 在任意位置访问实例。

Step 3：初始化引擎

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

Step 4：加入课堂

const joinResult = await classroom.joinClass({
  classId: 123456,           // 课堂 ID（必填）
  userId: 'user_001',        // 用户 ID（必填）
  token: 'biz-token-xxx',    // 业务 token（必填，由服务端签发）
});

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

Step 5：课堂互动（音视频 / 远端流）

// 开启本地摄像头（传入渲染容器 DOM）
await classroom.startCamera(document.getElementById('local-video')!);

// 开启麦克风
await classroom.startMicrophone();

// 绑定远端用户摄像头流到 DOM
const binding = classroom.bindRemoteView(
  'teacher_001',
  document.getElementById('remote-video')!,
  StreamType.Camera,
);

Step 6：离开课堂与销毁

// 解绑远端流
classroom.unbindRemoteView(binding);

// 主动离开课堂
await classroom.leaveClass();

// 完全销毁实例（释放所有资源）
await classroom.destroy();

完整最小示例

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

async function main() {
  // 1. 创建实例
  const classroom = new TencentClassroom({
    language: 'zh-CN',
    debug: true,
    board: { domId: 'board-container' },
  });

  // 2. 初始化
  const initResult = await classroom.init();
  if (!initResult.ok) return console.error(initResult.message);

  // 3. 监听关键事件（在进房前设置好）
  classroom.on(TEvent.KICK_OUT, ({ message }) => alert(message));

  // 4. 进房
  const joinResult = await classroom.joinClass({
    classId: 123456,
    userId: 'user_001',
    token: 'your-token',
  });
  if (!joinResult.ok) return console.error(joinResult.message);

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

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

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

main();

进阶：进房阶段详解（JoinProgress）

进房时 SDK 内部按顺序执行 10 个阶段，可通过 joinProgress$ 驱动 Loading UI：

classroom.state.joinProgress$.subscribe((progress) => {
  updateLoadingUI(progress);
});

阶段	值	说明
Idle	idle	初始状态
FetchingSchoolInfo	fetchingSchoolInfo	获取学校信息（含套餐、水印配置）
FetchingClassInfo	fetchingClassInfo	获取课堂详情（类型、配置、成员）
JoiningMember	joiningMember	注册成员（member/join）
LoginIM	loginIM	登录 IM 消息通道
JoinIMGroup	joinIMGroup	加入 IM 群组（信令+聊天）
JoinTRTC	joinTRTC	加入 TRTC 房间（音视频通道）
InitBoard	initBoard	初始化白板
InitPermission	initPermission	拉取权限列表
FetchingHistory	fetchingHistory	拉取历史消息
Completed	completed	进房完成

进阶：运行环境检测

checkEnvironment() 一次性校验课堂运行所需的全部核心能力。建议在 init() 之后、joinClass() 之前调用。

const env = await classroom.checkEnvironment();
if (!env.ok) {
  alert(env.message);
  return;
}
if (!env.data.isSupported) {
  // 根据失败原因给出更精确的提示
  if (env.data.reasons?.includes('InsecureContext')) {
    alert('请使用 HTTPS 访问本页面');
  } else if (env.data.reasons?.includes('WebRTCUnsupported')) {
    alert('当前浏览器不支持音视频，请使用 Chrome 85+ 或 Edge 86+');
  } else if (env.data.reasons?.includes('NoMediaDevices')) {
    alert('当前环境缺少 mediaDevices 能力，无法采集音视频');
  } else {
    alert('当前环境不支持课堂运行');
  }
  return;
}

// env.data.checks 给出分项结果，便于排障
// { browser: true, secureContext: true, mediaDevices: true, webrtc: true }

进阶：状态订阅与事件监听

响应式状态

// 订阅课堂状态
classroom.state.classStatus$.subscribe(status => {
  console.log('课堂状态:', status); // 'notStarted' | 'started' | 'ended' | 'expired'
});

// 监听被踢出
classroom.on(TEvent.KICK_OUT, ({ reason, message }) => {
  alert(message);
});

// 监听成员加入
classroom.on(TEvent.MEMBER_JOIN, (member) => {
  console.log('成员加入:', member.userId, member.nickName);
});

事件系统高级用法

// on 返回取消函数
const off = classroom.on(TEvent.CLASS_START, () => console.log('课堂开始'));
off(); // 取消监听

// once — 一次性监听，触发后自动取消
classroom.once(TEvent.JOIN_CLASS, (classInfo) => {
  console.log('进房成功，课堂名：', classInfo.className);
});

// waitFor — Promise 风格，等待事件触发（只等一次）
const classInfo = await classroom.waitFor(TEvent.JOIN_CLASS);

// waitFor 带超时
try {
  await classroom.waitFor(TEvent.BOARD_READY, 10_000);
} catch {
  console.error('白板就绪等待超时');
}

进阶：各角色使用流程

老师（Teacher）

学生（Student）

助教（Assistant）

• 与老师拥有相同的管理权限
• 进房后默认在台上，可直接开启音视频
• 不建议默认调用 startCamera() + startMicrophone() 开启音视频
• 可执行所有成员管理操作（踢人、邀请上台等）

巡课（Supervisor）

• 只读模式：可观看音视频、查看白板、浏览花名册
• 不可发送消息、不可操作成员
• 不出现在成员列表中（对其他人不可见）

进阶：平台检测

通过 classroom.platform 获取运行环境信息：

classroom.platform.isMobile     // 移动端（Native + Web）
classroom.platform.isDesktop    // 桌面端（Electron + Web 桌面）
classroom.platform.isElectron   // Electron 桌面应用
classroom.platform.isAndroid    // Android
classroom.platform.isIOS        // iOS
classroom.platform.isPad        // 平板（iPad / Android Tablet）
classroom.platform.isWeb        // 纯 Web 浏览器
classroom.platform.isNative     // 有 Bridge 注入（Electron / Android / iOS）
classroom.platform.supportTouch // 支持触摸屏

// 高层分类
classroom.platform.platform     // 'web' | 'electron' | 'android' | 'ios' | 'mobile-web' | 'server'

// 示例：根据平台决策
if (classroom.platform.isMobile) {
  // 使用移动端布局
} else {
  // 使用桌面端布局
}

下一步

• 音视频指南 — 设备管理、远端流渲染、连麦上台
• IM 聊天指南 — 消息收发与管理
• 白板指南 — 白板与课件操作
• 国际化 — 多语言与词条覆盖
• 错误处理 — TResult 模式详解
• API 参考 — 完整 API 文档