实现流程

---

1 导读

1.1 概念解释

• ZegoExpress-Video SDK：ZEGO 音视频互动 SDK，能够提供互动白板所需的实时信令传输的能力。互动白板 SDK 必须搭配此 SDK 使用。
• 互动白板 SDK、ZegoWhiteboardView SDK：均指提供 ZEGO 互动白板服务（ZegoWhiteboard） 的 SDK。
• ZegoWhiteboardView：在代码实现过程中，开发者直接使用的 ZegoWhiteboardView 视图。
• 白板：ZegoWhiteboardView SDK 提供的存储于服务器上的白板 Model，用户可以通过该 Model 访问白板的各种信息，包括通过该 Model 创建 ZegoWhiteboardView。

1.2 文档说明

本文分为两部分来介绍 ZegoWhiteboardView SDK：

1. 创建白板并使用基本功能：从实现一个简单的白板开始，演示引入 SDK、登录房间、创建 ZegoWhiteboardView、展示 ZegoWhiteboardView、使用涂鸦工具、与其他用户同步白板内容的基础流程。
2. 获取已创建的白板并展示：
   • 进入一个存在多个白板的房间时，如何获取已有的 ZegoWhiteboardView 列表，并正确地展现在界面上；
   • 当其他用户新增、删除白板时，本地如何正确处理视图。

2 前提条件

• 已在 ZEGO 控制台 创建项目，并申请有效的 AppID 和 AppSign，详情请参考 控制台 - 项目管理 中的“项目信息”。

• 在项目中集成 ZegoWhiteboardView SDK，详情请参考 快速开始 - 集成。

3 创建白板并使用基本功能

3.1 引入并初始化 SDK

3.1.1 引入头文件

开发者在工程中引入头文件。

// 引入 ZegoExpress-Video SDK 头文件
#import <ZegoExpressEngine/ZegoExpressEngine.h>
// 引入 ZegoWhiteboardView SDK 头文件
#import <ZegoWhiteboardView/ZegoWhiteboardView.h>

3.1.2 初始化 ZegoExpress-Video SDK

初始化 ZegoExpress-Video SDK，详情可参考实时音视频的 快速开始 - 实现流程。

/**
* appID:ZEGO 为开发者签发的应用 ID，请从 ZEGO 控制台 https://console-express. 
* zego.im 申请，取值范围为 0~4294967295。
* appSign: ZEGO 为开发者签发的应用 appSign，请从 ZEGO 控制台 https://console-express.  zego.im 申请
* scenario: 所属的应用场景,ZegoScenarioDefault为通用场景，请根据实际情况选择合适的场景
*/
ZegoEngineProfile *profile = [[ZegoEngineProfile alloc] init];
profile.appID = <#appID#>;
profile.appSign = <#appSign#>;
profile.scenario = ZegoScenarioDefault;
// 创建引擎，并注册 self 为 eventHandler 回调。不需要注册回调的话，eventHandler 参数可以传 nil，后续可调用 "-setEventHandler:" 方法设置回调
[ZegoExpressEngine createEngineWithProfile:profile eventHandler:self];

3.1.3 初始化 ZegoWhiteboardView SDK

1. 使用 ZegoWhiteboardManager 的 initWithCompleteBlock 接口初始化 ZegoWhiteboardView SDK。

如果回调 completeBlock 中的 “errorCode” 为 0，代表初始化成功，可进行更多操作。errorCode 可参考 常见错误码。

[[ZegoWhiteboardManager sharedInstance] initWithCompleteBlock:^(ZegoWhiteboardViewError errorCode) {
     // errorCode = 0 代表初始化成功
}];

2. 监听 ZegoWhiteboardView SDK 回调。

设置 ZegoWhiteboardManager 的代理，监听常用回调事件： [[ZegoWhiteboardManager sharedInstance] setDelegate:self]。 建议关注以下事件：

// 当房间内其他用户创建新的ZegoWhiteboardView的时，会收到新增ZegoWhiteboardView的回调
// 用户可以将新增的 whiteboardView 添加到视图中
- (void)onWhiteboardAdd:(ZegoWhiteboardView *)whiteboardView;

