iOS (Objective-C) · Pano开发者中心

本文介绍 iOS 白板的部分高级功能。

请先查看 iOS 白板快速接入指南了解基本功能后，再查看此文档。

文档操作

Pano 支持多白板，每块白板支持多份文档，每份文档支持多个页面。
即白板的层级结构为：白板 -> 文档 -> 页面。

初始化 PanoRtcWhiteboard 实例时，会自动生成 docId 为 "default" 的只有一页的默认文档。

创建文档

可以通过以下两种方式创建新文档。

1、导入背景图片创建新文档

通过 PanoRtcWhiteboard 实例的 - createDocWithImages: 方法导入指定数量的背景图片并创建新的白板文档。

如果导入多张背景图片，则新创建的白板文档也相应有多页。创建成功会触发 - onDocCreate:file: 事件。
背景图片缩放模式会决定导入后背景图片的布局。

NSString * url1 = @"..."; // 仅支持网络路径
NSString * url2 = @"...";
NSArray * urls = @[url1, url2];
[self.whiteboardEngine createDocWithImages:urls];

2、上传文档创建新文档

通过 PanoRtcWhiteboard 实例的 - createDocWithFilePath: 方法上传本地需转码的文件并创建新的白板文档。

文件上传后会自动转码，转码成功后自动创建一份新的白板文档，创建成功会触发 - onDocCreate:file: 事件。
如果上传的文件有多页，则新创建的白板文档也相应有多页。

[self.whiteboardEngine createDocWithFilePath:...];

列举文档

通过 PanoRtcWhiteboard 实例的 - enumerateFiles 方法列举文档，将返回文档ID列表。

[self.whiteboardEngine enumerateFiles];

获取当前白板文档ID

通过 PanoRtcWhiteboard 实例的 - getCurrentFileId 方法获取当前白板文档ID。

[self.whiteboardEngine getCurrentFileId];

切换文档

通过 PanoRtcWhiteboard 实例的 - switchDoc: 方法切换文档。

[self.whiteboardEngine switchDoc:@"123456"];

删除文档

通过 PanoRtcWhiteboard 实例的 - deleteDoc: 方法删除文档（默认文档不支持删除）。

[self.whiteboardEngine deleteDoc:@"123456"];

获取当前页码

通过 PanoRtcWhiteboard 实例的 - getCurrentPageNumber 方法获取当前页码（页码从 1 开始）。

self.curPage = [self.whiteboardEngine getCurrentPageNumber];

获取当前文档页码总数

通过 PanoRtcWhiteboard 实例的 - getTotalNumberOfPages 方法获取当前文档的页码总数。

self.totalPages = [self.whiteboardEngine getTotalNumberOfPages];

切换页码

通过 PanoRtcWhiteboard 实例的 - prevPage 方法切换到当前文档的上一页，- nextPage 方法切换到下一页。

// [self.whiteboardEngine prevPage]; // 切换到当前文档的上一页
[self.whiteboardEngine nextPage]; // 切换到下一页

通过 PanoRtcWhiteboard 实例的 - gotoPage: 方法切换到指定页面（页码从 1 开始）。

[self.whiteboardEngine gotoPage:1];

切换页码、添加页码、删除页面会触发 - onPageNumberChanged:withTotalPages: 回调。

添加页面

通过 PanoRtcWhiteboard 实例的 - addPage: 方法添加一个新页面到当前文档最后。

