Android (Java)
本文介绍 Android 白板的部分高级功能。
请先查看 Android 白板快速接入指南 了解基本功能后，再查看此文档。
文档操作
Pano 支持多白板，每块白板支持多份文档，每份文档支持多个页面。
即白板的层级结构为：白板 -> 文档 -> 页面。
初始化
RtcWhiteboard实例时，会自动生成docId为"default"的只有一页的默认文档。
创建文档
可以通过以下 3 种方式创建新文档。
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) 或 createDoc(String filePath, WBDocConvertConfig param) 方法上传本地需转码的文件并创建新的白板文档。
- 仅支持 pdf、pptx、ppt、docx、doc、xlsx、xls 格式的文件。
- 文件上传后会自动转码，转码成功后会自动创建一份新的白板文档，此操作会触发
onCreateDoc事件(其中返回fileId表示创建的白板文档)。
随后可以调用getFileInfo方法传入fileId获取docId(表示上传的文件转码后的文档ID) 等信息。 - 如果上传的文件有多页，则新创建的白板文档也相应有多页。
为了获得更好的体验，请参考 文档转码建议。
mWhiteboard.createDoc("/sdcard/test.pptx");
/*
WBDocConvertConfig convertConfig = new WBDocConvertConfig();
// WBDocConvertType 包括：JPG (默认值), PNG, H5, PDF
convertConfig.type = Constants.WBDocConvertType.JPG;
convertConfig.needThumb = false;
mWhiteboard.createDoc("/sdcard/test.pptx", convertConfig);
*/
3、加载已转码文档
通过 RtcWhiteboard 实例的 addDoc(WBDocContents contents) 方法，传入 docId 或 URL 加载已转码文档(文档转码相关内容请 点此查看)。
WBDocContents wbDocContents = new WBDocContents();
wbDocContents.name = "白板文档名称";
wbDocContents.docId = "123456789"; // 通过 docId 来加载已转码文档
/* 通过 URL 来加载
List<String> urls = new ArrayList<String>();
urls.add("https://...");
urls.add("https://...");
...
*/
mWhiteboard.addDoc(wbDocContents);
列举文档
通过 RtcWhiteboard 实例的 enumerateFiles 方法列举文档，将返回文档ID列表。
List<String> fileIds = mWhiteboard.enumerateFiles();
获取当前白板文档ID
通过 RtcWhiteboard 实例的 getCurrentFileId 方法获取当前白板文档ID。
String fileId = mWhiteboard.getCurrentFileId();
切换文档
通过 RtcWhiteboard 实例的 switchDoc 方法切换文档。
mWhiteboard.switchDoc("123456");
删除文档
通过 RtcWhiteboard 实例的 deleteDoc 方法删除文档（默认文档不支持删除）。
mWhiteboard.deleteDoc("123456");
获取当前页码
通过 RtcWhiteboard 实例的 getCurrentPageNumber 方法获取当前页码（页码从 1 开始）。
int currentPageNumber = 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();
其他操作
固定白板宽高
Pano 白板默认是无界的，但是有的场景下开发者可能需要固定白板宽高。
通过 RtcWhiteboard 实例的 initVision(WBVisionConfig config) 方法设置白板宽高。
将 WBVisionConfig 的 limited 参数指定为 true 来固定宽高。
- 各端设置的宽高数值需要保持一致。
- 打开白板时
open接口传入的视图的宽高比需要和此处传入的宽高比保持一致。
WBVisionConfig wbVisionConfig = new WBVisionConfig();
wbVisionConfig.width = 640;
wbVisionConfig.height = 360;
wbVisionConfig.limited = true;
mWhiteboard.initVision(wbVisionConfig);
广播消息
通过 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 白板支持多白板的特色功能。
例如，对于多人教学场景，老师和学生之间可以使用一块公共白板，用于老师授课。
每位学生也可以有一块自己的白板，用于提交各自的学习内容。
老师可以切换查看公共白板和每位特定学生的白板，每位学生也可以切换查看公共白板和自己的白板。
通过 RtcEngine 实例的 switchWhiteboard(String whiteboardId) 方法切换白板，然后通过 getWhiteboard 方法来获取白板，随后即可调用 RtcWhiteboard 实例的 open 方法打开该白板。
(SDK版本1.3.8+)可以通过 RtcWhiteboard 实例的 getCurrentWhiteboardId 方法获取当前白板ID。
// whiteboardId 参数是由开发者自定义的白板ID
mRtcEngine.switchWhiteboard("Student1");
mWhiteboard = mRtcEngine.getWhiteboard(); // 此后即可打开 "Student1" 白板
wbId = mWhiteboard.getCurrentWhiteboardId(); // "Student1"
...
mRtcEngine.switchWhiteboard("default"); // 切换到默认白板（公共白板）
mWhiteboard = mRtcEngine.getWhiteboard(); // 此后即可打开 "default" 白板
wbId = mWhiteboard.getCurrentWhiteboardId(); // "default"
- 如果从未调用过
switchWhiteboard方法，直接调用getWhiteboard方法，RtcEngine会自动创建 ID 为"default"的默认白板。- 如果先调用
switchWhiteboard方法再调用getWhiteboard方法，则会获取到最近一次切换的白板。- 前缀为 "pano-" 的白板ID为保留值，开发者请不要使用。
停止白板
通过 RtcWhiteboard 实例的 stop 方法停止白板（注意：默认白板不能停止），此方法会指示服务器销毁当前白板并踢出所有加入该白板的用户，请谨慎使用。
mWhiteboard.stop();
open/close/leave/stop的区别
open: 开启白板并且设置显示窗口，并且开始计费- 对于默认白板，如果任意用户调用
open接口，则加入该白板频道的所有用户都会自动连接默认白板并开始计费。 - 对于自定义白板(多白板)，各用户调用
open接口时仅本人开始计费。
- 对于默认白板，如果任意用户调用
close: 关闭白板UI，不会销毁本地白板，不会断开白板服务，不会停止本人计费 (可以重新open)leave: 关闭白板UI，销毁本地白板，断开白板服务，停止本人计费 (可以重新open)stop: 关闭白板UI，销毁本地白板，断开白板服务，踢出该白板内所有用户，停止所有用户计费