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
:表示当前激活的文档IDrole
:表示当前用户的角色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
实例的 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
实例的 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 列表。
示例代码
为方便开发者了解丰富的接口使用方式,我们还提供示例代码,请 体验参考。