添加页面是异步的，添加成功后会触发 - onContentUpdated 事件，随后可以通过 - getTotalNumberOfPages 方法获取当前文档页码总数，通过 ``- getCurrentPageNumber` 方法获取当前页码。
autoSwitch 参数表示是否自动切换到新页面。

[self.whiteboardEngine addPage:YES];

添加页面到指定位置

通过 PanoRtcWhiteboard 实例的 - insertPage:autoSwitch: 方法添加一个新页面到 pageNo 之后（页码从 1 开始）。

如果传入的 pageNo 参数超出文档页码总数，会返回 kPanoResultFailed。
autoSwitch 参数表示是否自动切换到新页面。

[self.whiteboardEngine insertPage:1 autoSwitch:YES];

删除页面

通过 PanoRtcWhiteboard 实例的 - removePage: 或 - removePage:switchNext: 方法删除指定页面。
默认行为是切换到被删除页的前一页（若有）。当 switchNext 设置为 true 时切换到被删除页的后一页。

[self.whiteboardEngine removePage:self.curPage];

视角跟随

视角跟随指的是和其他用户同步缩放或移动。

事件通知

请注意监听视角跟随相关的事件通知：

- onVisionShareStarted:：用户开始分享视角
- onVisionShareStopped:：用户停止分享视角

分享视角

通过 PanoRtcWhiteboard 实例的 - startShareVision 方法分享视角，- stopShareVision 方法停止分享。
开始和停止时，其他用户会收到通知。

[self.whiteboardEngine startShareVision];

跟随视角

通过 PanoRtcWhiteboard 实例的 - startFollowVision 方法跟随他人视角，- stopFollowVision 方法停止跟随。

[self.whiteboardEngine startFollowVision];

其他操作

设置用户角色

通过 PanoRtcWhiteboard 实例的 - setRoleType: 方法设置自己的角色。

kPanoWBRoleAdmin：管理员，kPanoWBRoleAttendee：普通用户：kPanoWBRoleViewer 仅观看的用户
这是异步操作，请注意监听 - onRoleTypeChanged: 通知。

[self.whiteboardEngine setRoleType:kPanoWBRoleAdmin]; // 设置自己为管理员

广播消息

通过 PanoRtcWhiteboard 实例的 - broadcastMessage: 方法广播消息（发给白板频道内所有用户）。

NSDictionary * dict = [[NSDictionary alloc] init];
[dict setValue:@"这是一条广播消息" forKey:@"msg"];
// options 设置为 nil，转换后的 JSON 不会包含回车和换行
NSData * json = [NSJSONSerialization dataWithJSONObject:dict options:nil error:nil];
// 此接口只要求 message 参数为 NSData 格式，但是为便于和其他端兼容解析，建议封装为 JSON 格式
[self.whiteboardEngine broadcastMessage:json];

发送消息

通过 PanoRtcWhiteboard 实例的 - sendMessage:toUser: 方法向特定用户发送消息。

NSDictionary * dict = [[NSDictionary alloc] init];
[dict setValue:@"这是一条定向消息" forKey:@"msg"];
// options 设置为 nil，转换后的 JSON 不会包含回车和换行
NSData * json = [NSJSONSerialization dataWithJSONObject:dict options:nil error:nil];
// 此接口只要求 message 参数为 NSData 格式，但是为便于和其他端兼容解析，建议封装为 JSON 格式
[self.whiteboardEngine sendMessage:json toUser:12345];

截图

截图当前页面

通过 PanoRtcWhiteboard 实例的 - snapshot:path: 方法将当前白板页面截图。

mode 参数含义：kPanoWBSnapshotView - 可见区域， kPanoWBSnapshotAll - 整个页面。
截图结果将触发 - onSnapshotComplete:name: 回调。

[self.whiteboardEngine snapshot:kPanoWBSnapshotAll path:documentPath];

截图特定文档所有页面

通过 PanoRtcWhiteboard 实例的 - saveDocToImages:path: 方法将特定白板文档的所有页面截图。

每个页面保存为一张图片，图片名称格式为：whiteboard_[fileId]_[page number].png, 例如：whiteboard_default_1.png。
截图结果将触发 - onDocSave:file:path: 和 - onSnapshotComplete:name: 回调。

[self.whiteboardEngine saveDocToImages:@"12345" path:documentPath];

多白板

切换与获取白板

Pano iOS 白板支持多白板的特色功能。
例如，对于多人教学场景，老师和学生之间可以使用一块公共白板，用于老师授课。
每位学生也可以有一块自己的白板，用于提交各自的学习内容。
老师可以切换查看公共白板和每位特定学生的白板，每位学生也可以切换查看公共白板和自己的白板。

通过 PanoRtcEngineKit 实例的 - switchWhiteboardEngine: 方法切换白板，然后通过 - whiteboardEngine 方法来获取白板，随后即可操作该白板。
(SDK版本1.3.8+)可以通过 PanoRtcWhiteboard 实例的 - getCurrentWhiteboardId 方法获取当前白板ID。

// - switchWhiteboardEngine: 方法的 whiteboardId 参数是由开发者自定义的白板ID
[self.engineKit switchWhiteboardEngine:@"Student1"];
self.whiteboardEngine = [self.engineKit whiteboardEngine]; // 此后即可操作 "Student1" 白板
docId = [self.whiteboardEngine getCurrentWhiteboardId]; // "Student1"
...
[self.engineKit switchWhiteboardEngine:@"default"]; // 切换到默认白板（公共白板）
self.whiteboardEngine = [self.engineKit whiteboardEngine]; // 此后即可操作 "default" 白板
docId = [self.whiteboardEngine getCurrentWhiteboardId]; // "default"

如果从未调用过 - switchWhiteboardEngine: 方法，直接调用 - whiteboardEngine 方法，PanoRtcEngineKit 会自动创建ID为 "default" 的默认白板。

如果先调用 - switchWhiteboardEngine: 方法再调用- whiteboardEngine 方法，则会获取到最近一次切换的白板。

前缀为 "pano-" 的白板ID为保留值，开发者请不要使用。

停止白板

通过 PanoRtcWhiteboard 实例的 - stop 方法停止白板（注意：默认白板不能停止），此方法会指示服务器销毁当前白板并踢出所有加入该白板的用户，请谨慎使用。

[self.whiteboardEngine stop];