Android (Java)
本文介绍 Android 白板的部分高级功能。
请先查看 Android 白板快速接入指南 了解基本功能后,再查看此文档。
文档操作
Pano 支持多白板,每块白板支持多份文档,每份文档支持多个页面。
即白板的层级结构为:白板 -> 文档 -> 页面。
初始化
RtcWhiteboard
实例时,会自动生成docId
为"default"
的只有一页的默认文档。
创建文档
可以通过以下两种方式创建新文档。
1、导入背景图片创建新文档
通过 RtcWhiteboard
实例的 createDoc(List<String> imageUrls)
方法导入指定数量的背景图片并创建新的白板文档。
- 如果导入多张背景图片,则新创建的白板文档也相应有多页。创建成功会触发
onCreateDoc
事件。 - 背景图片缩放模式 会决定导入后背景图片的布局。
List<String> imageUrls = new ArrayList<String>();
imageUrls.add("...url1...");
imageUrls.add("...url2...");
mWhiteboard.createDoc(imageUrls);
2、上传文档创建新文档
通过 RtcWhiteboard
实例的 createDoc(String filePath)
方法上传本地需转码的文件并创建新的白板文档。
- 文件上传后会自动转码,转码成功后自动创建一份新的白板文档,创建成功会触发
onCreateDoc
事件。 - 如果上传的文件有多页,则新创建的白板文档也相应有多页。
mWhiteboard.createDoc("/sdcard/test.pptx");
列举文档
通过 RtcWhiteboard
实例的 enumerateFiles
方法列举文档,将返回文档ID列表。
mWhiteboard.enumerateFiles();
获取当前白板文档ID
通过 RtcWhiteboard
实例的 getCurrentFileId
方法获取当前白板文档ID。
mWhiteboard.getCurrentFileId();
切换文档
通过 RtcWhiteboard
实例的 switchDoc
方法切换文档。
mWhiteboard.switchDoc("123456");
删除文档
通过 RtcWhiteboard
实例的 deleteDoc
方法删除文档(默认文档不支持删除)。
mWhiteboard.deleteDoc("123456");
获取当前页码
通过 RtcWhiteboard
实例的 getCurrentPageNumber
方法获取当前页码(页码从 1 开始)。
mWhiteboard.getCurrentPageNumber();
获取当前文档页码总数
通过 RtcWhiteboard
实例的 getTotalNumberOfPages
方法获取当前文档的页码总数。
mWhiteboard.getTotalNumberOfPages();
切换页码
通过 RtcWhiteboard
实例的 prevPage
方法切换到当前文档的上一页,nextPage
方法切换到下一页。
// mWhiteboard.prevPage(); // 切换到当前文档的上一页
mWhiteboard.nextPage(); // 切换到下一页
通过 RtcWhiteboard
实例的 gotoPage
方法切换到指定页面(页码从 1 开始)。
mWhiteboard.gotoPage(1);
切换页码、添加页码、删除页面 会触发
onPageNumberChanged
回调。
添加页面
通过 RtcWhiteboard
实例的 addPage(boolean autoSwitch)
方法添加一个新页面到当前文档最后。
- 添加页面是异步的,添加成功后会触发
onContentUpdated
事件,随后可以通过getTotalNumberOfPages
方法获取当前文档页码总数,通过getCurrentPageNumber
方法获取当前页码。 autoSwitch
参数表示是否自动切换到新页面。
mWhiteboard.addPage(true);
添加页面到指定位置
通过 RtcWhiteboard
实例的 insertPage(int pageNo, boolean autoSwitch)
方法添加一个新页面到 pageNo
之后(页码从 1 开始)。
- 如果传入的
pageNo
参数超出文档页码总数,会返回Failed
。 autoSwitch
参数表示是否自动切换到新页面。
mWhiteboard.insertPage(1, true);
删除页面
通过 RtcWhiteboard
实例的 removePage(int pageNo)
或 removePage(int pageNo, boolean switchNext)
方法删除指定页面。
默认行为是切换到被删除页的前一页(若有)。当 switchNext
设置为 true
时切换到被删除页的后一页。
whiteboard.removePage(1);
视角跟随
视角跟随指的是和其他用户同步缩放或移动。
事件通知
请注意监听视角跟随相关的事件通知:
onVisionShareStarted
:用户开始分享视角onVisionShareStopped
:用户停止分享视角
分享视角
通过 RtcWhiteboard
实例的 startShareVision
方法分享视角,stopShareVision
方法停止分享。
开始和停止时,其他用户会收到通知。
whiteboard.startShareVision();
跟随视角
通过 RtcWhiteboard
实例的 startFollowVision
方法跟随他人视角,stopFollowVision
方法停止跟随。
whiteboard.startFollowVision();
其他操作
设置用户角色
通过 RtcWhiteboard
实例的 setRoleType
方法设置自己的角色。
Admin
:管理员,Attendee
:普通用户:Viewer
仅观看的用户- 这是异步操作,请注意监听
onRoleTypeChanged
通知。
mWhiteboard.setRoleType(Constants.WBRoleType.Admin); // 设置自己为管理员
广播消息
通过 RtcWhiteboard
实例的 broadcastMessage
方法广播消息(发给白板频道内所有用户)。
String msg = "{\"msg\": \"这是一条广播消息(JSON格式)\"}";
mWhiteboard.broadcastMessage(msg.getBytes());
发送消息
通过 RtcWhiteboard
实例的 sendMessage
方法向特定用户发送消息。
String msg = "{\"msg\": \"这是一条定向消息(JSON格式)\"}";
mWhiteboard.sendMessage(10000, msg.getBytes());
截图
截图当前页面
通过 RtcWhiteboard
实例的 snapshot
方法将当前白板页面截图。
mode
参数含义:View
- 可见区域,All
- 整个页面。- 截图结果将触发
onSnapshotComplete (Constants.QResult result, String filename)
回调。
mWhiteboard.snapshot(Constants.WBSnapshotMode.View, "/sdcard");
截图特定文档所有页面
通过 RtcWhiteboard
实例的 saveDocToImages
方法将特定白板文档的所有页面截图。
- 每个页面保存为一张图片,图片名称格式为:whiteboard_[fileId]_[page number].png, 例如:whiteboard_default_1.png。
- 截图结果将触发
onSaveDoc
和onSnapshotComplete
回调。
String fileId = mWhiteboard.getCurrentFileId();
mWhiteboard.saveDocToImages(fileId, "/sdcard");
多白板
切换与获取白板
Pano Android 白板支持多白板的特色功能。
例如,对于多人教学场景,老师和学生之间可以使用一块公共白板,用于老师授课。
每位学生也可以有一块自己的白板,用于提交各自的学习内容。
老师可以切换查看公共白板和每位特定学生的白板,每位学生也可以切换查看公共白板和自己的白板。
通过 RtcEngine
实例的 switchWhiteboard(String whiteboardId)
方法切换白板,然后通过 getWhiteboard
方法来获取白板,随后即可操作该白板。
(SDK版本1.3.8+)可以通过 RtcWhiteboard
实例的 getCurrentWhiteboardId
方法获取当前白板ID。
// whiteboardId 参数是由开发者自定义的白板ID
mRtcEngine.switchWhiteboard("Student1");
mWhiteboard = mRtcEngine.getWhiteboard(); // 此后即可操作 "Student1" 白板
docId = mWhiteboard.getCurrentWhiteboardId(); // "Student1"
...
mRtcEngine.switchWhiteboard("default"); // 切换到默认白板(公共白板)
mWhiteboard = mRtcEngine.getWhiteboard(); // 此后即可操作 "default" 白板
docId = mWhiteboard.getCurrentWhiteboardId(); // "default"
- 如果从未调用过
switchWhiteboard
方法,直接调用getWhiteboard
方法,RtcEngine
会自动创建ID为"default"
的默认白板。- 如果先调用
switchWhiteboard
方法再调用getWhiteboard
方法,则会获取到最近一次切换的白板。- 前缀为 "pano-" 的白板ID为保留值,开发者请不要使用。
停止白板
通过 RtcWhiteboard
实例的 stop
方法停止白板(注意:默认白板不能停止),此方法会指示服务器销毁当前白板并踢出所有加入该白板的用户,请谨慎使用。
mWhiteboard.stop();