Web · Pano开发者中心

本文结合部分 SDK API ，介绍如何快速接入白板功能。

如需查看完整 SDK API 列表，请点击左侧导航 SDK API - Web SDK - RtcWhiteboard 部分。

导入SDK

共有 3 种方式来导入白板 SDK。

通过下载中心下载完整版 Web SDK 的 JS 文件（含音视频和白板功能），并通过 <script> 标签导入。
通过 PanoRtc.RtcEngine、PanoRtc.RtcWhiteboard、PanoRtc.Constants 获取相应的模块。

SDK 需要挂载 DOM，请将导入 SDK 的 <script> 标签添加到 <body> 中，不能添加到 <head> 中。
执行 npm install @pano.video/panortc 命令获取 Web 完整版 SDK 包（含音视频和白板功能）。
通过代码 import { RtcEngine, RtcWhiteboard, Constants } from '@pano.video/panortc' 导入 SDK 并获取相应的模块。
- 某些工具(例如 VSCode 默认的 powershell)需要在包名前后添加引号：
  npm install '@pano.video/panortc'，下同。
- 如果使用 Yarn，请将 npm install 更换为 yarn add，下同。
执行 npm install @pano.video/panorts 命令获取 Web RTS SDK 包（含白板功能，不含音视频功能）。
通过代码 import { RtcWhiteboard } from '@pano.video/panorts' 导入 SDK 并获取相应的模块。

下文示例代码按照 PanoRtc.RtcEngine、PanoRtc.RtcWhiteboard、PanoRtc.Constants 的方式使用。如果你使用 RtcEngine、RtcWhiteboard、Constants 的方式，请注意替换。

获取白板实例与加入白板频道

有 2 种方式来获取白板实例并加入白板频道。

方式1：先通过 RtcEngine 实例加入白板频道，再获取白板实例
- 这种方式适用于通过 <script> 标签导入 JS 文件，或者通过 npm 获取完整版 SDK 的情况。
方式2：先初始化白板实例，再加入白板频道
- 这种方式适用于全部 3 种导入白板SDK的情况。

两种方式使用其中一种即可，不要混用。下面分别介绍这两种方式。

通过RtcEngine实例加入白板频道再获取白板实例

相应处理逻辑为：

先通过 new PanoRtc.RtcEngine(appId) 初始化 RtcEngine 实例。
再通过 RtcEngine 实例的 joinChannel 方法加入频道。joinChannel 的参数 optionalConfig - joinChannelType 需要配置为：
- PanoRtc.Constants.whiteboardOnly (只加入白板频道)，或者：
- PanoRtc.Constants.mediaAndWhiteboard (同时加入音视频和白板频道)
当加入频道成功收到 PanoRtc.RtcEngine.Events.whiteboardAvailable 事件时，调用 RtcEngine 实例的 getWhiteboard 方法获取白板实例。
随后即可调用 RtcWhiteboard 实例的 open 方法打开白板。

初始化白板实例再加入白板频道

相应处理逻辑为：

先通过 new PanoRtc.RtcWhiteboard() 初始化 RtcWhiteboard 实例。
通过 RtcWhiteboard 实例的 joinChannel 方法加入白板频道。
在 joinChannel 方法的 onSuccess 回调中即可调用 RtcWhiteboard 实例的 open 方法打开白板。

私有化环境特殊配置

如果是私有化环境并且通过 @pano.video/panorts 导入白板 SDK 的方式，请在加入白板频道之前，增加下列配置(公有云无需此配置)：

import { RtsService } from '@pano.video/panorts'
RtsService.setServer('https://server.domain') // server.domain 为示意，请按实际情况配置

注册通知

通过 RtcWhiteboard 实例的 on 方法注册回调通知，通过 off 或 removeAllListeners 方法移除通知。

// 以下为部分通知示例
// 白板开启状态变化
rtcWhiteboard.on(PanoRtc.RtcWhiteboard.Events.openStateChanged, data => { ... });
// 白板就绪状态变化
rtcWhiteboard.on(PanoRtc.RtcWhiteboard.Events.readyStateChanged, data => { ... });
// 白板内容更新
rtcWhiteboard.on(PanoRtc.RtcWhiteboard.Events.whiteboardContentUpdate, data => { ... });
// 当前用户角色类型变化
rtcWhiteboard.on(PanoRtc.RtcWhiteboard.Events.userRoleTypeChanged, data => { ... }); 

