Whiteboard & Courseware API

Interactive whiteboard operations and courseware document management.

API Reference

boardInitTime

Whiteboard initialization duration in milliseconds.

boardReady

Whether the whiteboard is ready.

addBoardElement()

Add a custom element (H5, rich media, etc.) to the whiteboard.

Parameter	Type	Description
type	`number`	Element type (5 = H5)
url	`string`	Resource URL
options?	`any`	Optional config (e.g., `{ erasable: false }`)

Returns: string

Example:

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

addBoardImagesFile()

Add an image courseware (a single file containing multiple image pages) to the whiteboard.

Parameter	Type	Description
urls	`string`[]	Image URL list
title	`string`	File title

Returns: void

Example:

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

addBoardPage()

Add a new whiteboard page.

Returns: string

addBoardSignalForwardReceiver()

Add a signal forwarding receiver.

Parameter	Type	Description
userId	`string`	Receiver user ID

Returns: void

addBoardSyncData()

Receive remote whiteboard signaling data (called by CommandModule; not for external use).

Parameter	Type	Description
data	`BoardSyncData`	Sync data

Returns: void

addBoardTranscodeFile()

Add a transcoded file (courseware) onto the whiteboard; returns the board-side fileId.

Usually not called directly — loadCourseware() automatically dispatches here based on courseware type.

Parameter	Type	Description
result	`BoardTranscodeResult`	Transcode result (url / pages / resolution, etc.)

Returns: string

addBoardVideoFile()

Add a video courseware to the whiteboard.

Parameter	Type	Description
url	`string`	Video URL
title	`string`	File title

Returns: void

Example:

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

addOnlineCourseware()

Add an online H5 courseware (no upload required — just provide a URL).

The courseware is embedded into the whiteboard as an H5 element and synced across clients; suitable for interactive H5 apps or external pages.

Parameter	Type	Description
param	`AddOnlineCoursewareParam`	Online courseware params (url + title)

Returns: void

Example:

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

batchGetDocumentInfo()

Batch-get brief courseware info (for polling transcode progress).

Recommended: get all transcoding docIds via getUploadingFiles() and then batch-query the latest progress.

Parameter	Type	Description
docIds	`string`[]	Document ID list

Returns: Promise<TResult<BatchGetCoursewareInfoResult>>

bindDocumentToClass()

Bind a courseware document to the current classroom.

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

Parameter	Type	Description
docId	`string`	Document ID

Returns: Promise<TResult<void>>

Example:

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

boardPauseAudio()

Pause embedded audio on the whiteboard.

Parameter	Type	Description
elementId	`string`	Audio element ID

Returns: void

boardPlayAudio()

Play embedded audio on the whiteboard.

Parameter	Type	Description
elementId	`string`	Audio element ID

Returns: void

boardRefresh()

Refresh the whiteboard rendering.

Returns: void

boardShowVideoControl()

Show or hide the video control bar.

Parameter	Type	Description
show	`boolean`	Whether to show

Returns: void

boardSyncAndReload()

Sync historical data and reload the whiteboard.

Returns: void

cancelUploadCourseware()

Cancel a COS upload task (callable between the onReady callback and upload completion).

Parameter	Type	Description
taskId	`string`	Task ID from `uploadCourseware`'s `onReady` callback

Returns: void

Example:

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

clearBoard()

Clear all content on the current whiteboard page.

Returns: void

deleteBoardFile()

Delete a file from the whiteboard.

Parameter	Type	Description
fileId?	`string`	File ID (defaults to current file)

Returns: void

deleteDocument()

Delete a courseware document (teacher/assistant only).

Removes both server-side record and local list; fires TEvent.DOC_LIST_UPDATED.

Parameter	Type	Description
docId	`string`	Document ID

Returns: Promise<TResult<void>>

Example:

await classroom.deleteDocument('doc_001');

destroyBoard()

Destroy the whiteboard instance (automatically called by the SDK on room leave; usually no manual call needed).

After calling, the whiteboard DOM is cleared and state.boardReady$ becomes false.

Returns: void

enableBoardPermissionChecker()

Enable the whiteboard operation permission checker (only the listed operators can perform the listed actions).

Used for fine-grained control over student whiteboard actions, e.g., only certain students can draw or turn pages after being on stage.