// 当房间内其他用户删除 ZegoWhiteboardView 时，会收到 ZegoWhiteboardView 移除的回调
// 用户可以根据 whiteboardID 移除相应的 ZegoWhiteboardView
- (void)onWhiteboardRemoved:(ZegoWhiteboardID)whiteboardID;

3.2 登录房间

调用 ZegoExpressEngine 的 loginRoom 接口，传入房间 ID 参数 “roomID” 和用户参数 “user”，登录房间。

错误码详情请参考 登录房间错误码 。

- (void)loginRoom {
    // roomID 由您本地生成,需保证 “roomID” 全局唯一。不同用户要登录同一个房间才能进行通话
    NSString *roomID = @"room1";

    // 创建用户对象，ZegoUser 的构造方法 userWithUserID 会将 “userName” 设为与传的参数 “userID” 一样。“userID” 与 “userName” 不能为 “nil”，否则会导致登录房间失败。
    // userID 由您本地生成,需保证 “userID” 全局唯一。
    ZegoUser *user = [ZegoUser userWithUserID:@"user1"];

    // 只有传入 “isUserStatusNotify” 参数取值为 “true” 的 ZegoRoomConfig，才能收到 onRoomUserUpdate 回调。
    ZegoRoomConfig *roomConfig = [[ZegoRoomConfig alloc] init];
    roomConfig.isUserStatusNotify = YES;
    // 登录房间
    [[ZegoExpressEngine sharedEngine] loginRoom:roomID user:user config:roomConfig callback:^(int errorCode, NSDictionary * _Nullable extendedData) {
        // (可选回调) 登录房间结果，如果仅关注登录结果，关注此回调即可
        if (errorCode == 0) {
            NSLog(@"房间登录成功");
        } else {
            // 登录失败，请参考 errorCode 说明 https://doc-zh.zego.im/article/4377
            NSLog(@"房间登录失败");
        }
    }];
}

3.3 创建 ZegoWhiteboardView

1. 初始化 ZegoWhiteboardViewModel，设置属性。
   • aspectWidth，aspectHeight，roomID，name 四个属性为必填项。如下示例代码中创建宽高比为 16：9，横向有 5 页的 ZegoWhiteboardView。
   • roomID 需要和登录房间时的 roomID 一致。

// 创建白板模型
ZegoWhiteboardViewModel *model = [[ZegoWhiteboardViewModel alloc] init];
model.aspectWidth = 16.0 * 5; // 希望创建的白板的等比宽，如果我们创建超过一页的白板，需要乘以相应页数的倍数
model.aspectHeight = 9.0; // 希望创建的白板的等比高
model.roomID = @"123456"; // 传入房间ID，便于接收端判断
model.name = @"白板";

2. 调用 createWhiteboardView 接口创建 ZegoWhiteboardView。

创建成功之后，同一房间内的其他用户会收到 onWhiteboardAdd 的代理回调。

[[ZegoWhiteboardManager sharedInstance] createWhiteboardView:model completeBlock:^(ZegoWhiteboardViewError errorCode, ZegoWhiteboardView *whiteboardView) {
   whiteboardView.frame = CGRectMake(0, 0, 500, 300);
   [self.view addSubView: whiteboardView];
}];

3. 展示 ZegoWhiteboardView

将 completeBlock 回调中获取的 whiteboardView 设置 frame，并添加到视图中，即可展示 ZegoWhiteboardView。

whiteboardView.frame = CGRectMake(0, 0, 500, 300);
[self.view addSubView: whiteboardView];

3.4 体验 ZegoWhiteboardView SDK 的基本功能

3.4.1 设置绘图工具

1. 开启 ZegoWhiteboardView 的绘制功能。

• 将 setWhiteboardOperationMode 设置为 ZegoWhiteboardOperationModeDraw，即可开启 ZegoWhiteboardView 的绘制功能并同时关闭滚动功能。
• 将 setWhiteboardOperationMode 设置为 ZegoWhiteboardOperationModeScroll，时会关闭绘制功能并同时打开滚动功能。

