全局事件
SDK 通过事件通知业务层状态变化。所有事件通过 classroom.on(TEvent.XXX, handler) 监听。
使用方式
typescript
import { TencentClassroom, TEvent } from '@tencent-classroom/sdk';
const classroom = new TencentClassroom();
await classroom.init();
// 持久监听
classroom.on(TEvent.KICK_OUT, ({ reason, message }) => {
alert(message);
});
// 一次性监听
classroom.once(TEvent.CLASS_START, () => {
console.log('课堂已开始');
});
// Promise 风格等待
await classroom.waitFor(TEvent.JOIN_CLASS);事件列表
课堂生命周期
| 常量 | 事件值 | 说明 |
|---|---|---|
TEvent.JOIN_CLASS | joinClass | 进房成功（joinClass 完成，所有模块就绪） |
TEvent.LEAVE_CLASS | leaveClass | 离房完成（leaveClass 所有资源释放后触发） |
TEvent.BEFORE_LEAVE | beforeLeave | 即将离房（leaveClass 开始时触发，可用于显示"离开中..."Loading） |
TEvent.AFTER_LEAVE | afterLeave | 离房结束后（LEAVE_CLASS 之后触发） |
TEvent.CLASS_INFO_MODIFIED | classInfoModified | 课堂信息被修改（服务端下发 class_info_modified 信令） |
TEvent.CLASS_START | classStart | 课堂开始（startClass 成功后所有端收到） |
TEvent.CLASS_END | classEnd | 课堂结束（endClass 成功后所有端收到） |
TEvent.KICK_OUT | kickOut | 被踢出课堂（payload 含原因和本地化消息） |
TEvent.CLASS_INFO_CHANGE_REQUESTED | classInfoChangeRequested | 课堂信息变更请求（需要本地确认的课堂配置变更） |
TEvent.CLASS_INFO_UPDATED | classInfoUpdated | 课堂信息已更新（classInfo$ 同步完成后触发） |
TEvent.CLASS_TASK_CHANGE | classTaskChange | 课堂任务列表变更（白板任务 ClassTask 列表变化） |
TEvent.TASK_UPDATED | taskUpdated | 单个业务任务更新（防乱序处理后触发，携带完整 TaskInfo） |
TEvent.ENABLE_STAGE_CHANGED | enableStageChanged | 举手连麦开关状态变化（老师操作后所有端同步）。 |
TEvent.JOIN_PROGRESS_CHANGED | joinProgressChanged | 进房流程阶段变化（每次 JoinProgress 枚举值切换时触发）。 |
成员事件
| 常量 | 事件值 | 说明 |
|---|---|---|
TEvent.MEMBER_JOIN | memberJoin | 成员加入课堂（包含完整 MemberInfo） |
TEvent.MEMBER_LEAVE | memberLeave | 成员离开课堂（包含完整 MemberInfo） |
TEvent.MEMBER_STAGE_UP | memberStageUp | 成员上台（stage=true，包含完整 MemberInfo） |
TEvent.MEMBER_STAGE_DOWN | memberStageDown | 成员下台（stage=false，包含完整 MemberInfo） |
TEvent.MEMBER_DEVICE_CHANGE | memberDeviceChange | 成员设备状态变更（change_member_stream 信令驱动，通知 MediaRenderer 刷新渲染）。 |
TEvent.SELF_ONLINE | selfOnline | 自己上线（成员列表确认当前用户在线） |
TEvent.SELF_OFFLINE | selfOffline | 自己掉线/断线（可能触发重连流程） |
权限事件
| 常量 | 事件值 | 说明 |
|---|---|---|
TEvent.PERMISSION_UPDATE | permissionUpdate | 权限列表批量更新（老师操作权限后所有端收到） |
TEvent.MY_PERMISSION_CHANGE | myPermissionChange | 自己的权限变化（state.boardPermission$ 等同步前此事件触发） |
TEvent.SCHOOL_INFO_READY | schoolInfoReady | 学校信息加载完成（含套餐配置和水印配置） |
设备事件
| 常量 | 事件值 | 说明 |
|---|---|---|
TEvent.DEVICE_CHANGE | deviceChange | 本地设备插拔变更（摄像头/麦克风/扬声器 接入或拔出）。 |
RTC 事件
| 常量 | 事件值 | 说明 |
|---|---|---|
TEvent.USER_ENTER_ROOM | userEnterRoom | 远端用户进入 TRTC 房间 |
TEvent.USER_LEAVE_ROOM | userLeaveRoom | 远端用户离开 TRTC 房间 |
TEvent.USER_VIDEO_AVAILABLE | userVideoAvailable | 远端用户视频流可用/不可用（available=true 表示开启摄像头，false 表示关闭）。 |
TEvent.USER_AUDIO_AVAILABLE | userAudioAvailable | 远端用户音频流可用/不可用。 |
TEvent.USER_AUDIO_MUTE | userAudioMute | 远端用户音频 mute/unmute（主动静音，与 available 不同）。 |
TEvent.USER_SUB_STREAM_AVAILABLE | userSubStreamAvailable | 远端用户辅流（屏幕共享）可用/不可用 |
TEvent.LOCAL_VIDEO_STATS | localVideoStats | 本地视频推流统计数据（每 2s 触发一次） |
TEvent.LOCAL_AUDIO_STATS | localAudioStats | 本地音频推流统计数据 |
TEvent.REMOTE_VIDEO_STATS | remoteVideoStats | 远端视频拉流统计数据 |
TEvent.REMOTE_AUDIO_STATS | remoteAudioStats | 远端音频拉流统计数据 |
TEvent.SCREEN_SHARE_STARTED | screenShareStarted | 本端屏幕共享已开启 |
TEvent.SCREEN_SHARE_STOPPED | screenShareStopped | 本端屏幕共享已停止 |
TEvent.REMOTE_SCREEN_SHARE_STARTED | remoteScreenShareStarted | 远端用户开始屏幕共享（payload 含 userId） |
TEvent.REMOTE_SCREEN_SHARE_STOPPED | remoteScreenShareStopped | 远端用户停止屏幕共享 |
IM 事件
| 常量 | 事件值 | 说明 |
|---|---|---|
TEvent.RECV_MESSAGE | recvMessage | 收到新聊天消息（已加入 messageList$，此事件用于触发通知/滚动等 UI 操作） |
TEvent.RECV_CUSTOM_MSG | recvCustomMsg | 收到原始自定义群消息（未经 SDK 解析，ext/data/from 字段原样透传） |
TEvent.RECV_CUSTOM_IM_MSG | recvCustomImMsg | 收到自定义 IM 消息（已包装为 Message 格式） |
TEvent.MESSAGE_REVOKED | messageRevoked | 消息被撤回（msgId 为被撤回消息的 ID） |
TEvent.IM_CONNECTED | imConnected | IM 已连接 |
TEvent.IM_DISCONNECTED | imDisconnected | IM 断开（正在重连或无法重连） |
TEvent.IM_KICKED | imKicked | IM 账号在其他端登录，本端被踢出 |
TEvent.IM_SIG_EXPIRED | imSigExpired | IM 签名过期（需重新获取 sig 后重新进房） |
TEvent.IM_CMD_MESSAGE | imCmdMessage | 信令群指令消息（来自 cmdGroup，gzip 解压后，内部模块消费） |
TEvent.IM_C2C_ADMIN_MSG | imC2CAdminMsg | 后端 C2C saasadmin 下发控制指令（内部模块消费） |
白板事件
| 常量 | 事件值 | 说明 |
|---|---|---|
TEvent.BOARD_ERROR | boardError | 白板运行时错误（code=1/3/8 等，重试耗尽后触发，业务层应展示错误提示）。 |
TEvent.BOARD_SIG_ERROR | boardSigError | 白板签名/鉴权错误（code=7 签名过期 / code=11 签名无效，需重新进房）。 |
TEvent.BOARD_READY | boardReady | 白板就绪（历史数据同步完成，boardReady$=true，可执行翻页/工具等操作）。 |
TEvent.BOARD_INIT | boardInit | 白板 DOM 挂载完成（TEB_INIT，历史数据同步中） |
TEvent.BOARD_WARN | boardWarn | 白板非致命警告（code=10 页数达上限等） |
TEvent.BOARD_IMAGE_STATUS_CHANGED | boardImageStatusChanged | 白板图片加载状态变更（TEB_IMAGE_STATUS_CHANGED） |
TEvent.BOARD_H5PPT_STATUS_CHANGED | boardH5PptStatusChanged | H5 PPT 动效状态变更（TEB_H5PPT_STATUS_CHANGED） |
TEvent.BOARD_H5FILE_STATUS_CHANGED | boardH5FileStatusChanged | H5 文件状态变更（TEB_H5FILE_STATUS_CHANGED） |
TEvent.BOARD_MEDIA_STATUS_CHANGED | boardMediaStatusChanged | 白板 PPT 媒体播放状态（TEB_H5PPT_MEDIA_STATUS_CHANGED）。 |
TEvent.BOARD_VIDEO_STATUS_CHANGED | boardVideoStatusChanged | 白板内嵌视频状态变更（TEB_VIDEO_STATUS_CHANGED） |
TEvent.BOARD_AUDIO_STATUS_CHANGED | boardAudioStatusChanged | 白板音频状态变更（TEB_AUDIO_STATUS_CHANGED） |
TEvent.BOARD_ADD_TRANSCODE_FILE | boardAddTranscodeFile | 转码课件加载到白板成功（TEB_ADDTRANSCODEFILE，返回白板内部 fileId）。 |
课件事件
| 常量 | 事件值 | 说明 |
|---|---|---|
TEvent.DOC_LOAD_COURSEWARE | docLoadCourseware | 课件加载到白板的内部事件（DocModule → BoardModule，SDK 内部解耦）。 |
TEvent.DOC_PLAY_AUDIO | docPlayAudio | 音频课件播放指令（SDK 不内置播放器，由 UIKit 层实现）。 |
TEvent.DOC_LIST_UPDATED | docListUpdated | 课件列表更新（上传/删除/进房后自动触发；data.documents 为完整课件列表）。 |
TEvent.DOC_TRANSCODE_PROGRESS | docTranscodeProgress | 课件转码进度更新（内部，一般通过 DOC_UPLOAD_PROGRESS 统一消费） |
TEvent.DOC_UPLOAD_PROGRESS | docUploadProgress | 课件上传/转码进度更新（贯穿整个上传周期：COS 上传 → 服务端转码 → 完成）。 |
媒体播放事件
| 常量 | 事件值 | 说明 |
|---|---|---|
TEvent.VOD_START | vodStart | VOD 视频开始播放（payload 含 url） |
TEvent.VOD_PAUSE | vodPause | VOD 视频暂停 |
TEvent.VOD_RESUME | vodResume | VOD 视频恢复播放 |
TEvent.VOD_STOP | vodStop | VOD 视频停止 |
TEvent.VOD_END | vodEnd | VOD 视频播放完毕 |
TEvent.VOD_SEEK | vodSeek | VOD 视频跳转（payload 含 time 秒） |
TEvent.MUSIC_START | musicStart | 背景音乐开始播放（payload 含 url） |
TEvent.MUSIC_STOP | musicStop | 背景音乐停止 |
TEvent.MUSIC_PAUSE | musicPause | 背景音乐暂停 |
TEvent.MUSIC_RESUME | musicResume | 背景音乐恢复 |
TEvent.MUSIC_SEEK | musicSeek | 背景音乐跳转 |
字幕事件
| 常量 | 事件值 | 说明 |
|---|---|---|
TEvent.SUBTITLE_UPDATE | subtitleUpdate | 收到实时字幕数据（来自 TRTC 自定义消息或云端 ASR）。 |
TEvent.RTC_CUSTOM_MSG | rtcCustomMsg | TRTC 自定义消息中继（RtcModule → SubtitleModule，内部事件） |
水印
| 常量 | 事件值 | 说明 |
|---|---|---|
TEvent.WATERMARK_UPDATE | watermarkUpdate | 水印配置变更（setWatermarkConfig 调用或服务端下发后触发）。 |
TEvent.MARQUEE_UPDATE | marqueeUpdate | 跑马灯配置变更（setMarqueeConfig 调用或服务端下发后触发）。 |
网络检测事件
| 常量 | 事件值 | 说明 |
|---|---|---|
TEvent.NETWORK_SPEED_TEST_RESULT | networkSpeedTestResult | TRTC 测速结果（checkMediaServerConnection 完成后触发）。 |
网络监控事件
| 常量 | 事件值 | 说明 |
|---|---|---|
TEvent.NETWORK_BROKEN | networkBroken | 网络断开（globalNetworkStatus$.needStrongAlert=true 时通常已触发 GlobalAlert） |
TEvent.NETWORK_WEAK | networkWeak | 网络弱（画质可能降级） |
TEvent.NETWORK_RECOVERED | networkRecovered | 网络恢复正常 |
举手
| 常量 | 事件值 | 说明 |
|---|---|---|
TEvent.HAND_UP | handUp | 某成员举手/取消举手（status=true=举手，status=false=取消） |
TEvent.ASK_STAGE_REQUEST | askStageRequest | 学生发起申请上台请求（老师端收到，可审批或拒绝） |
TEvent.ASK_STAGE_ACCEPTED | askStageAccepted | 老师同意自己的申请上台（学生端收到） |
TEvent.ASK_STAGE_REJECTED | askStageRejected | 老师拒绝自己的申请上台（学生端收到） |
TEvent.ASK_STAGE_CANCELLED | askStageCancelled | 老师取消/清空邀请列表，自己不再在列表中（学生端收到） |
TEvent.ASK_STAGE_UPDATE | askStageUpdate | 举手邀请列表更新（v1/stage 信令驱动） |
TEvent.STAGE_LOOP_ACTION | stageLoopAction | 循环上台动作通知（v1/stage_loop 信令驱动） |
C2C 控制事件
| 常量 | 事件值 | 说明 |
|---|---|---|
TEvent.RECV_MEMBER_ACTION | recvMemberAction | 老师执行成员操作（C2C type=0，来自 saasadmin，学生端接收） |
TEvent.QUESTION_ANSWERED | questionAnswered | 有学生提交了答题答案（老师端收到，questionId 用于对应题目） |
TEvent.TRANSLATE_MSG | translateMsg | 翻译结果回调（v1/translate 信令，包含原文和译文） |
答题器事件
| 常量 | 事件值 | 说明 |
|---|---|---|
TEvent.QUESTION_BEGIN | questionBegin | 答题开始（所有端收到，payload 含题目 ID/选项数/时长等） |
TEvent.QUESTION_ABANDON | questionAbandon | 答题废弃/取消（不计分，直接结束） |
TEvent.QUESTION_CLOSE | questionClose | 答题关闭（可查看统计，但仍接受答案一段时间） |
TEvent.QUESTION_END | questionEnd | 答题完全结束（状态重置为 idle） |
AI 课堂
| 常量 | 事件值 | 说明 |
|---|---|---|
TEvent.AI_CLASS_READY | aiClassReady | AI 课堂就绪（taskId 为 AI 任务 ID） |
AV 权限变更（细粒度，联动 MediaRenderer）
| 常量 | 事件值 | 说明 |
|---|---|---|
TEvent.AV_ADD | avAdd | 新增 AV 权限条目（成员新上台或获得新权限） |
TEvent.AV_UPDATE | avUpdate | AV 权限条目更新（stage/camera/mic/screen 等字段变化） |
TEvent.AV_REMOVE | avRemove | AV 权限条目移除（成员下台） |
TEvent.ADJUST_HEARTBEAT | adjustHeartbeat | @internal 请求调整心跳间隔（MemberModule → RoomModule） |
TEvent.RESTORE_HEARTBEAT | restoreHeartbeat | @internal 请求恢复默认心跳间隔 |
TEvent.BURST_HEARTBEAT | burstHeartbeat | Burst heartbeat (PermissionModule self-offline → RoomModule) |
TEvent.CONFIRM_ACTION | confirmAction | @internal 需要用户确认的操作（如邀请上台弹框） |
TEvent.SILENCE_USER | silenceUser | User silenced/unsilenced (MemberModule → ImModule; triggers silenceUserOnMsgList) (internal) |
TEvent.HEARTBEAT_TASK_SEQ | heartbeatTaskSeq | @internal 心跳驱动的任务序列号同步（RoomModule → ClassModule） |
TEvent.HEARTBEAT_PERMISSION_SEQ | heartbeatPermissionSeq | @internal 心跳驱动的权限序列号同步（RoomModule → PermissionModule） |
TEvent.PERMISSION_REVOKED | permissionRevoked | Permission revoked (PermissionModule → RtcModule; triggers device stop) (internal) |
TEvent.MUTE_ALL_CHANGED | muteAllChanged | All-mute changed (ClassModule → RtcModule; stops local mic on mute) (internal) |
TEvent.MUTE_VIDEO_ALL_CHANGED | muteVideoAllChanged | All-video-mute changed (ClassModule → RtcModule; stops local camera on mute) (internal) |
TEvent.KICKOUT_CMD | kickoutCmd | @internal kickOut 信令指令（CommandModule → KickOutHandler） |
TEvent.KICKOUT_FOREVER_CMD | kickoutForeverCmd | @internal kickOutForever 信令指令（CommandModule → KickOutHandler） |
TEvent.PERMISSION_SYNC | permissionSync | @internal 权限列表同步（CommandModule → PermissionModule） |
TEvent.SET_MUSIC_VOLUME | setMusicVolume | @internal 设置背景音乐音量（MediaPlayModule → RtcModule） |
移动端事件
| 常量 | 事件值 | 说明 |
|---|---|---|
TEvent.SOFT_KEYBOARD | softKeyboard | 软键盘弹出/收回（visible=true 弹出，height 单位 px） |
TEvent.APP_RESIZED | appResized | 应用窗口尺寸变化（Electron 或 WebView 宿主调整窗口大小） |
TEvent.BACK_PRESSED | backPressed | 移动端返回键按下（Android 系统返回按钮） |
TEvent.ORIENTATION_CHANGE | orientationChange | 设备方向变化（portrait/landscape） |
资源加载事件
| 常量 | 事件值 | 说明 |
|---|---|---|
TEvent.LOAD_RESOURCE_ERROR | loadResourceError | 资源加载错误（白板 SDK / 第三方脚本等） |
TEvent.TRY_RELOAD_RESOURCE | tryReloadResource | 尝试重新加载资源 |
版本
| 常量 | 事件值 | 说明 |
|---|---|---|
TEvent.VERSION_UPDATE | versionUpdate | 检测到新版本可用（UIKit 可弹出更新提示） |
TEvent.LANGUAGE_CHANGED | languageChanged | 语言切换完成（setLocale 调用后触发）。 |
错误
| 常量 | 事件值 | 说明 |
|---|---|---|
TEvent.ERROR | error | 统一错误通道（所有模块错误汇聚于此，payload 含 module / code / message / detail）。 |
TEvent.WARN | warn | 统一警告通道（非致命问题，如白板页数接近上限）。 |
快直播事件
| 常量 | 事件值 | 说明 |
|---|---|---|
TEvent.STREAM_UPDATE | streamUpdate | 流列表更新（RoomModule 进房时 + CommandModule change_member_stream 信令驱动）。 |
TEvent.AUTOPLAY_FAILED | autoplayFailed | 浏览器自动播放策略阻止了视频播放（TCPlayer blocked 事件触发）。 |
TEvent.AUTOPLAY_CONFIRM | autoplayConfirm | 用户已点击确认播放，所有被阻播放器已恢复（可隐藏"点击播放"提示）。 |
TEvent.LIVE_VOLUME_UPDATE | liveVolumeUpdate | 快直播音量回调（WebLiveAdapter.enableVolumeEvaluation 驱动，用于音量动画 UI）。 |