互动白板
  • iOS
  • Android : Java
  • macOS
  • Windows
  • Web
  • Electron
  • 概述
  • 价格说明
  • 下载
  • 跑通示例源码
  • 接入指南
  • 快速开始
  • 场景实践
  • 客户端 API
  • 服务端 API
  • 常见错误码
  • 常见问题
  • 文档中心
  • 互动白板
  • 快速开始
  • 实现流程

实现流程

更新时间:2023-11-02 17:35

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 前提条件

2.3.0 或以上 版本的 SDK 支持 Token 鉴权,若您需要升级鉴权方式,可参考 如何从 AppSign 鉴权升级为 Token 鉴权

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

3.1 初始化 SDK

必须先保证 ZegoExpress-Video SDK 初始化成功,再初始化 ZegoWhiteboardView 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);

如果您需要切换鉴权方式,请参考 如何从 AppSign 鉴权升级为 Token 鉴权

3.1.2 初始化 ZegoWhiteboardView SDK

  1. 使用 ZegoWhiteboardManagerinit 方法初始化 ZegoWhiteboardView SDK。

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

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

调用 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 登录房间

调用 ZegoExpressEngineloginRoom 接口登录房间。

  1. 需保证 “roomID” 信息的全局唯一。
  2. “userID” 与 “userName” 不能为 “null” 否则会导致登录房间失败。
  3. ZegoUser 的构造方法 public ZegoUser(String userID) 会将 “userName” 设为与传的参数 “userID” 一样。
  4. 每个 “userID” 必须唯一,建议设置成一个有意义的值,开发者可将 “userID” 与自己业务账号系统进行关联。

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

//登录房间
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");
  1. 调用 createWhiteboardView 接口创建 ZegoWhiteboardView。 创建成功之后,同一房间内的用户会收到 onWhiteboardAdded 的代理回调。
ZegoWhiteboardManager.getInstance().createWhiteboardView(zegoWhiteboardViewModel, new IZegoWhiteboardCreateListener() {
    @Override
    public void onCreate(int errorCode, @Nullable ZegoWhiteboardView whiteboardView) {

    }
});
  1. 展示 ZegoWhiteboardView 将 createWhiteboardView 回调中获取的 whiteboardView 添加到视图中,即可展示 ZegoWhiteboardView。
if (errorCode == 0 && zegoWhiteboardView != null) {
        addView(zegoWhiteboardView,LayoutParams(
            ViewGroup.LayoutParams.MATCH_PARENT,
            ViewGroup.LayoutParams.MATCH_PARENT
            )
        )
}
添加白板view到容器的时候,容器需要设置成预设的宽高,比如 16:9。这样才能设置 match_parent 添加到容器里面去。

3.4 体验 ZegoWhiteboardView SDK 的基本功能

3.4.1 设置绘图工具

  1. 开启 ZegoWhiteboardView 的绘制功能。
currentWhiteboardView.setWhiteboardOperationMode(ZegoWhiteboardConstants.ZegoWhiteboardOperationModeDraw)
  1. 设置绘制工具类型。
    设置 ZegoWhiteboardManager 类的 setToolType 方法可修改 ZegoWhiteboardView 的工具类型,目前支持 9 种工具。
ZegoWhiteboardViewToolNone ,        // 未选择
ZegoWhiteboardViewToolPen ,        // 涂鸦画笔
ZegoWhiteboardViewToolText ,        // 文本
ZegoWhiteboardViewToolLine ,        // 直线
ZegoWhiteboardViewToolRect ,        // 矩形
ZegoWhiteboardViewToolEllipse ,        // 圆
ZegoWhiteboardViewToolSelector ,    // 选取图元
ZegoWhiteboardViewToolEraser ,        // 橡皮擦
ZegoWhiteboardViewToolLaser ,        // 激光笔
ZegoWhiteboardViewToolClick ,        // 点击
ZegoWhiteboardViewToolCustomImage     // 自定义图形
  1. 将工具设置为 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 上。

/Pics/WhiteboardView/scrawl.png

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

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 上的图元和位置的同步情况。

只要用户一直保持登录状态,ZegoWhiteboardView SDK 会自动同步 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 初始化 SDK3.2 登录房间 初始化 ZegoWhiteboardView SDK 并登录房间。

不同的用户需要加入到同一个房间,才能够收到 ZegoWhiteboardView SDK 的各种回调,从而实现互动协同。

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

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

// 获取房间内已创建的 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) {
        }
});
  1. 在白板移除时,移除相应的 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 示例源码

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

相关文档

本篇目录