生命周期 API

SDK 实例创建、初始化、进退房、事件订阅等核心生命周期方法。

典型流程

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

const classroom = new TencentClassroom({ language: 'zh-CN', debug: true });
await classroom.init();
await classroom.joinClass({ classId: 123, userId: 'u1', token: 'xxx' });

// ... 业务操作 ...

await classroom.leaveClass();
await classroom.destroy();

API 参考

Constructor

创建 SDK 实例。

构造后实例自动注册为静态单例 TencentClassroom.instance； 如果已有实例，新实例会覆盖旧的（与老项目 TMain.instance 行为一致）。

构造 ≠ 初始化：构造仅注册内置模块，不做网络或 SDK 初始化。 必须随后调用 init() 才能使用其他 API。

参数	类型	说明
config?	ClassroomConfig = {}	SDK 配置项（全部可选）

返回值: TencentClassroom

示例:

const classroom = new TencentClassroom({
  language: 'zh-CN',         // 界面语言 / UI language
  debug: true,               // 开启调试日志 / Enable debug logging
  board: { domId: 'board' }, // 白板容器 / Whiteboard container
  behavior: {
    autoLoadDefaultDocument: true, // 进房后自动加载默认课件
  },
});

---

state

只读响应式状态。

所有字段均以 $ 结尾（BehaviorSubject 语义：订阅时立即推送当前值）。 (BehaviorSubject semantics: subscribers receive the current value immediately on subscribe).

示例:

classroom.state.classStatus$.subscribe(s => updateUI(s));
const currentStatus = classroom.state.classStatus$.get();

---

instance

获取当前 SDK 实例（静态单例）。

在 new TencentClassroom() 之后的任意位置都可通过此属性访问， 无需将实例跨层传递。

若尚未调用 new TencentClassroom() 则抛出错误。

---

checkEnvironment()

检测当前运行环境是否满足课堂正常运行的最低要求。

综合检测以下关键能力（任一项不满足都会导致 isSupported=false）：

1. 浏览器环境 / Browser environment — 排除 SSR / Node 等场景
2. 安全上下文 / Secure context — HTTPS 或 localhost（getUserMedia 必需）
3. mediaDevices — navigator.mediaDevices.getUserMedia 是否可用
4. WebRTC — TRTC.isSupported()（或自定义 RTC 适配器的等价实现）

建议在 init() 之后、joinClass() 之前调用，根据结果决定是否继续进房或在 UI 提示用户。

与设备权限/可用性检查的边界：本方法只验证"环境/能力"，不触发摄像头/麦克风授权弹窗。 设备列表与权限请使用 getCameraList() / getMicrophoneList()。

返回值: Promise<TResult<EnvironmentCheckResult>>

示例:

const env = await classroom.checkEnvironment();
if (!env.ok) {
  toast.error(env.message);
  return;
}
if (!env.data.isSupported) {
  if (env.data.reasons?.includes('InsecureContext')) {
    toast.error('请使用 HTTPS 访问本页面');
  } else if (env.data.reasons?.includes('WebRTCUnsupported')) {
    toast.error('当前浏览器不支持音视频，请使用 Chrome 85+ 或 Edge 86+');
  } else {
    toast.error('当前环境不支持课堂运行');
  }
  return;
}
await classroom.joinClass({ classId, userId, token });

---

destroy()

销毁引擎实例，释放所有资源（TRTC / IM / Logger 等）。

调用后静态单例 TencentClassroom.instance 会被清除。

destroy() 会自动触发 leaveClass()，无需手动先离房。

返回值: Promise<TResult<void>>

---

init()

初始化引擎（必须在 joinClass 前调用）。

内部流程：启动 Logger Worker → 按依赖拓扑顺序初始化所有内置模块 → 应用 behavior 配置。

返回值: Promise<TResult<void>>

示例:

const result = await classroom.init();
if (!result.ok) {
  console.error('[init failed]', result.detail);
  showToast(result.message);
  return;
}

---

joinClass()

