实现流程

---

1 导读

1.1 概念解释

• 互动白板 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，详情请参考 控制台 - 项目管理 中的“项目信息”。
• 在项目中集成 ZegoWhiteboardView SDK，详情请参考 快速开始 - 集成。
• 已生成 Token，详情请参考 使用 Token 鉴权。也可以参考 控制台 - 开发辅助，在 ZEGO 控制台获取临时 Token（有效期为 24 小时）。

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

3.1 初始化 SDK

1. 初始化 ZegoWhiteboardView SDK

ZegoWhiteboardView SDK 包含了 ZEGO 实时音视频功能，其初始化方法与 ZegoExpress-Video SDK 一致。

• 如果开发者项目中没有集成过 ZegoExpress-Video SDK, 下载并初始化 ZegoWhiteboardView SDK 后，即可实现互动白板和实时音视频功能。
• 如果开发者项目中已经集成了 ZegoExpress-Video SDK，在后续需要集成互动白板功能时，可先去除该 SDK，直接下载和使用 ZegoWhiteboardView SDK。

方法一：从官网下载 SDK，手动集成 SDK 的初始化。

<script src="ZegoExpressWhiteboardWeb.js"></script>

/**
 * appID 为应用ID，请从 ZEGO 控制台-https://console.zego.im/ 获取
 * server 为接入服务器地址，请从 ZEGO 控制台-https://console.zego.im/ 获取
*/

// 初始化实例
const zegoExpressEngine = new window.ZegoExpressEngine(appID, server);

方法二：使用 npm 获取 SDK 时的初始化。

import { ZegoExpressEngine } from 'zego-express-whiteboard-web';
/**
 * appID 为应用ID，请从 ZEGO 控制台-https://console.zego.im/ 获取
 * server 为接入服务器地址，请从 ZEGO 控制台-https://console.zego.im/ 获取
*/
// 初始化实例
const zegoExpressEngine = new ZegoExpressEngine(appID, server);

2. 监听回调

调用 on 方法，传入监听事件名，监听常用回调事件： zegoExpressEngine.on(zegoEventName: ZegoEvent, callBack)。 ZegoEventName 可参考 ZegoEvent。

建议关注以下事件：

// 当房间内其他用户创建新的 zegoWhiteboardView 的时，会收到新增 zegoWhiteboardView 的回调
zegoExpressEngine.on('viewAdd', function(zegoWhiteboardView){
 // 用户可以将新增的 zegoWhiteboardView 添加到视图中
})

// 当房间内其他用户删除 zegoWhiteboardView 时，会收到 zegoWhiteboardView 移除的回调
zegoExpressEngine.on('viewRemoved', function(whiteboardID){
 // 用户可以根据 whiteboardID 移除自己维护的相应的 zegoWhiteboardView 列表
})

3.2 登录房间

1. 生成 Token

调用 ZegoExpressEngine 的 loginRoom 接口登录房间。登录时，请传入本文 前提条件 所获取到的 Token 进行鉴权。

注意：临时 Token 仅供调试，正式上线时，请从开发者的业务服务器生成 token，详情可参考 使用 Token 鉴权。如果 Token 错误，请参考 错误码 文档中的 1002067 和 1003072 排查问题。

2. 登录房间

调用 loginRoom 接口，传入房间 ID 参数 “roomID”、“token” 和用户参数 “user”，根据实际情况传入参数 “config”，登录房间。

// 登录房间，成功则返回 true
// userUpdate 设置为 true 才能收到 roomUserUpdate 回调。

let userID = Util.getBrow() + '_' + new Date().getTime();
let userName = "user0001";
let roomID = "0001";
let token = ;
// 为避免错过任何通知，您需要在登录房间前先监听用户加入/退出房间、房间连接状态变更、推流状态变更等回调。
zg.on('roomStateChanged', async (roomID, reason, errorCode, extendedData) => {

})
zg.loginRoom(roomID, token, { userID, userName: userID }, { userUpdate: true }).then(result => {
     if (result == true) {
        console.log("login success")
     }
});

3.3 创建 ZegoWhiteboardView

1. 调用 createView 接口创建白板。如下示例代码中创建宽为 1600 px，高为 900 px，横向有 5 页的 ZegoWhiteboardView。

zegoExpressEngine.createView({
    roomID: '登录房间号',
    name: '白板名称',
    aspectWidth: 1600 * 5,
    aspectHeight: 900,
    pageCount: 5,
    fileInfo?: {
        fileID: '文件ID',
        fileName: '文件名',
        fileType: '文件类型',
        authKey: ''
    }
}).then(view => {
    const zegoWhiteboardView = view;
});

