实现流程

---

1 概念解释

• ZEGO 文件云服务：指 ZEGO 存储文件的服务器，开发者上传文件时会上传到此服务器。
• ZegoDocsView SDK：即构文件共享服务对应的客户端 SDK。
• ZegoDocsView：文件视图，开发者可以利用该视图加载 ZEGO 文件云服务上的文件并展示。

2 前提条件

• 已在 ZEGO 控制台 创建项目，并申请有效的 AppID，详情请参考 控制台 - 项目管理 中的“项目信息”。
• 在项目中集成 ZegoDocsView SDK，详情请参考 快速开始 - 集成。
• 已生成 Token，详情请参考 使用 Token 鉴权。也可以参考 控制台 - 开发辅助，在 ZEGO 控制台获取临时 Token（有效期为 24 小时）。

3 使用步骤

本节分为四个部分来介绍 ZegoDocsView SDK：

1. 初始化 SDK
2. 上传文件：上传本地的文件到 ZEGO 文件云服务
3. 加载文件：通过文件 ID 加载 ZEGO 文件云服务上的文件并展示
4. 使用 ZegoDocsView 的基本功能

3.1 初始化 SDK

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

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

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

/**
* 初始化 ZegoExpressDocs SDK
* @param appID: ZEGO 为开发者签发的应用 ID，请从 ZEGO 控制台申请
* @param token: token
* @param userID: userID
*/
const zegoExpressDocs = new window.ZegoExpressDocs({appID, token, userID});

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

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

/**
* 初始化 ZegoExpressDocs SDK
* @param appID: ZEGO 为开发者签发的应用 ID，请从 ZEGO 控制台申请
* @param token: token
* @param userID: userID
*/
const zegoExpressDocs = new ZegoExpressDocs({appID, token, userID});

Token 过期更新

监听 Token 过期通知，如果 Token 过期，需要主动更新 Token。

zegoExpressDocs.on('onTokenWillExpire', function(){
    var newToken = 'new token';
    zegoExpressDocs.renewToken(newToken)
})

3.2 上传文件

调用 ZegoExpressDocs 中上传文件的方法上传文件到 ZEGO 文件云服务，上传成功之后返回的参数中可获取到该文件的 fileID，开发者就可以调用 ZegoDocsView 的 loadFile 接口，传入 fileID 加载该文件。

文件上传过程中有多个阶段，开发者需要特别关注以下两个阶段：

• 上传阶段：如果正常上传，会产生多次回调，每次都包含文件上传进度。例如当前上传 50%，则 “data” 内容为 {"uploadPercent":50}；当前上传 100%，则 “data” 内容为 {"uploadPercent":100}。
• 格式转换阶段：如果转换成功，只产生一次回调，包含转换后的文件 ID。例如当前转换完成，则 “data” 内容为 {"fileID":"ekxxxxxxxxv"}。fileID 对应的值即为文件 fileID。

其他上传阶段请参考 ZegoDocsViewUploadModel。

3.2.1 上传普通文件

调用 uploadFile 接口上传普通文件。

//上传文件后转码后渲染模式类型，如果用户涉及到 iOS、Web、Windows、Mac、小程序各端的业务，推荐使用 ZegoDocsViewRenderTypeVectorAndIMG 模式。
//上传文件成功之后会返回文件 ID

zegoExpressDocs.uploadFile(file, renderType):Promise<any>

建议关注以下事件：

//当上传文件时，会收到上传文件 uploadFile 的回调
zegoExpressDocs.on('onUpload', function(data: ZegoDocsViewUploadModel){
 ...
})

3.2.2 上传 H5 文件

调用 uploadH5File 上传 H5 文件。

/***
*@param myFile: 上传文件
*@param config: H5课件相关配置信息
*@param listener: 上传的进度的回调
*/
zegoExpressDocs.uploadH5File(myFile, config, function (res) {
  console.log('uploadH5File', res);
}).then(function (res) {
  console.log('uploadH5FileID', res);
});

3.3 加载文件

3.3.1 创建 ZegoDocsView

调用 createView 创建文件视图。

