iOS (Objective-C)

本文结合部分 SDK API ，介绍如何快速接入白板功能。

如需查看完整 SDK API 列表，请点击左侧导航查看：
SDK API - macOS/iOS (Objective-C) - PanoPanoRtcWhiteboard。

导入SDK

请 点此查看 如何导入SDK。

获取白板

使用白板前，请先 初始化 PanoRtcEngineKit 实例，再通过其 - whiteboardEngine 方法获取白板控制接口。

whiteboardEngine = [self.engineKit whiteboardEngine];

注册通知

通过 PanoRtcWhiteboard 实例的 - setDelegate: 方法注册白板回调，用来接收白板事件通知。

[self.whiteboardEngine setDelegate:self];

完整的回调方法列表与介绍，请查看 PanoPanoRtcWhiteboardDelegate 协议。

加入频道

请 点此查看 如何加入频道。对于加入频道时的 PanoRtcChannelConfig.serviceFlags 参数：

  • 如果需要同时使用音视频和白板功能，请将其配置为：
    kPanoChannelServiceMedia | kPanoChannelServiceWhiteboard；
  • 如果仅使用白板功能，请将其配置为 kPanoChannelServiceWhiteboard。

打开白板

加入白板频道成功后，通过 PanoRtcWhiteboard 实例的 - open: 方法打开白板。

第一位用户打开白板时，其他用户会收到 PanoRtcEngineDelegate 的 - onWhiteboardStart 通知。

[self.whiteboardEngine open:self.drawView];

工具条

SDK 内部已实现白板工具绘制和数据同步，但是由于不同的开发者有不同的 UI 设计，因此 SDK 不提供涉及 UI 交互的白板工具条。
请开发者自行设计白板工具条，来结合调用 SDK 接口以执行相应的白板操作。

全局属性

白板颜色

背景色

通过 PanoRtcWhiteboard 实例的 - setBackgroundColor: 方法设置白板背景色。

PanoWBColor * bgColor = [[PanoWBColor alloc] init];
bgColor.red = 0.5;
bgColor.green = 0.5;
bgColor.blue = 0.5;
bgColor.alpha = 1;
[self.whiteboardEngine setBackgroundColor:bgColor];

白板背景色仅在本地显示，不会同步给其他用户。因此每位用户的白板背景色可以不同。

前景色

通过 PanoRtcWhiteboard 实例的 - setForegroundColor: 方法设置白板前景色。
前景色适用于文字、线条和边框的颜色。

PanoWBColor * fgColor = [[PanoWBColor alloc] init];
fgColor.red = 0.5;
fgColor.green = 0.5;
fgColor.blue = 0.5;
fgColor.alpha = 1;
[self.whiteboardEngine setForegroundColor:fgColor];

填充色

通过 PanoRtcWhiteboard 实例的 - setFillColor: 方法设置白板填充色。
填充色适用于封闭图形（如椭圆和矩形）的填充颜色。

PanoWBColor * fillColor = [[PanoWBColor alloc] init];
fillColor.red = 0.5;
fillColor.green = 0.5;
fillColor.blue = 0.5;
fillColor.alpha = 1;
[self.whiteboardEngine setFillColor:fillColor];

适用于文字工具的全局属性

  • 通过 PanoRtcWhiteboard 实例的 - setFontSize: 方法设置字体大小。
[self.whiteboardEngine setFontSize:20]; // 范围：[10, 96]
  • 通过 PanoRtcWhiteboard 实例的 - setFontStyle: 方法设置字体样式（粗体、斜体）。
[self.whiteboardEngine setFontStyle:kPanoWBFontNormal];
// 可选值：kPanoWBFontNormal, kPanoWBFontBold, kPanoWBFontItalic, kPanoWBFontBoldItalic

适用于图形工具的全局属性

  • 通过 PanoRtcWhiteboard 实例的 - setLineWidth: 方法设置线条和边框的宽度。
[self.whiteboardEngine setLineWidth:5]; // 范围：[1, 20]
  • 通过 PanoRtcWhiteboard 实例的 - setFillType: 方法设置封闭图形填充方式。
[self.whiteboardEngine setFillType:kPanoWBFillColor];
// 可选值：kPanoWBFillNone 不填充、kPanoWBFillColor 填充颜色

常用工具

设置工具类型

通过 PanoRtcWhiteboard 实例的 - setToolType: 方法设置工具类型。

