Web
本文介绍 Web 白板的部分高级功能。
请先查看 Web 白板快速接入指南 了解基本功能后,再查看此文档。
文档操作
Pano 白板支持多份文档,每份文档支持多个页面。
即白板的层级结构为:白板 -> 文档 -> 页面。
调用
RtcWhiteboard
实例的open
方法打开白板时,会自动生成docId
和name
均为'default'
的只有一页的默认文档。
上传文档
通过 RtcWhiteboard
实例的 uploadDoc(onDocTranscodeStatus: function, transcodeType: "doc" | "courseware", needThumb: boolean, lifeType: 1 | 2)
方法上传文档,调用接口会自动打开文件选择框。
transcodeType
参数为'doc'
时支持 Word、Excel、PowerPoint、PDF 文件(转码为图片),为'courseware'
时仅支持 PowerPoint 文件(转码为在线资源)。- 文件上传后会自动转码,转码成功后自动创建一份新的白板文档,文档创建成功会触发
docCreated
事件。 - 如果上传的文件有多页,则新创建的白板文档也相应有多页。
needThumb
参数表示是否生成文档缩略图。lifeType
参数表示转码结果保存时间:1 - 长期(默认 7 天),2 - 临时(默认值)。- 早期的 SDK 版本不支持
needThumb
和lifeType
参数。
rtcWhiteboard.uploadDoc(obj => {
console.info(obj)
}, 'doc', true, 1);
加载文档
通过 RtcWhiteboard
实例的 loadDoc(fileKey: string)
方法加载已缓存的文档。
- 先通过 上传文档并转码 接口获取返回的
docId
参数,再通过 查询文档信息 查询该文档的转码结果,"status": 3
表示转码完成,此后可以将该docId
作为loadDoc
方法的fileKey
参数传入。
rtcWhiteboard.loadDoc("1234567890").then(info => console.info(info));
列举文档
通过 RtcWhiteboard
实例的 enumerateDocs()
方法列举文档信息。
rtcWhiteboard.enumerateDocs();
切换文档
通过 RtcWhiteboard
实例的 switchToDoc(docId: string)
方法切换文档。
rtcWhiteboard.switchToDoc('default');
删除文档
通过 RtcWhiteboard
实例的 deleteDoc(docId: string, switchDocId?: string)
方法删除文档。
switchDocId
参数表示删除后跳转到指定文档(如果不传值并且删除当前文档,则跳转至默认文档)
rtcWhiteboard.deleteDoc('1234567890');
默认文档不支持删除。
获取当前页码
通过 RtcWhiteboard
实例的 getCurrentPageNumber
方法获取当前页码(页码从 0 开始)。
rtcWhiteboard.getCurrentPageNumber();
获取当前文档页码总数
通过 RtcWhiteboard
实例的 getTotalNumberOfPages
方法获取当前文档的页码总数。
rtcWhiteboard.getTotalNumberOfPages();
切换页码
通过 RtcWhiteboard
实例的 prevPage
方法切换到当前文档的上一页,nextPage
方法切换到下一页。
rtcWhiteboard.nextPage();
通过 RtcWhiteboard
实例的 gotoPage(pageIndex: number, docId?: string)
方法切换到指定文档的指定页面(页码从 0 开始,如果不传 docId
默认操作当前文档)。
rtcWhiteboard.gotoPage(0, 'default');
添加页面
通过 RtcWhiteboard
实例的 addPage(autoSwitch: boolean)
方法添加一个新页面到当前文档最后。
- 添加页面是异步的,添加成功后会触发
whiteboardContentUpdate
事件,随后可以通过getTotalNumberOfPages
方法获取当前文档页码总数,通过getCurrentPageNumber
方法获取当前页码。 autoSwitch
参数表示是否自动切换到新页面。- 不支持对动态课件添加页面。
rtcWhiteboard.addPage(true);
添加页面到指定位置
通过 RtcWhiteboard
实例的 insertPage(pageIndex: number, autoSwitch: boolean, docId?: string)
方法添加一个新页面到指定文档的指定位置。
pageIndex
参数表示页码位置(页码从 0 开始),如果传入的参数超出文档页码总数,会返回"INVALID_INDEX"
。autoSwitch
参数表示是否自动切换到新页面。docId
参数如果不传,默认操作当前文档。- 不支持对动态课件添加页面。
rtcWhiteboard.insertPage(6, true);
删除页面
通过 RtcWhiteboard
实例的 removePage(index: number, docId?: string)
方法删除指定页面。
docId
参数如果不传,默认操作当前文档。- 不支持对动态课件删除页面。
rtcWhiteboard.removePage(1);
课件操作
本小节(课件操作)介绍的内容,仅适用于动态课件(
'courseware'
),不适用于普通文档('doc'
)。
步骤跳转
通过 RtcWhiteboard
实例的 coursewarePrev
方法跳转到课件的上一步,coursewareNext
方法跳转到下一步。
rtcWhiteboard.coursewareNext();
课件交互
通过 RtcWhiteboard
实例的 disableCoursewareInteraction
方法禁止用户通过键盘上下左右键控制课件交互,enableCoursewareInteraction
方法开启键盘方向键交互。
rtcWhiteboard.disableCoursewareInteraction();
通过 RtcWhiteboard
实例的 setToolType
方法设置工具类型为 ShapeType.Click
可以操作白板底部的课件。
rtcWhiteboard.setToolType(Constants.ShapeType.Click); // 可以操作白板底部的课件
视角跟随
视角跟随指的是和其他用户同步缩放或移动。
事件通知
请注意监听视角跟随相关的事件通知:
userVisionShareStart
:其他用户开始分享视角userVisionShareStop
:其他用户停止分享视角visionLockStop
: 自己分享视角时被他人抢占
分享视角
通过 RtcWhiteboard
实例的 startVisionShare
方法分享视角,stopVisionShare
方法停止分享。
开始和停止时,其他用户会收到通知。
rtcWhiteboard.startVisionShare();
跟随视角
通过 RtcWhiteboard
实例的 startFollowVision
方法跟随他人视角,stopFollowVision
方法停止跟随。
rtcWhiteboard.startFollowVision();
对接手写板
事件驱动
RtcWhiteboard
实例通过浏览器的自定义事件接收手写板的绘制指令,绘制指令结构如下:
type PanoPenEvent = {
// hang:手写笔悬停;start:书写开始;write:书写事件;end:书写结束
eventType: 'hang' | 'start' | 'write' | 'end'
x: number // 轨迹点 x 坐标
y: number // 轨迹点 y 坐标
width: number // 手写板宽度
height: number // 手写板高度
}
开发者需要根据您使用的手写板sdk里提供的事件类型,在接收到绘制事件时,转换为对应的 PanoPenEvent
的 eventType
,然后dispatch
到浏览器中,其中 start
类型不是必须的,可以直接发送 write
指令开始书写。
除了选择激光笔(ShapeType.LaserPointer)类型,其他绘制模式下手写板绘制指令均会绘制自由路径(ShapeType.Pen)
示例代码:
// 在某手写笔的sdk中接收到绘制事件时,判断该事件为书写的事件
// 假设书写事件的点位为 (100, 600),手写板的长宽为 1280 * 600
window.dispatchEvent(
new CustomEvent('panoPenEvent', {
detail: {
eventType: 'write',
x: 100,
y: 600,
width: 1280,
height: 600
}
})
);
设置手写板缩放和位移
以宽或以高为准缩放到白板画布
默认情况下,手写板的轨迹点位是以手写板的宽度作为缩放标准对应到画布上的,可以通过白板实例的 tabletMatchMode
属性指定以宽或高为准缩放
// tabletMatchMode: 'fitWidth' | 'fitHeight' = 'fitWidth'
console.log(rtcWhiteboard.tabletMatchMode); // 默认为 'fitWidth'
rtcWhiteboard.tabletMatchMode = 'fitHeight';
console.log(rtcWhiteboard.tabletMatchMode); // 输出 'fitHeight'
手写板缩放比例
通过白板实例的 tabletScale
属性设置手写板绘制到画布上的缩放比例,默认缩放比例为 1,即手写板是 1:1 对应到画布上的。
放大仅放大对应的点位,手写笔的轨迹宽度不受影响,轨迹宽度只受白板实例的 lineWidth
属性影响。
例如,当以tabletMatchMode
为 fitWidth
模式书写,在 tabletScale
为 1 时,在手写笔的水平 50% 位置画一个点,对应在白板上的位置也是水平50%的位置,当 tabletScale
为 2 时,在水平 50% 位置画一个点,在白板上对应的坐标值被放大了 2 倍,该点位在画布上对应为水平 100% 处。
移动端显示手写板的内容,如果默认比例下觉得写得字显示到白板上比较小,可以尝试把
tabletScale
设置大一点
console.log(rtcWhiteboard.tabletScale); // 默认为 1
rtcWhiteboard.tabletScale = 2;
console.log(rtcWhiteboard.tabletScale); // 输出 2,手写板在画布上被放大2倍
手写板位移
通过白板实例的 tabletTranslate
属性设置手写板相对于画布原点的位移比例,默认位移为 [0, 0],即手写板的左上角位置和画布的左上角(坐标[0, 0])位置一致。
位移的计算不受缩放影响。
console.log(rtcWhiteboard.tabletTranslate); // 默认为 [0, 0]
rtcWhiteboard.tabletTranslate = [100, 100];
console.log(rtcWhiteboard.tabletTranslate); // 输出 [100, 100]
手写板绘制模式
默认情况下手写板和白板画布是静态结合在一起的,默认情况下白板的画布是无限的,用户可以往任意方向无限托拽画布,但是手写板绘制的内容只会被限定在某个范围内显示,
可以通过设置白板实例的tabletWriteMode
属性设置让手写的内容不受拖拽影响,永远都以目前可视区域的左上角为原点计算对应的点位。
例如:假设白板的宽高为 500x500,手写板的宽高为 1000x2000,默认情况下,手写板内书写产生的轨迹点位只会被计算对应到白板的(0, 0) - (500, 1000) 的矩形范围内。
// tabletWriteMode: 'static' | 'sticky' = 'static'
console.log(rtcWhiteboard.tabletWriteMode); // 默认为 'static'
rtcWhiteboard.tabletWriteMode = 'sticky';
console.log(rtcWhiteboard.tabletWriteMode); // 输出 'sticky'
其他操作
设置用户角色
通过 RtcWhiteboard
实例的 setRoleType(roleType: WBRoleType)
方法设置自己的角色(Admin
:管理员,Attendee
:普通用户)。
这是异步操作,请注意监听 userRoleTypeChanged
通知。
Admin
(管理员)可以控制或删除Attendee
(普通用户)添加的内容。
rtcWhiteboard.setRoleType(PanoRtc.Constants.WBRoleType.Admin); // 设置自己为管理员
广播消息
通过 RtcWhiteboard
实例的 broadcastMessage(message: any)
方法广播消息(发给白板频道内所有用户)。
rtcWhiteboard.broadcastMessage('这是一条广播消息');
收到消息会触发
messageReceived
事件通知。
发送消息
通过 RtcWhiteboard
实例的 sendMessage(to: string, message: any)
方法向特定用户发送消息。
rtcWhiteboard.sendMessage('10000', '这是一条定向消息');
收到消息会触发
messageReceived
事件通知。
截图
通过 RtcWhiteboard
实例的 snapshot(autoDownload: boolean, mode: 'all' | 'view')
方法截图。
autoDownload
参数表示是否自动下载mode
参数表示截图模式('all'
:截取整个页面,'view'
:截取当前可视区域)
rtcWhiteboard.snapshot(true, 'all');
获取统计信息
通过 RtcWhiteboard
实例的 getStatistics
方法获取用户创建的图形数据统计信息。
rtcWhiteboard.getStatistics();