实现流程

---

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、登录房间、初始化白板 SDK、创建 ZegoWhiteboardView、展示 ZegoWhiteboardView、使用涂鸦工具、与其他用户同步白板内容的基础流程。
2. 获取已创建的白板并展示：
   • 进入一个存在多个白板的房间时，如何获取已有的 ZegoWhiteboardView 列表，并正确地展现在界面上；
   • 当其他用户新增、删除白板时，本地如何正确处理视图。

2 前提条件

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

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

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

3.1 初始化 SDK

3.1.1 初始化 ZegoExpress-Video SDK

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

// 创建引擎，通用场景接入，并注册 self 为 eventHandler 回调
// 不需要注册回调的话，eventHandler 参数可以传 null，后续可调用 "setEventHandler:" 方法设置回调
ZegoEngineProfile profile = new ZegoEngineProfile();
profile.appID = ;  // 请通过官网注册获取，格式为：1234567890L
profile.appSign = ; // 请通过官网注册获取，格式为字符串
profile.scenario = ZegoScenario.DEFAULT;  // 通用场景接入，请根据实际情况选择合适的场景
profile.application = getApplication();
engine = ZegoExpressEngine.createEngine(profile, null);

3.1.2 初始化 ZegoWhiteboardView SDK

1. 使用 ZegoWhiteboardManager 的 init 方法初始化 ZegoWhiteboardView SDK。

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

ZegoWhiteboardManager.getInstance().init(context, new IZegoWhiteboardInitListener() {
    @Override
    public void onInit(int errorCode) {
        if (errorCode == 0) {
            /** 初始化成功 */
        } else {
            /** 初始化失败 */
        }
    }
});

2. 监听白板事件

调用 ZegoWhiteboardManager 的设置监听器，监听常用白板事件： setWhiteboardManagerListener(IZegoWhiteboardManagerListener listener)。 包含以下事件：

// 使用白板过程中的错误回调
// 详细错误码见 ZegoWhiteboardConstants.java
void onError(int errorCode);

// 白板操作权限变更回调
// 该权限用于控制对白板的操作，包括缩放，滚动
void onWhiteboardAuthChanged(HashMap<String,Integer> authInfo) {}

// 图元操作权限变更回调
// 图元操作权限包括创建、删除、移动、更新、清空所有图元
void onWhiteboardGraphicAuthChanged(HashMap<String,Integer> authInfo) {}

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

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

3.2 登录房间

调用 ZegoExpressEngine 的 loginRoom 接口登录房间。

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

//登录房间
void loginRoom() {
    // ZegoUser 的构造方法 public ZegoUser(String userID) 会将 “userName” 设为与传的参数 “userID” 一样。“userID” 与 “userName” 不能为 “null” 否则会导致登录房间失败。
    ZegoUser user = new ZegoUser("user2");

    ZegoRoomConfig roomConfig = new ZegoRoomConfig();
    // 只有传入 “isUserStatusNotify” 参数取值为 “true” 的 ZegoRoomConfig，才能收到 onRoomUserUpdate 回调。
    roomConfig.isUserStatusNotify = true;

    // roomID 由您本地生成,需保证 “roomID” 全局唯一。不同用户要登录同一个房间才能进行通话
    String roomID = "room1";

    // 登录房间
    engine.loginRoom(roomID, user, roomConfig, (int error, JSONObject extendedData)->{
        // 登录房间结果，如果仅关注登录结果，关注此回调即可
        if (error == 0) {
            // 登录成功
            Toast.makeText(this, "登录成功", Toast.LENGTH_LONG).show();
        } else {
            // 登录失败，请参考 errorCode 说明 https://doc-zh.zego.im/article/4378
            Toast.makeText(this, "登录失败，请参考 errorCode 说明 https://doc-zh.zego.im/article/4378", Toast.LENGTH_LONG).show();
        }
    });
}

3.3 创建 ZegoWhiteboardView

1. 初始化 ZegoWhiteboardViewModel，设置属性。

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

// 创建白板模型
ZegoWhiteboardViewModel zegoWhiteboardViewModel = new ZegoWhiteboardViewModel();
zegoWhiteboardViewModel.setAspectHeight(9);    // 希望创建的白板的等比高
zegoWhiteboardViewModel.setAspectWidth(16 * 5);    // 希望创建的白板的等比宽，如果需要创建多页的白板，需要乘以相应的倍数
zegoWhiteboardViewModel.setName("白板1");
zegoWhiteboardViewModel.setPageCount(5);      // 白板的页数
zegoWhiteboardViewModel.setRoomId("123");

2. 调用 createWhiteboardView 接口创建 ZegoWhiteboardView。 创建成功之后，同一房间内的用户会收到 onWhiteboardAdded 的代理回调。

ZegoWhiteboardManager.getInstance().createWhiteboardView(zegoWhiteboardViewModel, new IZegoWhiteboardCreateListener() {
    @Override
    public void onCreate(int errorCode, @Nullable ZegoWhiteboardView whiteboardView) {

    }
});

3. 展示 ZegoWhiteboardView 将 createWhiteboardView 回调中获取的 whiteboardView 添加到视图中，即可展示 ZegoWhiteboardView。