Parameter	Type	Description
actions	`string`[]	Action patterns to enforce (e.g., `'Element::::'`, `'Board::Switch::Step'`)
operators	`string`[]	Allowed operator identifiers (e.g., `[\`operator/${userId}`]`)

Returns: void

Example:

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

getBoard()

Get the Proxy-wrapped raw TEduBoard instance (advanced usage — for calling whiteboard APIs not exposed on the Facade).

⚠️ Use only when native capabilities are truly needed; bypasses SDK type safety. Prefer setBoardToolType / prevBoard etc. for normal flows.

Returns: any

getBoardCurrentBoard()

Get the current whiteboard page ID.

Returns: string

getBoardCurrentFile()

Get the current file ID.

Returns: string

getBoardCurrentPage()

Get the current page number.

Returns: number

getBoardFileInfo()

Get file information by file ID.

Parameter	Type	Description
fileId	`string`	File ID

Returns: any

getBoardFileInfoList()

Get the list of all files on the whiteboard.

Returns: any[]

getBoardScale()

Get the current zoom scale factor.

Returns: number

getBoardScroll()

Get the current scroll position.

Returns: object

getBoardSignalForwardReceivers()

Get the list of signal forwarding receivers.

Returns: string[]

getBoardTotalPages()

Get the total number of pages.

Returns: number

getClassCoursewares()

Get the courseware list for the current classroom.

The SDK calls this once after join; you may refresh manually. The returned CoursewareInfo includes runtime fields (forbid / type).

Parameter	Type	Description
param?
docIds?	`string`[]
keyword?	`string`
limit?	`number`
page?	`number`

Returns: Promise<TResult<GetCoursewareListResult>>

Example:

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

getDocumentInfo()

Get information for a single courseware document.

Parameter	Type	Description
docId	`string`	Document ID

Returns: Promise<TResult<CoursewareInfo>>

Example:

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

getSchoolCoursewares()

Get all coursewares for the current school (courseware library search/management).

For the "courseware library" page; supports filters (permission / owner / keyword). Distinct from class-level getClassCoursewares.

Parameter	Type	Description
param?
keyword?	`string`
limit?	`number`
owner?	`string`
page?	`number`
permission?	`number`[]

Returns: Promise<TResult<GetCoursewareListResult>>

Example:

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

getUploadingFiles()

Get the tracking list of all files currently uploading or transcoding.

Useful for rendering an "upload queue" UI; the UIKit layer can also listen to TEvent.DOC_UPLOAD_PROGRESS for real-time updates.

Returns: UploadTrackInfo[]

Example:

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

getUploadTrack()

Get upload tracking info by document ID.

Parameter	Type	Description
docId	`string`	Document ID

Returns: UploadTrackInfo | undefined

gotoBoard()

Navigate to the specified whiteboard page by ID.

Parameter	Type	Description
boardId	`string`	Whiteboard page ID

Returns: void

gotoBoardPage()

Navigate to a specific step/page number.

Parameter	Type	Description
page	`number`	Page number (0-based)

Returns: void

Example:

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

hasUploadingFiles()

Whether there are any files currently uploading or transcoding (use to block leave actions).

Returns: boolean

Example:

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

initBoard()

Manually initialize the whiteboard (only needed when board.domId was not set in the constructor).

Usually not needed: if { board: { domId: 'xxx' } } was passed at construction, the board initializes automatically on join.

Once ready, state.boardReady$ becomes true and TEvent.BOARD_READY fires.

Parameter	Type	Description
params	`BoardInitParams`	Board init params (`domId` is required)

Returns: Promise<TResult<void>>

Example:

// 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()

Whether the board document audio is currently playing.

Returns: boolean

isBoardVideoPlaying()

Whether the board document video is currently playing.

Returns: boolean

isWebForbidDocType()

Check whether the document type is an unsupported audio/video format on Web (e.g., .avi, .wmv).

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

Parameter	Type	Description
docType	`string`	Document type suffix (lowercase, no dot; e.g., `'avi'`)

Returns: boolean

loadCourseware()

Load a courseware document onto the whiteboard.

Automatically dispatches by courseware type: image / video / audio / transcoded doc / H5. Does not operate the board directly; decoupled via TEvent.DOC_LOAD_COURSEWARE event.

Parameter	Type	Description
docInfo	`CoursewareInfo`	Courseware info object
refresh?	`boolean = false`	Force refresh (reload same courseware on class start)

Returns: void

Example:

typescript

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

nextBoard()

Navigate to the next whiteboard page within the current file.

Returns: void

Example:

classroom.nextBoard();

nextBoardPage()

Go to the next page (alias of nextBoard).

Returns: void

prevBoard()

Navigate to the previous whiteboard page within the current file.

Returns: void

Example:

classroom.prevBoard();

prevBoardPage()

Go to the previous page (alias of prevBoard).

Returns: void

processDoc()

Process courseware info and populate runtime fields (forbid / type).

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

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

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

Parameter	Type	Description
docInfo	`CoursewareInfo`	Courseware info from list APIs

Returns: CoursewareInfo

Example:

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()

Redo the previously undone whiteboard operation.

Returns: void

saveBoardSnapshot()

Save a whiteboard snapshot (cross-platform: Web / Electron / Native Mobile).

Typically obtain base64 via the native getBoard().snapshot() and then call this method to dispatch to the platform-specific save logic.

Parameter	Type	Description
snapId	`string`	Snapshot ID (business-defined unique identifier)
base64Data	`string`	Snapshot base64 data (with `data:image/png;base64,` prefix)
snapName?	`string`	Snapshot file name (optional)
sliceUnit?	`number`	Slice unit size (Native only — for chunked transfer of large images, optional)
dialog?	`boolean`	Whether to show the OS save dialog (Electron desktop, optional)

Returns: Promise<TResult<unknown>>

Example:

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

setBoardBackgroundColor()

Set the whiteboard background color.

Parameter	Type	Description
color	`string`	Background color

Returns: void

setBoardBackgroundImage()

Set the whiteboard background image.

Parameter	Type	Description
url	`string`	Image URL
mode?	`BoardFitMode`	Fit mode

Returns: void

setBoardContentFitMode()

Set the content fit mode.

Parameter	Type	Description
mode	`BoardFitMode`	Fit mode

Returns: void

setBoardDataSyncEnable()

Enable or disable whiteboard data synchronization.

Parameter	Type	Description
enable	`boolean`	Whether to enable

Returns: void

setBoardDrawEnable()

Enable or disable free-draw mode (when disabled, pen-like tools do not respond to clicks).

Parameter	Type	Description
enable	`boolean`	Whether to enable

Returns: void

setBoardPPTVideoSyncMaster()

Set this client as the PPT video sync master.

Parameter	Type	Description
enable	`boolean`	Whether to enable

Returns: void

setBoardScale()

Set the zoom scale factor.

Parameter	Type	Description
scale	`number`	Zoom scale factor

Returns: void

setBoardSignalForwardReceivers()

Set the list of signal forwarding receivers.

Parameter	Type	Description
userIds	`string`[]	Receiver user ID list

Returns: void

setBoardSpeakerDevice()

Set the speaker device for whiteboard audio.

Parameter	Type	Description
deviceLabel	`string`	Device label

Returns: void

setBoardSpeakerDeviceForPPT()

Set the speaker device for PPT audio.

Parameter	Type	Description
deviceLabel	`string`	Device label

Returns: void

setBoardToolType()

Switch the whiteboard tool type (pen / eraser / text / laser, etc.).

Parameter	Type	Description
type	`BoardToolType`	Tool type. 常用值 / common values:

Returns: void

Example:

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

setBrushColor()

Set the brush color.

Parameter	Type	Description
color	`string`	Color value (e.g. `'#FF0000'`)

Returns: void

Example:

classroom.setBrushColor('#1890ff');

setBrushThin()

Set the brush thickness.

Actual pixels = thin × board height / 10000; recommended range 50–300.

Parameter	Type	Description
thin	`number`	Thickness value in board-coordinate units

Returns: void

setCursorIcon()

Set a custom cursor icon for a specific tool type.

Parameter	Type	Description
toolType	`BoardToolType`	Tool type
icon
cursor	`string`
offsetX	`number`
offsetY	`number`
url	`string`

Returns: void

setHandwritingEnable()

Enable or disable handwriting (pen pressure) effect.

Parameter	Type	Description
enable	`boolean`	Whether to enable

Returns: void

setMouseToolBehavior()

Set the mouse tool behavior.

Parameter	Type	Description
behavior	`MouseToolBehavior`	Mouse behavior mode

Returns: void

setScaleAnchor()

Set the zoom anchor point.

Parameter	Type	Description
x	`number`	Anchor X coordinate
y	`number`	Anchor Y coordinate

Returns: void

setSystemCursorEnable()

Enable or disable the system cursor.

Parameter	Type	Description
enable	`boolean`	Whether to enable

Returns: void

setTextColor()

Set the text color.

Parameter	Type	Description
color	`string`	Color value

Returns: void

setTextSize()

Set the text font size.

Parameter	Type	Description
size	`number`	Font size

Returns: void

setTextStyle()

Set the text style.

Parameter	Type	Description
style	`0 \| 1 \| 2 \| 3`	0=常规 1=粗体 2=斜体 3=粗斜体 / 0=normal 1=bold 2=italic 3=bold-italic

Returns: void

setToolTypeTitle()

Set tool type title (display the operator's nickname).

Parameter	Type	Description
title	`string`	Title text
config
color	`string`
displaySelf	`boolean`
position	`number`
size	`number`
style	`number`
toolType	`BoardToolType`	Tool type

Returns: void

switchBoardFile()

Switch to the specified file.

Parameter	Type	Description
fileId	`string`	File ID

Returns: void

unbindDocumentFromClass()

Unbind a courseware document from the current classroom (does NOT delete the courseware itself; only removes from this class).

Parameter	Type	Description
docId	`string`	Document ID

Returns: Promise<TResult<void>>

undoBoard()

Undo the last whiteboard operation.

Returns: void

uploadCourseware()

Upload courseware to COS and create a document record (full workflow).

Progress is reported via onReady / onProgress callbacks (axios-style). The final result is returned via Promise<TResult>.

Parameter	Type	Description
param	`UploadCoursewareParam`	Upload parameters

Returns: Promise<TResult<UploadCoursewareResult>>

Example:

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()

Validate the format and size of a file before upload.

Call after file selection and before upload to provide quick error feedback. No network request needed; returns synchronously.

Parameter	Type	Description
file	`File`	The file to validate

Returns: TResult<void>

Whiteboard & Courseware API ​

API Reference ​

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() ​

Whiteboard & Courseware API

API Reference

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()