// 移除通知
// 方式一：使用 off 方法，格式为：off(event, cb)，其中 cb 表示特定的单个回调函数
// [注意] 通过匿名函数或箭头函数注册的通知函数，无法使用 off 方法移除，请使用下文 removeAllListeners 方法
rtcWhiteboard.off(PanoRtc.RtcWhiteboard.Events.docCreated, yourCallbackFunction);
// 方式二：使用 removeAllListeners 方法移除指定通知类型的所有监听器，格式为：removeAllListeners(event)
rtcWhiteboard.removeAllListeners(PanoRtc.RtcWhiteboard.Events.openStateChanged);
// 方式三：使用 removeAllListeners 方法移除所有的监听器，格式为：removeAllListeners()
rtcWhiteboard.removeAllListeners();

请按需处理各种事件通知，完整的通知列表，请查看 RtcWhiteboard EVENTS。

工具条

SDK 内部已实现白板工具绘制和数据同步，但是由于不同的开发者有不同的 UI 设计，因此 SDK 不提供涉及 UI 交互的白板工具条。
请开发者自行设计白板工具条，来结合调用 SDK 接口以执行相应的白板操作。
我们也提供包含工具条的示例代码供开发者参考。

工具条挂载点

SDK 会自动生成一个 DOM 节点用于挂载外部工具条。此挂载点不是必须的，开发者可以将工具条放置到任何自定义位置。
可以通过 RtcWhiteboard 实例的 toolsWrapper 属性来获取此挂载点。

console.info(rtcWhiteboard.toolsWrapper);

全局属性

白板颜色

背景色

通过 RtcWhiteboard 实例的 backgroundColor 属性来获取和设置白板背景色（仅支持 rgba 格式）。

console.info(rtcWhiteboard.backgroundColor);
rtcWhiteboard.backgroundColor = 'rgba(255, 255, 255, 1)';

白板背景色仅在本地显示，不会同步给其他用户。因此每位用户的白板背景色可以不同。

文字、线条和边框的颜色

通过 RtcWhiteboard 实例的 strokeStyle 属性来获取和设置文字、线条和边框的颜色（仅支持 rgba 格式）。默认值为：'rgba(33, 212, 183, 1)'。

console.info(rtcWhiteboard.strokeStyle);
rtcWhiteboard.strokeStyle = 'rgba(255, 0, 0, 1)';

设置该属性后，仅对新添加的文字、线条和边框生效。如果需要更新已选择的文字、线条和边框的颜色，请使用 setSelectedShapeStyle 方法。

rtcWhiteboard.setSelectedShapeStyle({strokeStyle: 'rgba(33, 212, 183, 1)'});

适用于文字工具的全局属性

设置 RtcWhiteboard 实例的以下全局属性后，仅对新绘制的图形生效。
如果需要更新已选择的图形，请调用相应的设置方法 setSelectedShapeFontStyle。
详请参考 RtcWhiteboard Properties。

fontSize：表示字体大小，number 类型，默认值为：14。

rtcWhiteboard.fontSize = 14;

bold：表示是否粗体，boolean 类型，默认值为：false。

rtcWhiteboard.bold = true;

italic：表示是否斜体，boolean 类型，默认值为：false。

rtcWhiteboard.italic = true;

适用于图形工具的全局属性

设置 RtcWhiteboard 实例的以下全局属性后，仅对新绘制的图形生效。

lineWidth：表示线条和边框的宽度，number 类型，默认值为：3。

rtcWhiteboard.lineWidth = 3;

fillStyle：表示封闭图形（如椭圆和矩形）的填充颜色，string 类型（仅支持 rgba 格式），默认值为：'rgba(112, 124, 138, 1)'。

rtcWhiteboard.fillStyle = 'rgba(255, 0, 0, 1)';

fillType：表示封闭图形填充方式，string 类型，默认值为 'none' 表示不填充，可配置为 'color' 表示填充颜色。
如果配置为填充颜色，则不再显示边框颜色。

rtcWhiteboard.fillType = 'color';

dashed: 表示新绘制的图形是否是虚线图形。

rtcWhiteboard.dashed = true; // 默认值 false

其他全局属性

selectedDrawnShapeTypes: 表示哪些图形在绘制后自动选中
selectedShape：表示当前被选中的图形
scale：表示当前白板视图的缩放比例
activeDoc：表示当前激活的文档信息
activeDocId：表示当前激活的文档ID
thumbnails: 表示当前白板文档的缩略图
role：表示当前用户的角色
isAdmin：表示当前用户是否是管理员

