腾讯云实时互动-教育版

简体中文

English

简体中文

English

Appearance

白板指南 ​

本文介绍互动白板相关功能的使用方法，包括白板初始化、工具栏操作、翻页缩放和课件管理。

白板初始化 ​

自动初始化（推荐） ​

在构造 SDK 实例时传入 board.domId，进房时自动初始化白板：

typescript
const classroom = new TencentClassroom({
  board: {
    domId: 'board-container',  // 白板挂载容器 DOM ID
    ratio: '16:9',             // 白板比例
    style: {
      brushColor: '#ff0000',
      brushThin: 100,
    },
  },
});

手动初始化 ​

如果构造时未配置 board.domId，可在进房后手动初始化：

typescript
const result = await classroom.initBoard({
  domId: 'board-container',
  ratio: '16:9',
});
if (!result.ok) {
  console.error('白板初始化失败:', result.message);
}

白板就绪状态 ​

typescript
// 订阅白板就绪状态
classroom.state.boardReady$.subscribe(ready => {
  if (ready) {
    console.log('白板已就绪，可以操作');
  }
});

// 监听白板就绪事件
classroom.on(TEvent.BOARD_READY, () => {
  console.log('白板历史数据同步完成');
});

// 监听白板错误
classroom.on(TEvent.BOARD_ERROR, ({ code, message }) => {
  console.error(`白板错误 [${code}]:`, message);
});

工具栏操作 ​

设置白板工具 ​

typescript
import { BoardToolType } from '@tencent-classroom/sdk';

// 切换工具
classroom.setBoardToolType(BoardToolType.Pen);        // 画笔
classroom.setBoardToolType(BoardToolType.Mouse);      // 选择
classroom.setBoardToolType(BoardToolType.Text);       // 文本
classroom.setBoardToolType(BoardToolType.Eraser);     // 橡皮擦
classroom.setBoardToolType(BoardToolType.Laser);      // 激光笔
classroom.setBoardToolType(BoardToolType.Line);       // 直线
classroom.setBoardToolType(BoardToolType.Rect);       // 矩形
classroom.setBoardToolType(BoardToolType.ZoomDrag);   // 缩放拖拽

画笔配置 ​

typescript
// 设置画笔颜色
classroom.setBrushColor('#ff0000');

// 设置画笔粗细
classroom.setBrushThin(100);

// 启用/禁用笔锋
classroom.setHandwritingEnable(true);

文本配置 ​

typescript
// 文本样式（0=普通, 1=粗体, 2=斜体, 3=粗斜体）
classroom.setTextStyle(1);

// 文本大小
classroom.setTextSize(24);

// 文本颜色
classroom.setTextColor('#333333');

涂鸦权限 ​

typescript
// 启用/禁用涂鸦
classroom.setBoardDrawEnable(true);
classroom.setBoardDrawEnable(false);

撤销 / 重做 / 清空 ​

typescript
classroom.undoBoard();   // 撤销
classroom.redoBoard();   // 重做
classroom.clearBoard();  // 清空当前页

翻页与缩放 ​

翻页 ​

typescript
// 上一页 / 下一页
classroom.prevBoard();
classroom.nextBoard();

// 跳转到指定页码
classroom.gotoBoardPage(3);

// 获取当前页码和总页数
const currentPage = classroom.getBoardCurrentPage();
const totalPages = classroom.getBoardTotalPages();
console.log(`第 ${currentPage} / ${totalPages} 页`);

缩放 ​

typescript
// 获取当前缩放系数
const scale = classroom.getBoardScale();

// 设置缩放系数
classroom.setBoardScale(150); // 150%

// 设置缩放锚点
classroom.setScaleAnchor(0.5, 0.5); // 中心缩放

内容适配 ​

typescript
import { BoardFitMode } from '@tencent-classroom/sdk';

classroom.setBoardContentFitMode(BoardFitMode.Contain);

背景设置 ​

typescript
// 设置白板背景色
classroom.setBoardBackgroundColor('#f5f5f5');

// 设置白板背景图
classroom.setBoardBackgroundImage('https://example.com/bg.png');

课件管理 ​

上传课件 ​

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

// 上传课件
const result = await classroom.uploadCourseware({
  file: selectedFile,
  schoolId: 100,
  permission: CoursewarePermission.Private,
  docType: 'pptx',
  onReady: (taskId) => {
    console.log('上传任务 ID:', taskId);
  },
  onProgress: (loaded, total, speed, percent) => {
    console.log(`上传进度: ${Math.round(percent * 100)}%`);
  },
});

if (!result.ok) {
  console.error('上传失败:', result.message);
  return;
}
console.log('上传成功，docId:', result.data.docId);

监听上传/转码进度 ​

typescript
classroom.on(TEvent.DOC_UPLOAD_PROGRESS, (progress) => {
  switch (progress.status) {
    case UploadTrackStatus.Uploading:
      setUploadBar(progress.filePercent);
      break;
    case UploadTrackStatus.Transcoding:
      setTranscodeBar(progress.transcodeProgress);
      break;
    case UploadTrackStatus.Completed:
      showToast('课件准备就绪');
      break;
    case UploadTrackStatus.Failed:
      showError('课件处理失败');
      break;
  }
});

加载课件到白板 ​

typescript
// 加载课件到白板
classroom.loadCourseware(docInfo);

// 强制重新加载（开课时刷新）
classroom.loadCourseware(docInfo, true);

课件列表管理 ​

typescript
// 获取当前课堂课件列表（schoolId/classId 由 SDK 内部自动填充）
const listResult = await classroom.getClassCoursewares({
  page: 1,
  limit: 20,
});
if (listResult.ok) {
  console.log('课件列表:', listResult.data.documents);
}

