白板与课件 API

互动白板操作和课件管理相关 API。白板基于 TEduBoard SDK 封装，课件管理支持上传、转码、加载全流程。

自动初始化

构造 SDK 时传入 { board: { domId: 'xxx' } } 后，进房时会自动初始化白板，无需手动调用 initBoard。

API 参考

boardInitTime

白板初始化耗时（ms）。

boardReady

白板是否就绪。

addBoardElement()

添加自定义元素（H5、富媒体等）到白板。

参数	类型	说明
type	`number`	元素类型（5=H5）
url	`string`	资源地址（H5 应用 URL 等）
options?	`any`	可选配置（如 `{ erasable: false }` 禁止橡皮擦除）

返回值: string

示例:

// 嵌入 H5 互动应用 / Embed an H5 interactive app
classroom.addBoardElement(5, 'https://your-h5.com/quiz', { erasable: false });

addBoardImagesFile()

添加图片课件到白板（多张图片合成一个文件）。

参数	类型	说明
urls	`string`[]	图片 URL 列表
title	`string`	文件标题

返回值: void

示例:

classroom.addBoardImagesFile(['https://cdn/img1.png', 'https://cdn/img2.png'], '图片课件');

addBoardPage()

新增白板页。

返回值: string

addBoardSignalForwardReceiver()

添加信令转发接收者。

参数	类型	说明
userId	`string`	接收者 userId

返回值: void

addBoardSyncData()

接收对端白板信令（由 CommandModule 调用，外部一般无需使用）。

参数	类型	说明
data	`BoardSyncData`	同步数据

返回值: void

addBoardTranscodeFile()

添加转码文件（课件）到白板，返回白板侧 fileId。

一般无需直接调用 — 使用 loadCourseware() 即可自动按课件类型分发到此方法。

参数	类型	说明
result	`BoardTranscodeResult`	转码结果（含 url、pages、resolution 等）

返回值: string

addBoardVideoFile()

添加视频课件到白板。

参数	类型	说明
url	`string`	视频地址
title	`string`	文件标题

返回值: void

示例:

classroom.addBoardVideoFile('https://cdn/lesson.mp4', '课程视频');

addOnlineCourseware()

添加在线 H5 课件（不需要上传，直接传 URL）。

课件以 H5 元素形式嵌入白板，所有端同步加载；适用于互动 H5 应用或外部嵌入页面。 suitable for interactive H5 apps or external pages.

参数	类型	说明
param	`AddOnlineCoursewareParam`	H5 课件参数（包含 url 与 title）

返回值: void

示例:

classroom.addOnlineCourseware({
  url: 'https://your-h5-app.com',
  title: '互动练习',
});

batchGetDocumentInfo()

批量获取课件简要信息（转码进度查询用）。

推荐用法：通过 getUploadingFiles() 拿到所有正在转码的 docId，再批量查询服务端最新进度。

参数	类型	说明
docIds	`string`[]	课件 ID 列表

返回值: Promise<TResult<BatchGetCoursewareInfoResult>>

bindDocumentToClass()

关联课件到当前课堂。

上传 (uploadCourseware) 后 SDK 已自动绑定，一般无需手动调用；该方法用于将学校课件库的存量课件绑定到本课堂。 uploadCourseware already auto-binds; this method is for binding pre-existing school-library coursewares into the current class.

参数	类型	说明
docId	`string`	课件 ID

返回值: Promise<TResult<void>>

示例:

// 从学校课件库选取已有课件绑定到本课堂 / Bind an existing library doc to this class
await classroom.bindDocumentToClass('doc_library_001');

boardPauseAudio()

暂停白板内嵌音频。

参数	类型	说明
elementId	`string`	音频元素 ID

返回值: void

boardPlayAudio()

播放白板内嵌音频。

参数	类型	说明
elementId	`string`	音频元素 ID

返回值: void

boardRefresh()

刷新白板。

返回值: void

boardShowVideoControl()

显示/隐藏视频控制条。

