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

---

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 和 AppSign，详情请参考 控制台 - 项目管理。

3 实现流程

3.1 初始化 SDK

3.1.1 引入 SDK

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

使用 npm 获取 SDK

// 引入音视频功能（提供房间能力）
const zegoExpressEngine = window.require('zego-express-engine-electron/ZegoExpressEngine.js')
// 引入白板功能（提供白板能力）
const ZegoWhiteBoard = window.require('zego-express-engine-electron/ZegoWhiteBoardView.js')
// 引入文件功能
const ZegoExpressDocs = window.require('zego-express-docsview-electron') 

3.1.2 初始化 ZegoWhiteboardView SDK

// AppID 由 ZEGO 分配给各 App；
// appSign 由 ZEGO 分配给各 App；
// 采用通用场景
const profile = {
    appID : xxx,
    appSign: xxx,
    scenario : zgDefines.ZegoScenario.General
};

zegoExpressEngine.createEngine(profile)
.then(() => {
    console.log("init succeed")
}).catch((e) => {
    console.log("init failed", e)
});

// 初始化白板
const zg = new ZegoWhiteBoard();

3.1.3 初始化 ZegoDocsView SDK

/**
* 初始化 ZegoExpressDocs SDK
* @param appID: ZEGO 为开发者签发的应用 ID，请从 ZEGO 控制台申请
* @param appSign: ZEGO 为开发者签发的应用 appSign，请从 ZEGO 控制台申请
* @param dataFolder: 可选，SDK 内部数据保存目录，开发者无需关注此目录下的具体内容
* @param cacheFolder: 可选，SDK 缓存保存目录
* @param logFolder: 可选，日志保存目录，记录 SDK 运行过程中的日志，便于定位
*/
const zegoExpressDocs = new ZegoExpressDocs({
    appID, 
    appSign,
    dataFolder, 
    cacheFolder, 
    logFolder
});

3.2 登录房间

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

/**
* 登录房间
* @param roomID 房间 ID，最大长度为 128 字节的字符串。仅支持数字，英文字符和 '~', '!', '@', '#', '$', '', '^', '&', '*', '(', ')', '_', '+', '=', '-', ';', '’', ',', '.', '<', '>', '/'
* @param user 登录用户信息
*/
zegoExpressEngine.loginRoom(roomID, { userID, userName },{
                maxMemberCount: 10,
                isUserStatusNotify: true
            });

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
    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){
         // 展示 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 示例源码

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