/**
* 创建 docView
* @param parent: ZegoDocsView 挂载容器 ID
* eg:<div id="parent"></div>
*/
const docView = zegoExpressDocs.createView(parent);

3.3.2 将文件添加到视图

调用 loadFile 将文件添加到视图。

// authKey 可为空字符串
docView.loadFile(fileID, authKey)

建议关注以下事件：

// 当上传文件时，会收到上传文件 loadFile 的回调，得到加载目标文件的相关信息
zegoExpressDocs.on('onLoadFile', function(data: ZegoDocsViewLoadFileModel){
 ...
})

3.4 使用 ZegoDocsView 的基本功能

3.4.1 翻页

• 加载文件成功后，可调用 ZegoDocsView 的 flipPage 接口对文件进行翻页。
• 加载文件成功后，可调用 ZegoDocsView 的 scrollTo 接口对文件进行滚动翻页。

/**
* 跳转到指定页位置。
* @param page: 跳转目标页，从 1 开始
* @param step: 跳转目标页对应的 step，从1开始（仅针对动态PPT）
*/
docView.flipPage(page: number, step?: number)

// 举例：非动态PPT 跳转到第3页。
docView.flipPage(3)

// 举例：动态PPT 跳转到第2页，第4步。
docView.flipPage(2,4)

/**
* 跳转到纵向偏移百分比。
* @param verticalPercent: 纵向偏移百分比，参数取值范围 0.00 ~ 1.00，例如要跳转到一半的位置，则传入参数为 0.50
*/
docView.scrollTo(verticalPercent: number)

3.4.2 文件缩放

加载文件成功后，可调用 setScaleFactor 对文件进行缩放。

• scaleFactor：文件缩放需要指定缩放因子，即缩小或放大的比例系数。
• scaleOffset：在缩小或放大后需要展示的区域的左起点。

/**
* 缩放
* @param scaleFactor: 缩放倍数，不小于 1 的正数
* @param scaleOffsetX: X轴缩放偏移量
* @param scaleOffsetY: Y轴缩放偏移量
* @note  目前偏移量尚未支持，可不传
*/
docView.setScaleFactor(scaleFactor: number, scaleOffsetX?: number, scaleOffsetY?: number)

/**
* 获取缩放对象
* @return {scaleFactor: 缩放倍数; scaleOffsetX: X轴缩放偏移量; scaleOffsetY: Y轴缩放偏移量}
*/
docView.getScaleFactor(): {scaleFactor: number; scaleOffsetX: number; scaleOffsetY: number}

3.4.3 获取文件缩略图

加载文件成功后，可调用 getThumbnailUrlList 获取文件缩略图。

/**
* 获取当前文件缩略图列表，仅支持 PDF，PPT，动态PPT，H5 文件格式，可在文件加载成功后调用
* @return 文件缩略图URL数组
*/
docView.getThumbnailUrlList(): Array<string>

3.4.4 Excel 文件切换 sheet

如果开发者上传的文件是 Excel 文件，而且存在多个 sheet 页，可以使用 switchSheet 方法切换 sheet 页，sheet 页从 0 开始。

docView.switchSheet(sheetIndex)

3.4.5 动态 PPT 操作

动态 PPT，即文件类型为 “ZegoDocsViewFileTypeDynamicPPTH5” 的文件，这种类型的文件每一页可能会有多个步骤（step）。

如果开发者上传的文件是动态 PPT 文件，可以通过 nextStep 和 previousStep 方法进行动态 PPT 的上一步和下一步的操作，进行动态 PPT 的上下步跳转。动态 PPT 的操作需要在文件加载完成后才能调用。

/**
* 下一步，仅针对动态 PPT ZegoDocsViewFileTypeDynamicPPTH5 类型操作
*/
docView.nextStep()

/**
* 上一步，仅针对动态 PPT ZegoDocsViewFileTypeDynamicPPTH5 类型操作
*/
docView.previousStep()

4 示例源码

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

相关文档

• 为什么设置转码清晰度后，没有立马生效，重新渲染也没有生效？
• 加载 PPT 时经常遇到的动画、文字、交互问题有哪些？
• 如何处理文件共享常见问题？