console.info(rtcWhiteboard.selectedDrawnShapeTypes);
console.info(rtcWhiteboard.selectedShape);
console.info(rtcWhiteboard.scale);
console.info(rtcWhiteboard.activeDoc);
console.info(rtcWhiteboard.activeDocId);
console.info(rtcWhiteboard.role);
console.info(rtcWhiteboard.isAdmin);

常用工具

工具类型

设置工具类型

通过 RtcWhiteboard 实例的 setToolType 方法设置工具类型。

rtcWhiteboard.setToolType(PanoRtc.Constants.ShapeType.Pen); // 笔（自由绘制）
rtcWhiteboard.setToolType(PanoRtc.Constants.ShapeType.LaserPointer); // 激光笔
rtcWhiteboard.setToolType(PanoRtc.Constants.ShapeType.Line); // 直线工具
rtcWhiteboard.setToolType(PanoRtc.Constants.ShapeType.Arrow); // 箭头工具
rtcWhiteboard.setToolType(PanoRtc.Constants.ShapeType.Rect); // 矩形工具，按住 Shift 可以绘制正方形
rtcWhiteboard.setToolType(PanoRtc.Constants.ShapeType.Square); // 正方形工具
rtcWhiteboard.setToolType(PanoRtc.Constants.ShapeType.Ellipse); // 椭圆工具，按住 Shift 可以绘制圆形
rtcWhiteboard.setToolType(PanoRtc.Constants.ShapeType.Circle); // 圆形工具
rtcWhiteboard.setToolType(PanoRtc.Constants.ShapeType.Text); // 文本工具
// 使用图章工具前，请先 addStamp(添加图章)、setStamp(设置图章，切换不同图章时需重新设置图章)
rtcWhiteboard.setToolType(PanoRtc.Constants.ShapeType.Stamp); // 图章工具
rtcWhiteboard.setToolType(PanoRtc.Constants.ShapeType.Select); // 选择工具，可以框选多个图形
// 拖拽工具，可以鼠标左键或单指拖动画布(白板未固定宽高的情况下)
rtcWhiteboard.setToolType(PanoRtc.Constants.ShapeType.Drag);
rtcWhiteboard.setToolType(PanoRtc.Constants.ShapeType.Delete); // 删除选中的图形
// 从 2.3.0 版本开始，Eraser 工具更改为 Brush 工具
// 刷子工具，可以结合全局属性 lineWidth 控制其宽度
rtcWhiteboard.setToolType(PanoRtc.Constants.ShapeType.Brush);
rtcWhiteboard.setToolType(PanoRtc.Constants.ShapeType.Click); // 课件交互（可以操作白板底部的课件）

请在加入白板频道成功后再进行白板操作。

获取工具类型

通过 RtcWhiteboard 实例的 getToolType 方法获取当前工具类型。

rtcWhiteboard.getToolType();

设置工具样式

文本样式

通过 RtcWhiteboard 实例的 setSelectedShapeFontStyle 方法设置当前所选文本的字体样式。
支持 3 个可选参数：fontSize(字体大小)、bold(是否加粗)、italic(是否斜体)。

rtcWhiteboard.setSelectedShapeFontStyle({fontSize: 12, bold: true, italic: true});

形状样式

通过 RtcWhiteboard 实例的 setSelectedShapeStyle 方法设置当前所选形状的样式。
支持 4 个可选参数：

lineWidth，线条和边框的宽度，number 类型
strokeStyle，线条和边框的颜色，string 类型，仅支持 rgba 格式，如 'rgba(33, 212, 183, 1)'
fillStyle，封闭图形（如椭圆和矩形）的填充颜色，string 类型，仅支持 rgba 格式，如 'rgba(112, 124, 138, 1)'
fillType，封闭图形填充方式（'none' 不填充，'color' 填充颜色，如果设置填充颜色，则不再显示边框颜色。）

rtcWhiteboard.setSelectedShapeStyle({
  lineWidth: 10,
  strokeStyle: 'rgba(33, 212, 183, 1)',
  fillStyle: 'rgba(112, 124, 138, 1)',
  fillType: 'color'
});

撤销与重做

通过 RtcWhiteboard 实例的 undo 方法撤消上一次操作，redo 方法重做上一次被撤销的操作。

rtcWhiteboard.undo();

只能对自己的操作记录进行撤销与重做。

另请关注通知：historyChanged。

图片操作

设置背景图片缩放模式

通过 RtcWhiteboard 实例的 setBackgroundImageScalingMode 方法设置背景图片缩放模式。

