Web

本文结合部分 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 PanoRtc from '@pano.video/panortc' 导入完整版SDK。
    通过代码 const { RtcEngine, RtcWhiteboard, Constants } = PanoRtc 解构赋值获取相应的模块。

    如果不解构赋值，也可以换用 PanoRtc.RtcEngine、PanoRtc.RtcWhiteboard、PanoRtc.Constants 获取相应的模块。

  • 通过命令行工具执行 npm install @pano.video/whiteboard 命令获取白板 Web SDK 包（仅白板功能）。
    通过代码 import { RtcWhiteboard, Constants } from '@pano.video/whiteboard' 导入白板SDK并获取相应的模块。

下文示例代码按照 PanoRtc.RtcEngine、PanoRtc.RtcWhiteboard、PanoRtc.Constants 的方式使用。

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

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

  • 方式1：先通过 RtcEngine 实例加入白板频道，再获取白板实例
  • 方式2：先初始化白板实例，再加入白板频道

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

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

这种方式适用于通过 <script> 标签导入 JS 文件，或者通过 npm 获取完整版 SDK 的情况。
相应处理逻辑为：

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

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

这种方式适用于全部 3 种导入白板SDK的情况。
相应处理逻辑为：

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

注册通知

通过 RtcWhiteboard 实例的 on 方法注册回调通知。

// 以下为部分通知示例
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.whiteboardFailover, data => { ... }); // 白板断开自动重连状态变化
rtcWhiteboard.on(PanoRtc.RtcWhiteboard.Events.userRoleTypeChanged, data => { ... }); // 当前用户角色类型变化
rtcWhiteboard.on(PanoRtc.RtcWhiteboard.Events.docCreated, data => { ... }); // 文档创建事件
rtcWhiteboard.on(PanoRtc.RtcWhiteboard.Events.docDeleted, data => { ... }); // 文档删除事件
rtcWhiteboard.on(PanoRtc.RtcWhiteboard.Events.messageReceived, data => { ... }); // 收到消息

请按需处理各种事件通知，完整的通知列表，请查看 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 实例的以下全局属性后，仅对新绘制的图形生效。
如果需要更新已选择的图形，请调用相应的设置方法 setSelectedShapeStyle。
详请参考 RtcWhiteboard Properties。

  • lineWidth：表示线条和边框的宽度，number 类型，默认值为：5。
rtcWhiteboard.lineWidth = 5;
  • fillStyle：表示封闭图形（如椭圆和矩形）的填充颜色，string 类型（仅支持 rgba 格式），默认值为：'rgba(112, 124, 138, 1)'。
rtcWhiteboard.fillStyle = 'rgba(255, 0, 0, 1)';
  • fillType：表示封闭图形填充方式，string 类型，默认值为 'none' 表示不填充，可配置为 'color' 表示填充颜色。
    如果配置为填充颜色，则不再显示边框颜色。
rtcWhiteboard.fillType = 'color';

其他全局属性

  • selectedShape：表示当前被选中的图形
  • scale：表示当前白板视图的缩放比例
  • activeDoc：表示当前激活的文档信息
  • activeDocId：表示当前激活的文档ID
  • role：表示当前用户的角色
  • isAdmin：表示当前用户是否是管理员
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.Ellipse); // 椭圆工具，按住 Shift 可以绘制圆形
rtcWhiteboard.setToolType(PanoRtc.Constants.ShapeType.Text); // 文本工具
rtcWhiteboard.setToolType(PanoRtc.Constants.ShapeType.Select); // 选择工具，可以框选多个图形
rtcWhiteboard.setToolType(PanoRtc.Constants.ShapeType.Delete); // 删除选中的图形
// 橡皮檫工具，可以结合全局属性 lineWidth 控制擦除宽度
rtcWhiteboard.setToolType(PanoRtc.Constants.ShapeType.Eraser);
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();

图片操作

设置背景图片缩放模式

通过 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));

多媒体操作

上传音频

通过 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 实例的 setScale 方法设置当前画板的缩放比例（0.1 - 5，number 类型）。

rtcWhiteboard.setScale(1.5);

移动

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

  • 每次调用，都是基于原始位置进行移动，而不是基于当前位置进行移动。
  • smooth 表示是否平滑移动，duration 表示平滑移动时间（单位毫秒）
rtcWhiteboard.setTranslate(100, 100, true, 1000);

获取位移

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

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

禁用鼠标和手势

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

rtcWhiteboard.disableScaleAndMove();

禁用滚轮缩放

通过 RtcWhiteboard 实例的 disableWheelScale 方法禁止通过滚轮缩放画板。

rtcWhiteboard.disableWheelScale();

更新画板尺寸

通过 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 方法关闭白板。可以通过 open 方法重新打开。

rtcWhiteboard.close();

高级功能

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

SDK API 指南

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

示例代码

为方便开发者了解丰富的接口使用方式，我们还提供示例代码，请 体验参考。

Last updated on 4/12/2021
← iOS (Objective-C)简介 →