[self.whiteboardEngine setToolType:kPanoWBToolNone]; // 空，画板不响应操作，但是可以操作动态课件中的内容
[self.whiteboardEngine setToolType:kPanoWBToolText]; // 文本工具
[self.whiteboardEngine setToolType:kPanoWBToolPath]; // 画笔工具
[self.whiteboardEngine setToolType:kPanoWBToolLaser]; // 激光笔工具
[self.whiteboardEngine setToolType:kPanoWBToolLine]; // 直线工具
[self.whiteboardEngine setToolType:kPanoWBToolArrow]; // 箭头工具
[self.whiteboardEngine setToolType:kPanoWBToolRect]; // 矩形工具
[self.whiteboardEngine setToolType:kPanoWBToolEllipse]; // 椭圆工具
// 使用图章工具前，请先 addStamp(添加图章)、setStamp(设置图章，切换不同图章时需重新设置图章)
[self.whiteboardEngine setToolType:kPanoWBToolStamp]; // 图章工具
[self.whiteboardEngine setToolType:kPanoWBToolSelect]; // 选择工具，可以触摸移动图形
// 从 1.6.6 版本开始，kPanoWBToolEraser 工具更改为 kPanoWBToolDelete 工具
[self.whiteboardEngine setToolType:kPanoWBToolDelete]; // 删除工具，用于删除图形
// 刷子工具本质上是对图层区域做透明处理，所以开启刷子功能时，不要移动和缩放图形
// 刷子工具，可以结合 -setLineWidth: 方法设置其宽度
[self.whiteboardEngine setToolType:kPanoWBToolBrush]; // 刷子工具，用于擦除图形的局部

请在加入白板频道成功后再进行白板操作。

撤销与重做

通过 PanoRtcWhiteboard 实例的 - undo 方法撤消上一次操作，- redo 方法重做上一次被撤销的操作。

[self.whiteboardEngine undo];
  • 只能对自己的操作记录进行撤销与重做。
  • 另请关注通知：- onUndoStatusChanged:, - onRedoStatusChanged:。

图片操作

设置背景图片缩放模式

通过 PanoRtcWhiteboard 实例的 - setBackgroundImageScalingMode: 方法设置背景图片缩放模式。

/* WBImageScalingMode 可选值：
   kPanoWBImageScalingFit 长边充满，短边留空，左上角对齐
   kPanoWBImageScalingAutoFill 短边充满，长边裁剪，左上角对齐
   kPanoWBImageScalingFillWidth 宽度充满，顶部对齐
   KPanoWBImageScalingFillHeight 高度充满，左侧对齐
   kPanoWBImageScalingFitCenter 适合视图，居中
   以上方式都会保持背景图片宽高比
*/
[self.whiteboardEngine setBackgroundImageScalingMode:kPanoWBImageScalingFit];

设置背景图片

通过 PanoRtcWhiteboard 实例的 - setBackgroundImage: 方法设置当前页的背景图片，- setBackgroundImage:withPageNumber: 方法设置指定页的背景图片。

NSString * kDefaultImageUrl = @"https://..."; // 图片 URL，本地或网络路径均可
[self.whiteboardEngine setBackgroundImage:kDefaultImageUrl];

导入背景图片列表

通过 PanoRtcWhiteboard 实例的 - addBackgroundImages: 方法导入背景图片列表到当前白板文档。

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

上传图片

通过 PanoRtcWhiteboard 实例的 - addImageFile: 方法上传图片（此方法上传的图片支持拖拽）。

NSString * kImageUrl = @"https://domain/path/filename.jpg"; // 图片 URL，可为本地路径或远程 URL
[self.whiteboardEngine addImageFile:kImageUrl];

多媒体操作

Admin 用户操作音视频（包括动态课件中嵌入的音视频，以及通过下列方法上传到白板中的音视频）时，播放状态（播放、暂停、拖动进度条）会自动同步给其他用户。

上传音频

通过 PanoRtcWhiteboard 实例的 - addAudioFile: 方法上传音频文件到当前页面。

NSString * kMediaUrl = "https://domain/path/filename.mp3"; // 媒体 URL，可为本地路径或远程 URL
[self.whiteboardEngine addAudioFile:kMediaUrl];

上传视频

通过 PanoRtcWhiteboard 实例的 - addVideoFile: 方法上传视频文件到当前页面。

NSString * kMediaUrl = "https://domain/path/filename.mp4"; // 媒体 URL，可为本地路径或远程 URL
[self.whiteboardEngine addVideoFile:kMediaUrl];

设置用户角色

通过 PanoRtcWhiteboard 实例的 - setRoleType: 方法设置自己的角色(这是异步操作，请注意监听 - onRoleTypeChanged: 通知)。
角色的区别：

定义类型权限备注
kPanoWBRoleAdmin管理员可以使用工具，可以操作所有用户的内容一个频道只能有一位管理员
kPanoWBRoleAttendee普通用户可以使用工具，只能操作自己的内容默认角色
kPanoWBRoleViewer仅观看的用户不能使用工具，只能缩放和移动
 
[self.whiteboardEngine setRoleType:kPanoWBRoleAdmin]; // 设置自己为管理员

画板操作