// WBImageScalingMode 可选值：AutoFill/FillHeight/FillWidth/Fit
rtcWhiteboard.setBackgroundImageScalingMode(PanoRtc.Constants.WBImageScalingMode.AutoFill);

设置背景图片

通过 RtcWhiteboard 实例的 setBackgroundImage(url: string) 方法设置背景图片。

rtcWhiteboard.setBackgroundImage('https://domain/path/filename.jpg');

导入背景图片列表

通过 RtcWhiteboard 实例的 addBackgroundImages(urls: string[], addToCurrentDoc: boolean, docName: string) 方法导入背景图片列表。

addToCurrentDoc 参数表示是否添加到当前文档中。
(版本 1.2.0+)当 addToCurrentDoc 设置为 false 时，可以通过 docName 参数指定新文档名称（如果不指定，则 SDK 自动生成文档名称）。

rtcWhiteboard.addBackgroundImages(['https://domain/path/filename1.jpg', 'https://domain/path/filename2.jpg', ...], false, 'NewDoc');

上传图片

通过 RtcWhiteboard 实例的 uploadImage(callback: function, setAsBackground: boolean) 方法上传图片，调用接口会自动打开文件选择框。
setAsBackground 为 true 时上传为背景图，false 时上传为图片元素（背景图不支持拖拽，图片元素支持拖拽）。

rtcWhiteboard.uploadImage(obj => {
  console.info(obj)
}, true);

如需将图片以 URL 格式上传，请使用 RtcWhiteboard 实例的 addImageShape(url: string): Promise‹QResult› 方法。

rtcWhiteboard.addImageShape('https://domain/path/filename.jpg')
.then(obj => console.info(obj))
.catch(error => console.info(error));

多媒体操作

Admin 用户操作音视频（包括动态课件中嵌入的音视频，以及通过下列方法上传到白板中的音视频）时，播放状态（播放、暂停、拖动进度条）会自动同步给其他用户。

上传音频

通过 RtcWhiteboard 实例的 uploadAudio 方法上传音频文件到当前页面(支持.mp3、.ogg格式)。

调用此方法后，会自动弹出文件选择框。
可以通过选择工具选中控件，进行缩放和移动。
可以通过删除工具，或者按 Delete 键删除生成的音频控件。

rtcWhiteboard.uploadAudio(obj => {
  // obj 中返回 code, state, message或uploadProgress
})

如需将音频以 URL 格式上传，请使用 RtcWhiteboard 实例的 addAudioShape(url: string): Promise‹QResult› 方法。

rtcWhiteboard.addAudioShape('https://domain/path/filename.mp3')
.then(obj => console.info(obj))
.catch(error => console.info(error));

上传视频

通过 RtcWhiteboard 实例的 uploadVideo 方法上传视频文件到当前页面(支持.mp4、.ogg、.webm格式)。

调用此方法后，会自动弹出文件选择框。
可以通过选择工具选中控件，进行缩放和移动。
可以通过删除工具，或者按 Delete 键删除生成的视频控件。

rtcWhiteboard.uploadVideo(obj => {
  // obj 中返回 code, state, message或uploadProgress
})

如需将视频以 URL 格式上传，请使用 RtcWhiteboard 实例的 addVideoShape(url: string): Promise‹QResult› 方法。

rtcWhiteboard.addVideoShape('https://domain/path/filename.mp4')
.then(obj => console.info(obj))
.catch(error => console.info(error));

设置用户角色

通过 RtcWhiteboard 实例的 setRoleType(roleType: WBRoleType) 方法设置自己的角色(这是异步操作，请注意监听 userRoleTypeChanged 通知)。
角色的区别：

定义	类型	权限	备注
`Admin`	管理员	可以使用工具，可以操作所有用户的内容	一个频道只能有一位管理员
`Attendee`	普通用户	可以使用工具，只能操作自己的内容	默认角色
`Viewer`	仅观看的用户	不能使用工具，只能缩放和移动

rtcWhiteboard.setRoleType(PanoRtc.Constants.WBRoleType.Admin); // 设置自己为管理员

画板操作

缩放和移动

缩放

通过 RtcWhiteboard 实例的 setScale 方法设置当前画板的缩放比例（0.1 - 5，number 类型）。
通过 setScaleOfAll 方法设置所有文档页面的缩放比例。

rtcWhiteboard.setScale(1.5);

移动

通过 RtcWhiteboard 实例的 setTranslate(x: number, y: number, smooth: boolean, duration: number) 方法移动画板。

每次调用，都是基于原始位置进行移动，而不是基于当前位置进行移动。
smooth 表示是否平滑移动，duration 表示平滑移动时间（单位毫秒）

