创建超级白板

---

概念解释

• ZegoExpress-Video SDK：ZEGO 音视频互动 SDK，能够提供超级白板所需的实时信令传输的能力。超级白板 SDK 必须搭配此 SDK 使用。
• 超级白板 SDK、ZegoSuperBoard SDK：均指提供 ZEGO 超级白板服务（ZegoSuperBoard） 的 SDK。
• ZegoSuperBoardView：在代码实现过程中，开发者用于展示的白板视图。
• ZegoSuperBoardSubView：ZegoSuperBoardView 的子集，开发者实际创建的 View。ZegoSuperBoardView 会自动呈现最新创建或通过 switchSuperBoardSubView 指定的 ZegoSuperBoardSubView。
• 纯白板：指定宽、高和页数创建的白板，用户在指定的白板画布上进行实时绘制。
• 文件白板：基于文件创建的白板，白板宽高和页数由文件决定，实现在文件上绘制图元的业务需求。

前提条件

• ZegoSuperBoard SDK 需要与 ZegoExpress-Video SDK 搭配使用，请同时集成 ZegoExpress-Video SDK。超级白板 SDK 的压缩包中已经包含 ZegoExpress-Video SDK，无需单独下载。

• 若之前已集成过 ZegoExpress-Video SDK，请升级到最新版本，避免 SDK 版本不匹配造成初始化失败。

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

• 已生成 Token，详情请参考 使用 Token 鉴权。也可以参考 控制台 - 开发辅助，在 ZEGO 控制台获取临时 Token（有效期为 24 小时）。

准备环境

在开始集成 ZegoSuperBoard SDK 前，请确保开发环境满足以下要求：

• 准备一台可以连接到互联网的 Windows 或 macOS 计算机。

• 获取摄像头麦克风等行为需运行在 HTTPS 环境下，集成 SDK 之前，请确保最终项目能够运行在 HTTPS 环境下。开发环境下则可先通过本地运行规避，例如 localhost 或 127.0.0.1。
• 使用 SDK 支持的浏览器，目前 SDK 支持的浏览器版本如下：

集成 SDK

1 下载 SDK

从官网下载 SDK

请参考 下载 SDK 包，下载最新版本的 SDK，下载完成后进行解压。

npm 下载 SDK

需要分别下载 ZegoSuperBoard SDK 和 ZegoExpress-Video SDK。

npm i zego-superboard-web
npm i zego-express-engine-webrtc

2 导入 SDK

从官网下载的 SDK 可使用 script 直接引入，需要分别导入 ZegoSuperBoard SDK 和 ZegoExpress-Video SDK，其中，“x.x.x” 为 ZegoExpress-Video SDK 的版本号，请参考上一步压缩包解压后的文件名。

<script src="ZegoSuperBoardManagerWeb.js"></script>
<script src="ZegoExpressWebRTC-x.x.x.js"></script>

npm 下载的 SDK 可使用下面的方法导入。

import { ZegoSuperBoardManager } from 'zego-superboard-web';
import {ZegoExpressEngine} from 'zego-express-engine-webrtc'
// 或
const ZegoSuperBoardManager = require('zego-superboard-web').ZegoSuperBoardManager;
var ZegoExpressEngine = require('zego-express-engine-webrtc').ZegoExpressEngine

实现超级白板

1 初始化 SDK

初始化 ZegoExpress-Video SDK

创建 ZegoExpressEngine 引擎实例，将申请到的 AppID 传入参数 “appID”，将接入服务器地址传入参数 “server”。

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

初始化 ZegoSuperBoard SDK

1. 使用 ZegoSuperBoardManager 的 getInstance 方法获取 ZegoSuperBoard 实例。
2. 使用 ZegoSuperBoard 实例的 init 方法初始化 ZegoSuperBoard SDK，这里需要传入 ZegoExpressEngine 的引擎实例。

初始化 SDK 需要用于验证身份的 Token，其获取方式请参考 用户权限控制 中的 “4.1 生成 Token”。

<!-- 需要挂载的父容器 -->
<div id="parentDomID"></div>

// 获取 ZegoSuperBoard 实例
zegoSuperBoard = ZegoSuperBoardManager.getInstance();
// 初始化 ZegoSuperBoard，成功则 result 返回 true  
const result = await zegoSuperBoard.init(zg, {
    parentDomID: 'parentDomID', // 需要挂载的父容器 ID
    appID: 0, // 申请到的 AppID
    userID: '', // 用户自定义生成的用户 ID
    token: '' // 登录房间需要用于验证身份的 Token
});

2 监听事件回调

根据实际应用需要，在初始化 SuperBoard 后监听想要关注的事件回调，比如错误提醒、远端新增白板文件、远端删除白板文件、远端切换白板文件等。

on: 注册回调事件，通过 event 指定监听事件名。

// 常用的 SuperBoard 相关回调
// SuperBoard 自动实现了多端同步能力，远端通知回调内只需刷新本地UI逻辑即可。
// 监听错误回调，SDK 内部错误均通过此回调抛出，除了直接在接口中直接返回的错误外
zegoSuperBoard.on('error', function(errorData) {
    // 错误码，错误提示语
    console.log(errorData.code, errorData.message)
});