缩放和移动

缩放

通过 PanoRtcWhiteboard 实例的：

  • - getCurrentScaleFactor 方法获取当前白板视图的缩放比例
  • - getCurrentMaxScaleFactor 方法获取当前白板视图的最大缩放比例
  • - getCurrentMinScaleFactor 方法获取当前白板视图的最小缩放比例
  • - setCurrentScaleFactor: 方法设置缩放比例
Float32 scale = [self.whiteboardEngine getCurrentScaleFactor];
[self.whiteboardEngine setCurrentScaleFactor:1.0f]; // 取值范围 [0.1, 5.0]

重置当前页视角

通过 PanoRtcWhiteboard 实例的 - resetVision 方法重置当前页视角，将当前文档或动态课件一键居中，或者将默认白板恢复初始大小。

[self.whiteboardEngine resetVision];

手势控制缩放和移动

通过 PanoRtcWhiteboard 实例的 - setOption:forType: 方法，type 参数设置为 kPanoWBOptionScaleMove，option 参数设置为带 BOOL 值的 NSNumber 来设置是否允许手势控制白板缩放和移动（不影响通过 - setCurrentScaleFactor: 方法控制缩放）。

[self.whiteboardEngine setOption:@YES forType:kPanoWBOptionEnableUIResponse]; // 默认值为 YES (允许手势控制)

同步光标位置

通过 PanoRtcWhiteboard 实例的 - setOption:forType: 方法：

  • type 参数设置为 kPanoWBOptionCursorPosSync，option 参数设置为带 BOOL 值的 NSNumber 来设置是否同步光标位置给其他用户。
  • type 参数设置为 kPanoWBOptionShowRemoteCursor，option 参数设置为带 BOOL 值的 NSNumber 来设置是否显示其他用户的光标位置。
  • 这两个参数默认都是关闭的。
[self.whiteboardEngine setOption:@YES forType:kPanoWBOptionCursorPosSync]; // 同步光标位置给其他用户
[self.whiteboardEngine setOption:@YES forType:kPanoWBOptionShowRemoteCursor]; // 显示其他用户的光标位置

UI 交互

通过 PanoRtcWhiteboard 实例的 - setOption:forType: 方法，type 参数设置为 kPanoWBOptionEnableUIResponse，option 参数设置为带 BOOL 值的 NSNumber 来设置白板是否响应 UI 交互事件。
默认启用，如果 option 传入 @NO 则白板不再响应任何 UI 交互，既不能移动和缩放，也不能使用任何工具。

[self.whiteboardEngine setOption:@NO forType:kPanoWBOptionEnableUIResponse]; // 关闭白板 UI 交互

隐藏画板内容

通过 PanoRtcWhiteboard 实例的 - setOption:forType: 方法，type 参数设置为 kPanoWBOptionShowDraws，option 参数设置为带 BOOL 值的 NSNumber 来隐藏或显示白板图形（不影响背景图片和动态课件）。

[self.engineKit setOption:@YES forType:kPanoWBOptionShowDraws]; // @YES: 显示(默认值)，@NO: 隐藏

清除画板内容

白板的层级结构为：白板 -> 文档 -> 页面。

通过 PanoRtcWhiteboard 实例的 - clearDocContents:withType: 清除指定文档的内容(此方法需要管理员权限)。

// 管理员清除指定文档的所有内容
[self.whiteboardEngine clearDocContents:@"12345" withType:kPanoWBClearAll];

通过 PanoRtcWhiteboard 实例的 - clearContents:withType: 方法清除当前文档的画板内容(此方法需要管理员权限)。

// 管理员清除当前文档所有页面的所有内容
[self.whiteboardEngine clearContents:NO withType:kPanoWBClearAll];

通过 PanoRtcWhiteboard 实例的 - clearUserContents:currentPage:withType: 方法清除当前文档中特定用户的画板内容。
所有用户都可以清除自己的内容，清除其他用户的内容需要管理员权限。

// 管理员清除当前文档中特定用户添加的图形
[self.whiteboardEngine clearUserContents:12345 currentPage:NO withType:kPanoWBClearDraws];

关闭/离开白板

通过 PanoRtcWhiteboard 实例的 - close 方法关闭白板（仅关闭当前用户的白板 UI）。

[self.whiteboardEngine close];

通过 PanoRtcWhiteboard 实例的 - leave 方法离开白板（关闭当前用户的白板 UI，并且断开白板服务）。

[self.whiteboardEngine leave];

高级功能

请 点此查看 iOS 白板的高级功能介绍。

SDK API 指南

更多白板 SDK 接口，请 点此查看 API 列表。

示例代码

为方便开发者了解丰富的接口使用方式，我们还提供示例代码，请体验参考：

Last updated on 2022/4/8
← Windows (C++)Android (Java) →