[currentWhiteboardView setWhiteboardOperationMode:ZegoWhiteboardOperationModeDraw]

2. 设置绘制工具类型。

设置 ZegoWhiteboardManager 类的 toolType 属性可修改 ZegoWhiteboardView 的工具类型，目前支持 10 种工具。

ZegoWhiteboardViewToolNone ,     // 未选择
ZegoWhiteboardViewToolPen ,    // 涂鸦画笔
ZegoWhiteboardViewToolText ,    // 文本
ZegoWhiteboardViewToolLine ,    // 直线
ZegoWhiteboardViewToolRect ,    // 矩形
ZegoWhiteboardViewToolEllipse , // 圆
ZegoWhiteboardViewToolSelector ,// 选取图元
ZegoWhiteboardViewToolEraser ,  // 橡皮擦
ZegoWhiteboardViewToolLaser ,   // 激光笔
ZegoWhiteboardViewToolCustomImage    // 自定义图形工具

3. 将工具设置为 ZegoWhiteboardViewToolPen 涂鸦画笔。

// 设置白板工具为画笔
[ZegoWhiteboardManager sharedInstance].toolType = ZegoWhiteboardViewToolPen;
[ZegoWhiteboardManager sharedInstance].brushColor = [UIColor redColor]; // 画笔颜色，默认为红色
[ZegoWhiteboardManager sharedInstance].brushSize = 10; // 画笔粗细，默认为 16

设置涂鸦画笔成功后，用手指在 whiteboardView 的范围内按下移动，即可看到涂鸦效果展示在 whiteboardView 上。

4. 可针对画笔设置自定义光标。

ZEGO SDK 已内置画笔图标，开发者可通过 setCustomCursorAttribute 设置画笔的光标样式。

// 关闭自定义光标（默认为开启状态） 
[ZegoWhiteboardManager sharedInstance].enableCustomCursor = NO;

// 开启自定义光标
[ZegoWhiteboardManager sharedInstance].enableCustomCursor = YES;

// 关闭显示远程自定义光标（默认为开启状态）
[ZegoWhiteboardManager sharedInstance].enableRemoteCursorVisible = NO;

// 开启显示远程自定义光标
[ZegoWhiteboardManager sharedInstance].enableRemoteCursorVisible = YES;

// 设置自定义光标
ZegoWhiteboardCursorAttribute * attribute = [ZegoWhiteboardCursorAttribute new];
attribute.iconPath = @"https://xxxxxxxx.com/xxx.png";  // 请使用正确的图片地址
attribute.offsetX = 0;  // 自定义光标作用点，绘制点作用在图片指定 x 偏移方向，默认为 0，不可超出图片宽度
attribute.offsetY = 0;  // 自定义光标作用点，绘制点作用在图片指定 y 偏移方向，默认为 0，不可超出图片高度
// currentWhiteboardView 为当前使用的白板
[currentWhiteboardView setCustomCursorAttribute:ZegoWhiteboardViewCursorTypePen cursorAttribute:attribute complete:nil];

3.4.2 同步 ZegoWhiteboardView 上的内容

不同用户只要加入同一个房间，通过 getWhiteboardListWithCompleteBlock 获取到 ZegoWhiteboardView 列表，并将 ZegoWhiteboardView 添加到界面中，即可观察到 ZegoWhiteboardView 上的图元和位置的同步情况。

3.4.3 滚动 ZegoWhiteboardView

调用 scrollToHorizontalPercent 方法使 ZegoWhiteboardView 滚动到相应位置。

• horizontalPercent 表示水平位置百分比，取值范围：0 ～ 1.0；
• verticalPercent 表示垂直位移百分比，取值范围：0 ～ 1.0。

CGFloat horizontalPercent = 0.5; // 水平位置百分比 
CGFloat verticalPercent = 0; // 垂直位置百分比
[self scrollToHorizontalPercent:horizontalPercent
                  verticalPercent:verticalPercent
                  completionBlock:nil];