// 监听白板翻页、滚动
zegoSuperBoard.on('superBoardSubViewScrollChanged', function(uniqueID, page, step) {

});
// 监听远端白板缩放
zegoSuperBoard.on('superBoardSubViewScaleChanged', function(uniqueID, scale) {

}); 

// 监听远端新增白板
zegoSuperBoard.on('remoteSuperBoardSubViewAdded', function(uniqueID) {

});

// 监听远端销毁白板
zegoSuperBoard.on('remoteSuperBoardSubViewRemoved', function(uniqueID) {

});

// 监听远端切换白板
zegoSuperBoard.on('remoteSuperBoardSubViewSwitched', function(uniqueID) {

});

// 监听远端切换 Excel Sheet
zegoSuperBoard.on('remoteSuperBoardSubViewExcelSwitched', function(uniqueID, sheetIndex) {

});

// 监听远端白板权限变更
zegoSuperBoard.on('remoteSuperBoardAuthChanged', function(data) {
    console.log(data.scale, data.scroll)
});

// 监听远端白板图元权限变更
zegoSuperBoard.on('remoteSuperBoardGraphicAuthChanged', function(data) {        
    console.log(data.create, data.delete, data.move, data.update, data.clear)
});

3 登录房间

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")
     }
});

4 创建白板

超级白板支持创建纯白板和文件白板。

• 纯白板：指定宽、高和页数创建的白板，用户在指定的白板画布上进行实时绘制。
• 文件白板：基于文件创建的白板，白板宽高和页数由文件决定，实现在文件上绘制图元的业务需求。

您可以通过 roomStateUpdate 回调接口，实时接收房间和服务器之间的连接状态变化。仅当房间状态是连接成功时，才能进行创建白板等操作。

• 创建纯白板

// 上一步的登录房间成功，返回 true 后才可创建白板
const model = await zegoSuperBoard.createWhiteboardView({
    name: '', // 白板名称
    perPageWidth: 1600, // 白板每页宽度
    perPageHeight: 900, // 白板每页高度
    pageCount: 5 // 白板页数
});

• 创建文件白板

创建文件白板前需要先获取文件的 fileID，可参考 共享文件管理 进行上传。

// 上一步的登录房间成功，返回 true 后才可创建白板
const model = await zegoSuperBoard.createFileView({
    fileID // 文件的 fileID，在上传文件成功后返回的唯一文件标识
});

5 挂载当前白板

// 获取 SuperBoardSubViewList
const superBoardSubViewList = await zegoSuperBoard.querySuperBoardSubViewList();

// 获取 SuperBoardView
const superBoardView = zegoSuperBoard.getSuperBoardView();

// 获取当前 SuperBoardSubView
const zegoSuperBoardSubView = superBoardView.getCurrentSuperBoardSubView()

// 获取 SuperBoardSubView 对应 model
const model = zegoSuperBoardSubView.getModel();

// 获取当前需要挂载白板的 uniqueID
const uniqueID = model.uniqueID;

// 判断文件类型，如果是 Excel 白板，需要先获取到 sheetIndex
let sheetIndex;
const fileType = model.fileType;
if (fileType === 4) {
    // Excel 白板
    const sheetName = zegoSuperBoardSubView.getCurrentSheetName();
    // 获取当前 Excel 对应的 Sheet 列表
    const zegoExcelSheetNameList = zegoSuperBoardSubView.getExcelSheetNameList();
    // 通过 sheetName 从 zegoExcelSheetNameList 中获取到对应的 sheetIndex
    sheetIndex = zegoExcelSheetNameList.findIndex(function(element, index) {
        return element === sheetName;
    });
}

// 挂载当前白板
const result = await superBoardView.switchSuperBoardSubView(uniqueID, sheetIndex);

6 验证白板创建

运行上述项目的多个实例，登录同一房间ID。用鼠标在任一窗口的 ZegoSuperBoardView 的范围内按下移动，即可看到涂鸦效果展示在各个窗口的 ZegoSuperBoardView 上。

7 销毁白板

// 销毁后SDK内部会自动切换到另外一个白板。展示的白板为销毁白板的上一个
const result = await zegoSuperBoard.destroySuperBoardSubView(uniqueID)

8 离开房间

调用 ZegoExpressEngine 的 logoutRoom 接口退出房间。

zg.logoutRoom(roomID);

9 反初始化 SDK

反初始化 ZegoSuperBoard SDK

调用 ZegoSuperBoardManager 的 unInit，反初始化 ZegoSuperBoard SDK。

zegoSuperBoard.unInit();

反初始化 ZEGO Express Video SDK

如果无需再使用 ZEGO Express Video SDK 的能力，即可调用 ZegoExpressEngine 的 destroyEngine 销毁引擎，释放麦克风、摄像头、内存、CPU 等资源。

 zg.destroyEngine();