fileInfo 参数解释：

创建成功之后，同一房间内的其他用户会收到 viewAdd 的监听回调。

2. 展示 ZegoWhiteboardView

   1. 在 Html 中添加一个容器 div。

      <div id="parent" style="width:1600px;height:900px"> </div>

   2. 调用 attachView 接口，将获取的 zegoWhiteboardView，添加到视图中，即可展示 zegoWhiteboardView。

      zegoExpressEngine.attachView(zegoWhiteboardView: ZegoWhiteboardView,parent: string): Promise<void>

3.4 体验 ZegoWhiteboardView SDK 的基本功能

3.4.1 设置绘图工具

1. 开启 setWhiteboardOperationMode 的绘制功能。

zegoWhiteboardView.setWhiteboardOperationMode(operationMode: ZegoWhiteboardOperationMode): void

operationMode 参数解释：

2. 设置绘制工具类型。

通过 setToolType 接口来设置当前白板使用的工具类型及特性，目前支持 10 种白板工具。

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

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

// 设置白板工具为画笔，画笔颜色，默认为 #f54326，画笔粗细，默认为 6
zegoWhiteboardView.setToolType(1)

设置涂鸦画笔成功后，在 zegoWhiteboardView 的范围内按下使用鼠标涂鸦，即可看到涂鸦效果展示在 zegoWhiteboardView 上。

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

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

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

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

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

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

// 设置自定义光标样式
zegoExpressEngine.setCustomCursorAttribute(1, {
    iconPath: 'FILE',  // 自定义光标的地址，支持本地地址和网络地址
    offsetX: 0,  // 自定义光标横向偏移量
    offsetY: 0  // 自定义光标纵向偏移量
})

3.4.2 同步 ZegoWhiteboardView 上的内容

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

// 1. 加入同一房间后，请求获取该房间内的白板列表
var zegoWhiteboardViewList = []
zegoExpressEngine.getViewList().then(res=>{
    zegoWhiteboardViewList = res
})

// 2. 假设进房的用户需要加载指定白板，该白板ID 为 1
var targetWhiteboardID = 1

// 3. 根据筛选条件，从白板列表中过滤得到目标白板
zegoWhiteboardView = zegoWhiteboardViewList.filter(function (v) {
    return targetWhiteboardID === v.getID();
})[0];

// 4. 将获取到到目标白板渲染
zegoExpressEngine.attachView(zegoWhiteboardView, parentId)

3.4.3 滚动 ZegoWhiteboardView

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

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

zegoWhiteboardView.scroll(horizontalPercent: number,verticalPercent: number): boolean

3.4.4 移除白板

调用 destroyView 接口移除白板。移除成功之后，同一房间内的用户会收到 viewRemoved 的回调。

zegoExpressEngine.destroyView(zegoWhiteboardView: ZegoWhiteboardView): Promise<void>

zegoExpressEngine.on('viewRemoved', function(whiteboardID){
 // 用户可以根据 whiteboardID 移除自己维护的相应的 zegoWhiteboardView 列表
})

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

4.1 初始化

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

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

调用 getViewList 接口获取白板列表。

zegoExpressEngine.getViewList(): Promise<ZegoWhiteboardView[]>

4.3 关注白板的回调

开发者可以根据需要，关注白板新增和删除时的监听回调。

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

// 当房间内其他用户创建新的 zegoWhiteboardView 的时，会收到新增 zegoWhiteboardView 的回调
zegoExpressEngine.on('viewAdd', function(zegoWhiteboardView){
 // 用户可以将新增的 zegoWhiteboardView 添加到视图中
})

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

// 当房间内其他用户删除 zegoWhiteboardView 时，会收到 zegoWhiteboardView 移除的回调
zegoExpressEngine.on('viewRemoved
', function(whiteboardID){
 // 用户可以根据 whiteboardID 移除自己维护的相应的 zegoWhiteboardView 列表
})

5 示例源码

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

相关问题

• 白板创建成功后，调用翻页接口不生效？
• 为什么各端看到的白板或者文件内容不同步？
• 如何处理白板或文件显示不完整或留白的问题？
• 如何解决 Web 平台互动白板 SDK 登录失败的问题？
• 互动白板的生命周期是什么样的？
• 互动白板 SDK 是否支持快捷键操作？