互动白板与文件共享的搭配使用

---

1 导读

1.1 简介

在实际业务开发过程中，互动白板 (ZegoWhiteboardView SDK）经常与文件共享 (ZegoDocsView SDK) 搭配使用。通常情况下，ZegoWhiteboardView 会覆盖在 ZegoDocsView 之上，然后通过一定的逻辑处理，就能实现在文件上绘制图元的业务需求。

1.2 概念解释

• ZegoWhiteboardView SDK：提供 ZEGO 互动白板服务的 SDK。同时 Web 端 ZegoWhiteboardView SDK 包含了 ZEGO 实时音视频功能，能够提供互动白板所需的实时信令传输的能力。
• ZegoDocsView SDK：提供 ZEGO 文件共享服务 的 SDK。
• ZegoWhiteboardView：在代码实现过程中，开发者直接使用的 ZegoWhiteboardView 视图。
• ZegoDocsView：在代码实现过程中，开发者直接使用的 ZegoDocsView 视图。
• 文件白板：ZegoWhiteboardView 覆盖在 ZegoDocsView 之上组成的视图。
• 普通白板：ZegoWhiteboardView 视图。

2 前提条件

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

• 已在项目中集成 ZegoDocsView SDK，详情请参考文件共享的 快速开始 - 集成。

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

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

3 实现流程

3.1 初始化 SDK

3.1.1 引入 SDK

开发者在工程中引入 ZegoWhiteboardView SDK 和 ZegoDocsView SDK。

方法一：从官网下载 SDK，再通过 <script> 标签引入

// 引入 ZegoWhiteboardView SDK
<script src="ZegoExpressWhiteboardWeb.js"></script>
// 引入 ZegoDocsView SDK
<script src="ZegoExpressDocs.js"></script>

方法二：使用 npm 获取 SDK

import { ZegoExpressEngine } from 'zego-express-whiteboard-web';
import { ZegoExpressDocs } from 'zego-express-docsview-web';
// 或者
const ZegoExpressEngine = require('zego-express-whiteboard-web').ZegoExpressEngine;
const ZegoExpressDocs = require('zego-express-docsview-web').ZegoExpressDocs;

3.1.2 初始化 ZegoWhiteboardView SDK

/**
 * 初始化 ZegoWhiteboardView SDK
 * @param appID 为应用 ID，请从 ZEGO 控制台-https://console.zego.im/ 获取
 * @param server 为接入服务器地址，请从 ZEGO 控制台-https://console.zego.im/ 获取
*/
const zegoExpressEngine = new ZegoExpressEngine(appID, server);

3.1.3 初始化 ZegoDocsView SDK

/**
* 初始化 ZegoExpressDocs SDK
* @param appID 为应用 ID，请从 ZEGO 控制台-https://console.zego.im/ 获取
* @param token 登录验证 token，是通过在 ZEGO 控制台注册项目获得密钥，加上指定算法获得；测试阶段可以通过即构的接口绕过，正式环境一定要用户自己实现
* @param userID 用户 ID，最大 64 字节的字符串。仅支持数字，英文字符和 '~', '!', '@', '#', '$', '', '^', '&', '*', '(', ')', '_', '+', '=', '-', ';', '’', ',', '.'
*/
const zegoExpressDocs = new ZegoExpressDocs({appID, token, userID});

3.2 登录房间

1. 生成 Token

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

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

2. 登录房间

调用 loginRoom 接口，传入房间 ID 参数 “roomID”、“token” 和用户参数 “user”，登录房间。只有登录房间才能实现房间内所有成员的互通。

/**
* 登录房间
* @param roomID 房间 ID，最大长度为 128 字节的字符串。仅支持数字，英文字符和 '~', '!', '@', '#', '$', '', '^', '&', '*', '(', ')', '_', '+', '=', '-', ';', '’', ',', '.', '<', '>', '/'
* @param token 登录验证 token，是通过在 ZEGO 控制台注册项目获得密钥，加上指定算法获得；测试阶段可以通过即构的接口绕过，正式环境一定要用户自己实现
* @param user 登录用户信息
*/
zegoExpressEngine.loginRoom(roomID, token, { userID, userName });

3.3 创建并展示 ZegoDocsView 和 ZegoWhiteboardView

ZegoWhiteboardView 的创建和展示必须要在 ZegoDocsView 展示完成后。

3.3.1 注册文件加载完成回调

只有回调触发才表示当前 ZegoDocsView 上文件已经加载完成，即 ZegoDocsView 已经展示完成。

/**
* 注册 ZegoDocsView 上文件加载完成的回调
* @param 回调方法
*/
zegoExpressDocs.on('onLoadFile', (res) => {
      // step1: 此时 ZegoDocsView 已展示完成

      // step2: 调用下文 3.3.4 中定义的 loadFileCallback 方法创建并展示 ZegoWhiteboardView
        loadFileCallback(res)
})

3.3.2 创建 ZegoDocsView

创建了一个 ZegoDocsView，此时 ZegoDocsView 上还没有文件内容。

<!--Html 中一个容器 div-->
<div id="parent"></div>

/**
* 创建 ZegoDocsView
* @param parent 需要挂载的父容器 ID，父容器定位方式需为相对定位且物理尺寸不为 0
*/
const zegoDocsView = zegoExpressDocs.createView(parent);

3.3.3 展示 ZegoDocsView

在 ZegoDocsView 上加载指定文件。

/**
* 在 ZegoDocsView 上加载指定文件，加载完成会触发上面注册文件的回调
* @param fileID 文件唯一标识 ID，上传源文件转码成功后会返回该 ID
* @param authKey 业务服务与 ZegoDocs 服务约定算法生成的共享鉴权 key。如开启鉴权切鉴权失败，loadFile 将失败。如未开启鉴权，该 key 可为空
*/
zegoDocsView.loadFile(fileID, '');

3.3.4 创建并展示 ZegoWhiteboardView

在 ZegoDocsView 展示完成后开始创建并展示 ZegoWhiteboardView。

// 创建并展示 ZegoWhiteboardView，其中参数 res 为文件加载完成后返回的文件相关信息
function loadFileCallback(res) {
    // 根据文件相关信息创建 ZegoWhiteboardView
    const zegoWhiteboardView = zegoExpressEngine.createView({
        roomID: roomID, // 当前房间 ID
        name: res.fileName,
        aspectWidth: res.width,
        aspectHeight: res.height,
        pageCount: res.pageCount,
        fileInfo: {
            fileID: res.fileID,
            fileName: res.fileName,
            fileType: res.fileType,
            authKey: res.authKey
        }
    }).then(function() {
     // 展示 ZegoWhiteboardView
      zegoExpressEngine.attachView(zegoWhiteboardView, res.viewID);
    });
}

3.4 ZegoDocsView 与 ZegoWhiteboardView 之间的同步滚动与翻页

无论是翻页还是滚动都是通过 ZegoWhiteboardView 的 scroll 接口实现，ZegoWhiteboardView SDK 内部会自动将 ZegoDocsView 滚动或翻页到相同位置，并同步给房间内其他人。

// 下一页
function nextPage() {
      // step1: 获取当前页数、当前总页数
    const currentPage = zegoWhiteboardView.getCurrentPage();
    const totalPage = zegoWhiteboardView.getPageCount();
      // step2: 校验当前是否能进行翻页
    if (currentPage >= totalPage || totalPage <= 1) return;
      // step3: 获取当前滚动方向，文件白板默认都是纵向，不可修改
      const { direction } = zegoWhiteboardView.getCurrentScrollPercent();
      // step4: 计算目标页的百分比
    const percent = currentPage / totalPage;
    // step5: 判断滚动方向，执行滚动或翻页
    if (direction === 1) {
        // 横向滚动
        zegoWhiteboardView.scroll(percent, 0);
    } else {
          // 纵向滚动
        zegoWhiteboardView.scroll(0, percent);
    }
}
// 上一页
function previousPage() {
      // step1: 获取当前页数、当前总页数
    const currentPage = zegoWhiteboardView.getCurrentPage();
    const totalPage = zegoWhiteboardView.getPageCount();
      // step2: 校验当前是否能进行翻页
    if (currentPage <= 1 || totalPage <= 1) return;
      // step3: 获取当前滚动方向，文件白板默认都是纵向，不可修改
      const { direction } = zegoWhiteboardView.getCurrentScrollPercent();
      // step4: 计算目标页的百分比
    const percent = (currentPage - 2) / totalPage;
      // step5: 判断滚动方向，执行滚动或翻页
    if (direction === 1) {
          // 横向滚动
        zegoWhiteboardView.scroll(percent, 0);
    } else {
          // 纵向滚动
        zegoWhiteboardView.scroll(0, percent);
    }
}

3.5 销毁文件白板

调用 destroyView 销毁文件白板。

/**
* 销毁指定的文件白板，ZegoWhiteboardView SDK 内部会自动销毁 ZegoWhiteboardView 和对应的 ZegoDocsView 相关资源
* @params ZegoWhiteboardView
*/
zegoExpressEngine.destroyView(zegoWhiteboardView);

4 示例源码

以上介绍了互动白板和文件共享搭配使用的基本场景，更复杂的交互场景请查看完整的示例源码，详情请参考 下载示例源码。

相关文档

互动白板 SDK 与 文件共享 SDK 的关系是什么？