参数	类型	说明
show	`boolean`	是否显示

返回值: void

boardSyncAndReload()

同步历史数据并刷新白板。

返回值: void

cancelUploadCourseware()

取消 COS 上传任务（在 onReady 回调后、上传完成前可调用）。

参数	类型	说明
taskId	`string`	`uploadCourseware` 的 `onReady` 回调中获得的 taskId

返回值: void

示例:

// 用户点击"取消上传"按钮 / User clicks "cancel upload"
classroom.cancelUploadCourseware(currentTaskId);

clearBoard()

清空当前页内容。

返回值: void

deleteBoardFile()

删除指定文件。

参数	类型	说明
fileId?	`string`	文件 ID（不传则删除当前文件）

返回值: void

deleteDocument()

删除课件（仅老师/助教可操作）。

同时移除服务端记录和本地课件列表，触发 TEvent.DOC_LIST_UPDATED。

参数	类型	说明
docId	`string`	课件 ID

返回值: Promise<TResult<void>>

示例:

await classroom.deleteDocument('doc_001');

destroyBoard()

销毁白板实例（离房时 SDK 自动调用，一般无需手动调用）。

调用后白板 DOM 内容被清除，state.boardReady$ 变为 false。

返回值: void

enableBoardPermissionChecker()

启用白板的操作权限检查器（限制只有指定 operators 才能执行 actions）。

用于细粒度控制学生在白板上的操作能力，例如只允许某些学生上台后翻页或绘制。