// 获取学校课件库（搜索/管理场景）
const schoolDocs = await classroom.getSchoolCoursewares({
  page: 1,
  limit: 20,
  permission: [0, 1], // [0]=私有 [1]=公共
  keyword: '第一章',
});

// 删除课件
await classroom.deleteDocument('doc_001');

// 绑定课件到课堂
await classroom.bindDocumentToClass('doc_001');

// 取消绑定
await classroom.unbindDocumentFromClass('doc_001');

文件格式校验 ​

typescript
// 上传前校验文件格式和大小（同步，无需网络请求）
const validateResult = classroom.validateUploadFile(file);
if (!validateResult.ok) {
  showToast(validateResult.message); // "不支持的文件格式" 等
  return;
}

白板文件操作 ​

typescript
// 添加转码文件
const fileId = classroom.addBoardTranscodeFile(transcodeResult);

// 添加图片文件
classroom.addBoardImagesFile(['url1.png', 'url2.png'], '图片合集');

// 添加视频文件
classroom.addBoardVideoFile('https://example.com/video.mp4', '教学视频');

// 切换文件
classroom.switchBoardFile(fileId);

// 删除文件
classroom.deleteBoardFile(fileId);

// 获取文件列表
const fileList = classroom.getBoardFileInfoList();

白板权限控制 ​

各角色白板能力 ​

能力老师助教学生巡课
涂鸦绘画✅✅需授权❌
工具栏操作✅✅需授权❌
翻页✅✅需授权❌
加载课件✅✅❌❌
查看白板✅✅✅✅
H5 PPT 交互（点击视频/弹窗）✅✅✅✅
  • 老师/助教：进房后默认拥有完整白板权限
  • 学生：默认无白板权限（只能查看），需由老师动态授权后才能涂鸦、使用工具
  • 巡课：只读查看，不可操作

权限检查方法 ​

typescript
// 是否拥有白板权限（涂鸦、工具、翻页等全部白板操作能力）
classroom.canOperateBoard(); // => boolean

// 订阅白板权限变化
classroom.state.boardPermission$.subscribe((hasPermission) => {
  if (hasPermission) {
    showBoardToolbar();  // 展示工具栏
  } else {
    hideBoardToolbar();  // 隐藏工具栏
  }
});

统一的白板权限

白板权限涵盖涂鸦（draw）、工具切换（tool）、翻页（turnPage）等所有白板操作能力。

动态授权 / 收回白板权限 ​

老师/助教可通过 memberAction 为学生动态授予或收回白板权限：

typescript
import { MemberActionType } from '@tencent-classroom/sdk';

// 老师：授予学生白板权限
await classroom.memberAction({
  userId: 'student_001',
  action: MemberActionType.Board_Enable,
});

// 老师：收回学生白板权限
await classroom.memberAction({
  userId: 'student_001',
  action: MemberActionType.Board_Disable,
});

授权后学生端 boardPermission$ 自动变为 true，SDK 内部自动完成：

  • setDrawEnable(true) — 开启涂鸦输入
  • setDataSyncEnable(true) — 操作同步到其他人
  • 工具自动切换为画笔

收回权限时自动完成：

  • setDrawEnable(false) — 关闭涂鸦输入
  • setDataSyncEnable(false) — 操作不同步
  • 工具自动切换为 MOUSE（仍可与 H5 PPT 交互）

权限与课堂状态的联动 ​

  • 未开课时：无论权限如何，白板操作不同步（setDataSyncEnable(false)），可用于课前备课涂鸦练习
  • 开课时：按权限控制同步。开课瞬间 SDK 自动清除课前本地操作

更多白板事件 ​

除了 BOARD_READY 和 BOARD_ERROR 外，SDK 还提供以下白板相关事件：

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

// 白板 DOM 已挂载，历史数据同步中（此时白板可见但还不可操作）
classroom.on(TEvent.BOARD_INIT, () => {
  showBoardLoading();
});

// 白板签名/鉴权错误（不触发重试）
classroom.on(TEvent.BOARD_SIG_ERROR, ({ code, message }) => {
  console.error('白板鉴权错误:', code, message);
});

// 白板警告（如页数超限 code=10）
classroom.on(TEvent.BOARD_WARN, ({ code, message }) => {
  console.warn(`白板警告 [${code}]:`, message);
});

// 转码课件加载到白板成功
classroom.on(TEvent.BOARD_ADD_TRANSCODE_FILE, (fileId) => {
  console.log('课件已加载到白板，fileId:', fileId);
});

// H5 PPT 状态变化
classroom.on(TEvent.BOARD_H5PPT_STATUS_CHANGED, (status, data) => {
  console.log('H5PPT 状态变化:', status);
});

// 白板内嵌视频状态变化
classroom.on(TEvent.BOARD_VIDEO_STATUS_CHANGED, (data) => {
  console.log('白板视频状态:', data);
});

// H5PPT 媒体播放状态（老师端用于视频同步）
classroom.on(TEvent.BOARD_MEDIA_STATUS_CHANGED, (fileId, mediaId, status, currentTime) => {
  // 老师端同步播放进度给学生端
});

// 白板图片加载状态（1=错误 2=超时）
classroom.on(TEvent.BOARD_IMAGE_STATUS_CHANGED, (status, data) => {
  if (status === 1) console.error('白板图片加载失败');
});

// 课件列表更新
classroom.on(TEvent.DOC_LIST_UPDATED, ({ documents }) => {
  refreshCoursewarePanel(documents);
});

// 课件加载到白板
classroom.on(TEvent.DOC_LOAD_COURSEWARE, ({ type, docInfo }) => {
  console.log('课件加载中:', docInfo.name);
});

相关 API ​

Copyright © 2013-2026 Tencent Cloud. All Rights Reserved.

腾讯云版权所有 京ICP备11018762号-1073