通过 setTranslateOfAll 方法设置所有文档页面的偏移。

rtcWhiteboard.setTranslate(100, 100, true, 1000);

获取位移

通过 RtcWhiteboard 实例的 getTranslate 方法获取画板的位移。

rtcWhiteboard.getTranslate(); // 例如：{x: 100, y: 100}

居中

通过 RtcWhiteboard 实例的 center 方法将当前文档或动态课件一键居中，或者将默认白板恢复初始大小。

rtcWhiteboard.center();

禁用鼠标和手势

通过 RtcWhiteboard 实例的 disableScaleAndMove 方法禁止通过鼠标和手势缩放和移动画板（禁止后仍然可以通过接口操作），enableScaleAndMove 方法允许操作。

rtcWhiteboard.disableScaleAndMove();

禁用滚轮缩放

通过 RtcWhiteboard 实例的 disableWheelScale 方法禁止通过滚轮缩放画板，enableWheelScale 方法允许操作。

rtcWhiteboard.disableWheelScale();

同步光标位置

通过 RtcWhiteboard 实例的 cursorSyncType 属性设置光标同步类型。

rtcWhiteboard.cursorSyncType = 'write'; // 仅在鼠标按下做绘制动作时同步光标位置

通过 RtcWhiteboard 实例的 enableCursorSync 方法开启光标位置同步(展示其他用户的光标位置及其用户名)，通过 disableCursorSync 方法关闭光标位置同步。

rtcWhiteboard.enableCursorSync();

更新画板尺寸

通过 RtcWhiteboard 实例的 updateCanvasSize 方法更新画板尺寸（当白板容器尺寸发生变化时调用）。
版本 1.2.0+ 支持以下两个属性：

autoAdjust：是否自动调整画布内容（默认 true）
keepScale：自动调整画布内容时是否保持缩放比例（默认 true）

rtcWhiteboard.updateCanvasSize(true, true);

获取可见区域坐标

通过 RtcWhiteboard 实例的 getViewportPosition 方法获取当前画板可见区域的坐标。

rtcWhiteboard.getViewportPosition();

隐藏画板内容

通过 RtcWhiteboard 实例的 hideWhiteboard 方法隐藏画板内容（所有的形状和背景图片都会隐藏, 但是仍可和课件交互），showWhiteboard 方法显示画板内容。

(版本 1.2.0+)参数 hideBackgroundImg 表示是否隐藏背景图。

rtcWhiteboard.hideWhiteboard(false);

清除画板内容

通过 RtcWhiteboard 实例的 clearContents(curPage: boolean, type: WBClearType) 方法清除所有用户在画板上的内容（需要管理员权限）。

curPage 参数表示是否仅限清除当前页面。
type 参数表示清除的内容类型。
- 为 All 时清除所有用户的所有内容
- 为 DRAWS 时清除所有用户添加的图形
- 为 BACKGROUND_IMAGE 时清除所有用户添加的背景图片

rtcWhiteboard.clearContents(false, PanoRtc.Constants.WBClearType.All); // 管理员清除所有页面的所有内容

通过 RtcWhiteboard 实例的 clearUserContents(userId: string, curPage: boolean, clearType: WBClearType) 方法清除特定用户的画板内容。

需要管理员权限才能清除其他用户添加的内容。
curPage 参数表示是否仅限清除当前页面。
type 参数表示清除的内容类型。
- 为 All 时清除特定用户的所有内容
- 为 DRAWS 时清除特定用户添加的图形
- 为 BACKGROUND_IMAGE 时清除特定用户添加的背景图片

// 管理员清除特定用户添加的图形
rtcWhiteboard.clearUserContents('10000', false, PanoRtc.Constants.WBClearType.DRAWS);

关闭/离开白板

通过 RtcWhiteboard 实例的 close 方法关闭白板（仅关闭当前用户的白板 UI）。可以通过 open 方法重新打开。

rtcWhiteboard.close();

通过 RtcWhiteboard 实例的 leave 方法离开白板关闭当前用户的白板 UI，并且断开白板服务）。

rtcWhiteboard.leave();

高级功能

请点此查看 Web 白板的高级功能介绍。

SDK API 指南

更多白板 SDK 接口，请点此查看 API 列表。

示例代码

为方便开发者了解丰富的接口使用方式，我们还提供示例代码，请参考以下开源项目：

PanoWhiteboardDemo(仅白板)：GitHub、Gitee
PanoVideoDemo(白板和音视频)：GitHub、Gitee