加入课堂（完整进房流程：学校信息 → 课堂信息 → IM → TRTC → 白板 → 权限 → 历史消息）。

进房进度通过 state.joinProgress$ Signal 实时推送， 也可监听 TEvent.JOIN_PROGRESS_CHANGED 事件。

参数	类型	说明
params	JoinParams	进房参数（classId / userId / token 必填）

返回值: Promise<TResult<void>>

示例:

const result = await classroom.joinClass({
  classId: 123456,
  userId: 'teacher_001',
  token: 'biz-token-from-server',
  role: 'teacher',           // 可选，SDK 会根据课堂配置自动推断
});
if (!result.ok) {
  showToast(result.message);
  return;
}

---

leaveClass()

主动离开课堂（退出 TRTC / IM / 白板，停止心跳，状态重置）。

返回值: Promise<TResult<void>>

示例:

await classroom.leaveClass();
await classroom.destroy(); // 通常在 leaveClass 之后调用 destroy

---

off()

取消事件监听。

参数	类型	说明
event	E	事件名
listener?	ClassroomEvents\[E\]	要移除的回调。不传则移除该事件的所有监听器。

返回值: void

---

on()

监听事件（持续监听，直到手动取消）。

建议使用 TEvent.XXX 常量而非字符串字面量，可获得编译期类型安全和 IDE 自动补全。

参数	类型	说明
event	E	事件名（推荐 TEvent.XXX）
listener	ClassroomEvents\[E\]	回调函数，参数类型由 ClassroomEvents 精确推导

返回值: () => void

示例:

// 监听课堂开始 / Listen for class start
const off = classroom.on(TEvent.CLASS_START, () => console.log('课堂开始'));
off(); // 业务结束后取消 / Unsubscribe when done

// 监听被踢出 / Listen for kick-out
classroom.on(TEvent.KICK_OUT, ({ reason, message }) => {
  console.warn('kicked out:', reason);
  showAlert(message);
});

// 监听进房进度 / Listen for join progress
classroom.on(TEvent.JOIN_PROGRESS_CHANGED, ({ progress }) => {
  if (progress === JoinProgress.Completed) showSuccessUI();
});

---

once()

监听一次性事件（触发一次后自动取消）。

参数	类型	说明
event	E	事件名（推荐 TEvent.XXX）
listener	ClassroomEvents\[E\]	回调函数，触发一次后自动移除

返回值: () => void

示例:

classroom.once(TEvent.JOIN_CLASS, (classInfo) => {
  console.log('进房成功，课堂名：', classInfo.className);
});

---

waitFor()

等待事件触发，返回 Promise（只等待一次，效果等同 once 的异步版本）。

适用于"先进房、再执行下一步"的线性异步流程，代码比 on/once 更简洁。

参数	类型	说明
event	E	事件名
timeout?	number	超时毫秒数（不传则永不超时）。超时后 Promise reject，需自行 catch。

返回值: Promise<Parameters<ClassroomEvents\[E\]>\[0\]>

示例:

// 等待进房完成 / Wait for join to complete
const classInfo = await classroom.waitFor(TEvent.JOIN_CLASS);

// 设置 10 秒超时保护 / 10-second timeout
try {
  await classroom.waitFor(TEvent.JOIN_CLASS, 10000);
} catch {
  console.error('进房超时 / Join timed out');
}

---

classInfo

当前课堂信息（进房后有值，离房后为 null）。

与 state.classInfo$.get() 等价，提供同步读取快捷方式。

---

i18n

国际化引擎，用于语言切换、词条覆盖、注册自定义语言。 i18n engine — language switching, message overrides, custom locale registration.

---

initialized

引擎是否已完成初始化（即 init() 已成功调用并返回 ok=true）。

---

platform

平台检测工具，提供当前运行环境信息。

---

version

SDK 版本号（实例属性，等同 TencentClassroom.VERSION）。

---

VERSION

SDK 版本号（静态属性）。

示例:

TencentClassroom.VERSION // => '2.0.0'

---