3.4.4 移除白板

调用 ZegoWhiteboardManager 类的 destroyWhiteboardID 接口移除白板。

移除成功之后，同一房间内的用户会收到 - (void)onWhiteboardAdd:(ZegoWhiteboardView *)whiteboardView 的代理回调。

 [[ZegoWhiteboardManager sharedInstance] destroyWhiteboardID:whiteboardID completeBlock:^[(ZegoWhiteboardViewError errorCode, ZegoWhiteboardID whiteboardID) {
    // 白板移除成功后，可根据 whiteboardID 移除相应的 ZegoWhiteboardView
   if (errorCode == ZegoWhiteboardViewSuccess) {
           [self.whiteboardView removeFromSuperview];
   }
}];

4 获取已创建的白板并展示

4.1 初始化

请参考 3.1 引入并初始化 SDK 和 3.2 登录房间 初始化 ZegoWhiteboardView SDK 并登录房间。

4.2 获取房间内已创建的 ZegoWhiteboardView 列表

调用 ZegoWhiteboardManager 的 getWhiteboardListWithCompleteBlock 接口获取房间内已创建的 ZegoWhiteboardView 列表。

用户可以将获取到的 ZegoWhiteboardView 直接添加到界面上展示，用户可通过 ZegoWhiteboardView 的 whiteboardModel 属性获取白板信息。

// 获取房间内已创建的 ZegoWhiteboardView 列表
[[ZegoWhiteboardManager sharedInstance] getWhiteboardListWithCompleteBlock:^(ZegoWhiteboardViewError errorCode, NSArray *whiteBoardList) {
        // 遍历返回的 ZegoWhiteboardView 列表，用户可直接添加到界面中, 或者保存起来按需使用
         for (ZegoWhiteboardView *whiteBoardView in whiteBoardList) {
                 whiteBoardView.frame = CGRectMake(0, 0, 500, 300);
                 [self.view addSubview:whiteBoardView];
                [self.whiteboardViewList addObject:whiteBoardView];
    }
}];

4.3 关注白板的代理回调

开发者可以根据需要，关注白板新增和删除时的代理回调。关注回调前，必须保证设置了 ZegoWhiteboardManager 的代理：[[ZegoWhiteboardManager sharedInstance] setDelegate:self];

1. 在白板新增时，展示最新的 ZegoWhiteboardView。

// 当房间内其他用户创建新的ZegoWhiteboardView的时，会收到新增ZegoWhiteboardView的回调
// 用户可以将新增的 whiteboardView 添加到视图中
- (void)onWhiteboardAdd:(ZegoWhiteboardView *)whiteboardView {
        whiteBoardView.frame = CGRectMake(0, 0, 500, 300);
         [self.view addSubview:whiteBoardView];
        [self.whiteboardViewList addObject:whiteBoardView];
}

2. 在白板移除时，移除相应的 ZegoWhiteboardView。

// 当房间内其他用户删除 ZegoWhiteboardView 时，会收到 ZegoWhiteboardView 移除的回调
// 用户可以根据 whiteboardID 移除相应的 ZegoWhiteboardView
- (void)onWhiteboardRemoved:(ZegoWhiteboardID)whiteboardID {
        for (NSInteger i = 0; i < self.whiteboardViewList.count; i++) {
        ZegoWhiteboardView *whiteboardView = self.whiteboardViewList[i];
        if (whiteboardView.whiteboardModel.whiteboardID == whiteboardID) {
            [self.whiteboardViewList removeObjectAtIndex:i];
            [whiteboardView removeFromSuperview];
            i--;
        }
    }
}

5 示例源码

开发者可以在互动白板示例项目中，体验互动白板业务，并查看完整的源码和代码逻辑，详情请参考 互动白板 - 下载示例源码。

相关文档

• 白板创建成功后，调用翻页接口不生效？
• 如何设置日志？
• 为什么设置转码清晰度后，没有立马生效，重新渲染也没有生效？
• 如何处理白板或文件显示不完整或留白的问题？
• 互动白板的生命周期是什么样的？