if (errorCode == 0 && zegoWhiteboardView != null) {
        addView(zegoWhiteboardView,LayoutParams(
            ViewGroup.LayoutParams.MATCH_PARENT,
            ViewGroup.LayoutParams.MATCH_PARENT
            )
        )
}

3.4 体验 ZegoWhiteboardView SDK 的基本功能

3.4.1 设置绘图工具

1. 开启 ZegoWhiteboardView 的绘制功能。

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

currentWhiteboardView.setWhiteboardOperationMode(ZegoWhiteboardConstants.ZegoWhiteboardOperationModeDraw)

2. 设置绘制工具类型。
   设置 ZegoWhiteboardManager 类的 setToolType 方法可修改 ZegoWhiteboardView 的工具类型，目前支持 9 种工具。

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

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

int toolType = ZegoWhiteboardConstants.ZegoWhiteboardViewToolPen;
int color = Color.RED;
int size = 4;
/** 设置画笔的类型*/
ZegoWhiteboardManager.getInstance().setToolType(toolType);
/** 设置画笔的颜色*/
ZegoWhiteboardManager.getInstance().setBrushColor(color);
/** 设置画笔的大小*/
ZegoWhiteboardManager.getInstance().setBrushSize(size);

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

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

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

// 关闭自定义光标（默认为开启状态）
ZegoWhiteboardManager.getInstance().enableCustomCursor(false);

// 开启自定义光标 
ZegoWhiteboardManager.getInstance().enableCustomCursor(true);

// 关闭显示远程自定义光标（默认为开启状态）
ZegoWhiteboardManager.getInstance().enableRemoteCursorVisible(false);

// 开启显示远程自定义光标
ZegoWhiteboardManager.getInstance().enableRemoteCursorVisible(true);

// 设置自定义光标
ZegoWhiteboardCursorAttribute attribute = new ZegoWhiteboardCursorAttribute();
attribute.url = url;  // 自定义光标的地址，支持本地地址和网络地址
attribute.pox_x = 10;  // 自定义光标横向偏移量
attribute.pox_y = 10;  // 自定义光标纵向偏移量
// currentWhiteboardView 为当前使用的白板
currentWhiteboardView.setCustomCursorAttribute(
    ZegoWhiteboardViewCursorType.Pen,attribute) { errorCode ->
};

3.4.2 同步 ZegoWhiteboardView 上的内容

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

3.4.3 滚动 ZegoWhiteboardView

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

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

/** 白板滚动  */
float horizontalPercent = 1.0f;
float verticalPercent = 1.0f;
zegoWhiteboardView.scrollTo(horizontalPercent, verticalPercent);

3.4.4 移除白板

调用 ZegoWhiteboardManager 类的 destroyWhiteboardView 方法移除白板。 移除成功之后，同一房间内的用户会收到 onWhiteboardRemoved 的回调通知。

long whiteboardID = 1;
ZegoWhiteboardManager.getInstance().destroyWhiteboardView(whiteboardID, new IZegoWhiteboardDestroyListener() {
    @Override
    public void onDestroy(int errorCode, long whiteboardID) {
        if (errorCode == 0) {
            /** 销毁白板成功*/
        } else {
            /** 销毁白板失败*/
        }
    }
});

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

4.1 初始化

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

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

调用 ZegoWhiteboardManager 的 getWhiteboardViewList 接口获取房间内已创建的 ZegoWhiteboardView 列表。 用户可以将获取到的 ZegoWhiteboardView 直接添加到界面上展示，用户可通过 ZegoWhiteboardView 的 getWhiteboardViewModel 属性获取白板信息。

// 获取房间内已创建的 ZegoWhiteboardView 列表
ZegoWhiteboardManager.getInstance().getWhiteboardViewList(new IZegoWhiteboardGetListListener() {
        @Override
        public void onGetList(int errorCode, ZegoWhiteboardView[] whiteboardViewList) {
            if (errorCode == 0) {
                /** 获取成功 */
            } else {
                /** 获取失败 */
            }
        }
    });

4.3 关注白板的回调

开发者可以根据需要，关注白板新增和删除时的回调。关注回调前，必须保证设置了 ZegoWhiteboardManager 的方法：setWhiteboardManagerListener

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

ZegoWhiteboardManager.getInstance().setWhiteboardManagerListener(new IZegoWhiteboardManagerListener() {
    @Override
    public void onError(int errorCode) {
    }

    @Override
    public void onWhiteboardAdded(ZegoWhiteboardView zegoWhiteboardView) {
        addView(zegoWhiteboardView,LayoutParams(
        ViewGroup.LayoutParams.MATCH_PARENT,
        ViewGroup.LayoutParams.MATCH_PARENT))
    }

    @Override
        public void onWhiteboardRemoved(long whiteboardID) {
        }
});

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

ZegoWhiteboardManager.getInstance().setWhiteboardManagerListener(new IZegoWhiteboardManagerListener() {
    @Override
    public void onError(int errorCode) {
    }

    @Override
    public void onWhiteboardAdded(ZegoWhiteboardView zegoWhiteboardView) {
    }

    @Override
    public void onWhiteboardRemoved(long whiteboardID) {
        removeView(getWhiteboardViewHolder(whiteboardID))
    }
});

5 示例源码

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

相关文档

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