实现流程

---

1 概念解释

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

2 前提条件

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

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

3 使用步骤

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

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

3.1 初始化 SDK

/** 引入 ZegoExpressDocs SDK */
const ZegoExpressDocs = window.require('zego-express-docsview-electron');
/**
* 初始化 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 上传文件

调用 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 模式。

zegoExpressDocs.uploadFile(file, renderType)

建议关注以下事件：

//当上传文件时，会收到上传文件 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 创建 ZegoDocsView。

/**
* 创建 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 示例源码

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