参数	类型	说明
actions	`string`[]	需要检查权限的操作列表（如 `'Element::::'`、`'Board::Switch::Step'`）
operators	`string`[]	允许操作的用户列表（如 `[\`operator/${userId}`]`）

返回值: void

示例:

classroom.enableBoardPermissionChecker(
  ['Element::*::*', 'Board::Switch::Step'],
  [`operator/${currentUserId}`],
);

getBoard()

获取 Proxy 包装的 TEduBoard 原始实例（高级用法，用于直接调用未在 Facade 暴露的白板 API）。

⚠️ 仅在确实需要原生能力时使用，绕过 SDK 类型安全和事件机制；普通业务请优先使用 setBoardToolType / prevBoard 等 Facade 方法。

返回值: any

getBoardCurrentBoard()

获取当前白板 ID。

返回值: string

getBoardCurrentFile()

获取当前文件 ID。

返回值: string

getBoardCurrentPage()

获取当前页码。

返回值: number

getBoardFileInfo()

获取指定文件信息。

参数	类型	说明
fileId	`string`	文件 ID

返回值: any

getBoardFileInfoList()

获取文件列表。

返回值: any[]

getBoardScale()

获取当前缩放系数。

返回值: number

getBoardScroll()

获取当前滚动位置。

返回值: object

getBoardSignalForwardReceivers()

获取信令转发接收者列表。

返回值: string[]

getBoardTotalPages()

获取总页数。

返回值: number

getClassCoursewares()

获取当前课堂的课件列表。

进房后 SDK 自动调用一次，业务侧可主动刷新。返回的 CoursewareInfo 已包含运行时字段（forbid / type）。

参数	类型	说明
param?
docIds?	`string`[]
keyword?	`string`
limit?	`number`
page?	`number`

返回值: Promise<TResult<GetCoursewareListResult>>

示例:

const r = await classroom.getClassCoursewares({ page: 1, limit: 50, keyword: 'pptx' });
if (r.ok) renderCoursewarePanel(r.data.documents);

getDocumentInfo()

获取单个课件信息。

参数	类型	说明
docId	`string`	课件 ID

返回值: Promise<TResult<CoursewareInfo>>

示例:

const r = await classroom.getDocumentInfo('doc_001');
if (r.ok) console.log(r.data.title, r.data.fileUrl);

getSchoolCoursewares()

获取当前学校的全部课件列表（课件库搜索/管理场景）。

用于"课件库"页面，可按权限、所有者、关键词等过滤；与课堂级别的 getClassCoursewares 区分。

参数	类型	说明
param?
keyword?	`string`
limit?	`number`
owner?	`string`
page?	`number`
permission?	`number`[]

返回值: Promise<TResult<GetCoursewareListResult>>

示例:

const r = await classroom.getSchoolCoursewares({
  page: 1,
  limit: 50,
  permission: [0, 1], // 0=私有 1=公共 / 0=private 1=public
  keyword: '第一章',
});

getUploadingFiles()

获取所有正在上传/转码中的文件跟踪列表。

用于在课堂面板中渲染"上传队列" UI；UIKit 层也可监听 TEvent.DOC_UPLOAD_PROGRESS 事件获取实时更新。

返回值: UploadTrackInfo[]

示例:

const list = classroom.getUploadingFiles();
console.log(`${list.length} files in progress`);

getUploadTrack()

根据 docId 获取上传跟踪信息。

参数	类型	说明
docId	`string`	课件 ID

返回值: UploadTrackInfo | undefined

gotoBoard()

跳转到指定白板页。

参数	类型	说明
boardId	`string`	白板页 ID

返回值: void

gotoBoardPage()

跳转到指定步骤页码。

参数	类型	说明
page	`number`	页码（0-based）

返回值: void

示例:

// 跳转到第 3 页 / Jump to the 3rd page
classroom.gotoBoardPage(2);

hasUploadingFiles()

是否有正在上传/转码中的文件（用于阻止离房等关键操作）。

返回值: boolean

示例:

if (classroom.hasUploadingFiles()) {
  if (!confirm('有课件正在上传，确认离开？')) return;
}
await classroom.leaveClass();

initBoard()

手动初始化白板（仅在构造时未配置 board.domId 时使用）。

通常无需调用：构造时传 { board: { domId: 'xxx' } } 后进房时会自动初始化白板。

初始化完成后 state.boardReady$ 变为 true 并触发 TEvent.BOARD_READY。

参数	类型	说明
params	`BoardInitParams`	白板初始化参数（必须包含 `domId`）

返回值: Promise<TResult<void>>

示例:

// DOM 元素动态创建场景：等待容器挂载后再初始化 / Dynamic mount: init after the DOM is ready
const result = await classroom.initBoard({ domId: 'whiteboard-container' });
if (!result.ok) console.error('Board init failed:', result.message);

// 监听就绪事件 / Wait for ready event
classroom.on(TEvent.BOARD_READY, () => console.log('Board ready'));

isBoardAudioPlaying()

白板文档音频是否播放中。

返回值: boolean

isBoardVideoPlaying()

白板文档视频是否播放中。

返回值: boolean

isWebForbidDocType()

判断是否为 Web 端不支持的音视频格式（如 .avi、.wmv 等）。

processDoc() 内部会用此方法填充 forbid 字段，业务侧通常无需直接调用。 processDoc() uses this internally to populate the forbid field; rarely called directly.

参数	类型	说明
docType	`string`	文档类型后缀（小写，不含点；如 `'avi'`）

返回值: boolean

loadCourseware()

使用课件（加载到白板）。

根据课件类型自动分发：图片 / 视频 / 音频 / 转码文档 / H5。不直接操作白板，通过 TEvent.DOC_LOAD_COURSEWARE 事件解耦。

参数	类型	说明
docInfo	`CoursewareInfo`	课件信息
refresh?	`boolean = false`	是否强制刷新（开课时重新加载同一课件）

返回值: void

示例:

typescript

const res = await classroom.getClassCoursewares();
if (res.ok && res.data.list.length > 0) {
  classroom.loadCourseware(res.data.list[0]);
}

nextBoard()

翻到当前文件的下一页白板。

返回值: void

示例:

classroom.nextBoard();

nextBoardPage()

下一页（nextBoard 别名）。

返回值: void

prevBoard()

翻到当前文件的上一页白板。

返回值: void

示例:

classroom.prevBoard();

prevBoardPage()

上一页（prevBoard 别名）。

返回值: void

processDoc()

处理课件信息，填充运行时字段（forbid / type）。

服务端返回的 CoursewareInfo 缺少前端展示所需的两个字段：

forbid：是否在 Web 端禁用（如 .avi/.wmv 等浏览器不支持的格式）
type：归一化后的图标分类（doc / image / video / audio / h5 / unknown）

loadCourseware() 调用前必须先调用此方法处理。 loadCourseware() requires the input to be processed first.

参数	类型	说明
docInfo	`CoursewareInfo`	课件信息（来自 `getClassCoursewares` / `getSchoolCoursewares` 等接口）

返回值: CoursewareInfo

示例:

const r = await classroom.getClassCoursewares();
if (r.ok) {
  const docs = r.data.documents.map((d) => classroom.processDoc(d));
  docs.forEach((d) => {
    if (d.forbid) console.log(`${d.title} 在 Web 端不支持`);
  });
}

redoBoard()

重做。

返回值: void

saveBoardSnapshot()

保存白板截图（多端适配：Web / Electron / Native Mobile）。

通常先通过 getBoard().snapshot() 等原生方法获取 base64，再调用此方法分发到对应平台保存。

参数	类型	说明
snapId	`string`	截图 ID（业务自定义唯一标识）
base64Data	`string`	截图 base64 数据（通常带 `data:image/png;base64,` 前缀）
snapName?	`string`	截图文件名（可选）
sliceUnit?	`number`	分片大小（Native 端用于分片传输大图，可选）
dialog?	`boolean`	是否弹出系统保存对话框（Electron 桌面端，可选）

返回值: Promise<TResult<unknown>>

示例:

// 配合白板原生 snapshot 接口 / Combined with the native snapshot API
const board = classroom.getBoard();
board.snapshot((base64: string) => {
  classroom.saveBoardSnapshot(`snap_${Date.now()}`, base64, 'snap.png');
});

setBoardBackgroundColor()

设置白板背景色。

参数	类型	说明
color	`string`	背景色

返回值: void

setBoardBackgroundImage()

设置白板背景图。

参数	类型	说明
url	`string`	图片地址
mode?	`BoardFitMode`	适配模式

返回值: void

setBoardContentFitMode()

设置内容适配模式。

参数	类型	说明
mode	`BoardFitMode`	适配模式

返回值: void

setBoardDataSyncEnable()

启用/禁用数据同步。

参数	类型	说明
enable	`boolean`	是否启用

返回值: void

setBoardDrawEnable()

启用/禁用涂鸦（关闭后画笔等工具点击无效）。

参数	类型	说明
enable	`boolean`	是否启用

返回值: void

setBoardPPTVideoSyncMaster()

设置 PPT 视频同步主控。

参数	类型	说明
enable	`boolean`	是否启用

返回值: void

setBoardScale()

设置缩放系数。

参数	类型	说明
scale	`number`	缩放系数

返回值: void

setBoardSignalForwardReceivers()

设置信令转发接收者列表。

参数	类型	说明
userIds	`string`[]	接收者 userId 列表

返回值: void

setBoardSpeakerDevice()

设置白板扬声器设备。

参数	类型	说明
deviceLabel	`string`	设备标签

返回值: void

setBoardSpeakerDeviceForPPT()

设置 PPT 音频扬声器设备。

参数	类型	说明
deviceLabel	`string`	设备标签

返回值: void

setBoardToolType()

切换白板工具类型（画笔/橡皮/文本/激光笔等）。

参数	类型	说明
type	`BoardToolType`	- `BoardToolType.ZoomDrag`(16) 缩放拖拽 / zoom & drag

返回值: void

示例:

import { BoardToolType } from '@tencent-classroom/sdk';
classroom.setBoardToolType(BoardToolType.Pen);

setBrushColor()

设置画笔颜色。

参数	类型	说明
color	`string`	颜色值（如 `'#FF0000'`）

返回值: void

示例:

classroom.setBrushColor('#1890ff');

setBrushThin()

设置画笔粗细。

实际渲染像素 = thin × 白板高度 / 10000；建议取值 50~300。

参数	类型	说明
thin	`number`	粗细值（白板坐标系单位）

返回值: void

setCursorIcon()

设置自定义光标图标。

参数	类型	说明
toolType	`BoardToolType`	工具类型
icon
cursor	`string`
offsetX	`number`
offsetY	`number`
url	`string`

返回值: void

setHandwritingEnable()

启用/禁用笔锋效果。

参数	类型	说明
enable	`boolean`	是否启用

返回值: void

setMouseToolBehavior()

设置鼠标工具行为。

参数	类型	说明
behavior	`MouseToolBehavior`	鼠标行为模式

返回值: void

setScaleAnchor()

设置缩放锚点。

参数	类型	说明
x	`number`	锚点 X 坐标
y	`number`	锚点 Y 坐标

返回值: void

setSystemCursorEnable()

启用/禁用系统光标。

参数	类型	说明
enable	`boolean`	是否启用

返回值: void

setTextColor()

设置文本颜色。

参数	类型	说明
color	`string`	颜色值

返回值: void

setTextSize()

设置文本大小。

参数	类型	说明
size	`number`	字号

返回值: void

setTextStyle()

设置文本样式。

参数	类型	说明
style	`0 \| 1 \| 2 \| 3`	0=常规 1=粗体 2=斜体 3=粗斜体 / 0=normal 1=bold 2=italic 3=bold-italic

返回值: void

setToolTypeTitle()

设置工具类型标题（显示操作者昵称）。

参数	类型	说明
title	`string`	标题文本
config
color	`string`
displaySelf	`boolean`
position	`number`
size	`number`
style	`number`
toolType	`BoardToolType`	工具类型

返回值: void

switchBoardFile()

切换到指定文件。

参数	类型	说明
fileId	`string`	文件 ID（来自 `addBoardTranscodeFile` 等返回值或 `getBoardFileInfoList`）

返回值: void

unbindDocumentFromClass()

取消课件与课堂的关联（不删除课件本身，仅从本课堂移除）。

参数	类型	说明
docId	`string`	课件 ID

返回值: Promise<TResult<void>>

undoBoard()

撤销。

返回值: void

uploadCourseware()

上传课件到 COS 并创建文档记录（完整流程）。

进度通过 onReady / onProgress 回调通知（axios 风格）。最终结果通过 Promise<TResult> 返回。

参数	类型	说明
param	`UploadCoursewareParam`	上传参数

返回值: Promise<TResult<UploadCoursewareResult>>

示例:

typescript

const result = await classroom.uploadCourseware({
  file,
  schoolId: 100,
  permission: CoursewarePermission.Private,
  docType: 'pptx',
  onReady: (taskId) => { this.uploadTaskId = taskId; },
  onProgress: (loaded, total, speed, percent) => {
    this.progress = Math.round(percent * 100);
  },
});
if (!result.ok) { toast.error(result.message); return; }
console.log('上传成功，docId:', result.data.docId);

validateUploadFile()

校验上传文件的格式和大小。

在触发文件选择框后、开始上传前调用，快速给出错误提示。不需要网络请求，同步返回。

参数	类型	说明
file	`File`	待上传的文件

返回值: TResult<void>

白板与课件 API ​

API 参考 ​

boardInitTime ​

boardReady ​

addBoardElement() ​

addBoardImagesFile() ​

addBoardPage() ​

addBoardSignalForwardReceiver() ​

addBoardSyncData() ​

addBoardTranscodeFile() ​

addBoardVideoFile() ​

addOnlineCourseware() ​

batchGetDocumentInfo() ​

bindDocumentToClass() ​

boardPauseAudio() ​

boardPlayAudio() ​

boardRefresh() ​

boardShowVideoControl() ​

boardSyncAndReload() ​

cancelUploadCourseware() ​

clearBoard() ​

deleteBoardFile() ​

deleteDocument() ​

destroyBoard() ​

enableBoardPermissionChecker() ​

getBoard() ​

getBoardCurrentBoard() ​

getBoardCurrentFile() ​

getBoardCurrentPage() ​

getBoardFileInfo() ​

getBoardFileInfoList() ​

getBoardScale() ​

getBoardScroll() ​

getBoardSignalForwardReceivers() ​

getBoardTotalPages() ​

getClassCoursewares() ​

getDocumentInfo() ​

getSchoolCoursewares() ​

getUploadingFiles() ​

getUploadTrack() ​

gotoBoard() ​

gotoBoardPage() ​

hasUploadingFiles() ​

initBoard() ​

isBoardAudioPlaying() ​

isBoardVideoPlaying() ​

isWebForbidDocType() ​

loadCourseware() ​

nextBoard() ​

nextBoardPage() ​

prevBoard() ​

prevBoardPage() ​

processDoc() ​

redoBoard() ​

saveBoardSnapshot() ​

setBoardBackgroundColor() ​

setBoardBackgroundImage() ​

setBoardContentFitMode() ​

setBoardDataSyncEnable() ​

setBoardDrawEnable() ​

setBoardPPTVideoSyncMaster() ​

setBoardScale() ​

setBoardSignalForwardReceivers() ​

setBoardSpeakerDevice() ​

setBoardSpeakerDeviceForPPT() ​

setBoardToolType() ​

setBrushColor() ​

setBrushThin() ​

setCursorIcon() ​

setHandwritingEnable() ​

setMouseToolBehavior() ​

setScaleAnchor() ​

setSystemCursorEnable() ​

setTextColor() ​

setTextSize() ​

setTextStyle() ​

setToolTypeTitle() ​

switchBoardFile() ​

unbindDocumentFromClass() ​

undoBoard() ​

白板与课件 API

API 参考

boardInitTime

boardReady

addBoardElement()

addBoardImagesFile()

addBoardPage()

addBoardSignalForwardReceiver()

addBoardSyncData()

addBoardTranscodeFile()

addBoardVideoFile()

addOnlineCourseware()

batchGetDocumentInfo()

bindDocumentToClass()

boardPauseAudio()

boardPlayAudio()

boardRefresh()

boardShowVideoControl()

boardSyncAndReload()

cancelUploadCourseware()

clearBoard()

deleteBoardFile()

deleteDocument()

destroyBoard()

enableBoardPermissionChecker()

getBoard()

getBoardCurrentBoard()

getBoardCurrentFile()

getBoardCurrentPage()

getBoardFileInfo()

getBoardFileInfoList()

getBoardScale()

getBoardScroll()

getBoardSignalForwardReceivers()

getBoardTotalPages()

getClassCoursewares()

getDocumentInfo()

getSchoolCoursewares()

getUploadingFiles()

getUploadTrack()

gotoBoard()

gotoBoardPage()

hasUploadingFiles()

initBoard()

isBoardAudioPlaying()

isBoardVideoPlaying()

isWebForbidDocType()

loadCourseware()

nextBoard()

nextBoardPage()

prevBoard()

prevBoardPage()

processDoc()

redoBoard()

saveBoardSnapshot()

setBoardBackgroundColor()

setBoardBackgroundImage()

setBoardContentFitMode()

setBoardDataSyncEnable()

setBoardDrawEnable()

setBoardPPTVideoSyncMaster()

setBoardScale()

setBoardSignalForwardReceivers()

setBoardSpeakerDevice()

setBoardSpeakerDeviceForPPT()

setBoardToolType()

setBrushColor()

setBrushThin()

setCursorIcon()

setHandwritingEnable()

setMouseToolBehavior()

setScaleAnchor()

setSystemCursorEnable()

setTextColor()

setTextSize()

setTextStyle()

setToolTypeTitle()

switchBoardFile()

unbindDocumentFromClass()

undoBoard()