文件共享
  • iOS
  • Android
  • macOS
  • Windows
  • Web : JavaScript
  • Electron
  • 概述
  • 价格说明
  • 下载
  • 下载示例源码
  • 接入指南
  • 快速开始
  • 场景实践
  • 进阶功能
  • 客户端 API
  • 服务端 API v2
  • 常见错误码
  • 常见问题
  • 文档中心
  • 文件共享
  • 快速开始
  • 实现流程

实现流程

更新时间:2023-09-18 17:05

1 概念解释

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

2 前提条件

文件共享功能不是默认开启的,使用前请在 ZEGO 控制台 自助开通(开通步骤请参考 项目管理 - 服务配置 中的“文件共享”),或联系 ZEGO 技术支持开通。

3 使用步骤

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

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

如果要实现在文件上绘制以及多端联动功能,需要引入互动白板功能,详情请参考 ZegoWhiteboardView SDK

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,开发者就可以调用 ZegoDocsViewloadFile 接口,传入 fileID 加载该文件。

上传的文件必须满足相应的规范:

  1. 文件请使用 Microsoft Office 2013 或以上版本编辑/保存,不支持低版本 Microsoft Office 或其他办公软件保存的文件,如 WPS、Keynote、Microsoft Office 2003 等。

  2. 文件必须是可编辑的,不支持“只读”、“加密”、或其他保护的文档,否则会导致转码失败。

全部规范请参考 概述 - 文件规范

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

  • 上传阶段:如果正常上传,会产生多次回调,每次都包含文件上传进度。例如当前上传 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){
 ...
})

如果遇到加载失败的情况,请参考 常见错误码。常见的原因如下:

  • 开发者申请的 AppID 不包含文件共享的能力,需要向 ZEGO 技术支持申请开通。
  • 上传文件和加载文件使用不同的 AppID。例如,开发者在 AppID1 中上传了文件1,却在 AppID2 中加载文件1的 fileID,此时会找不到文件。
  • 文件上传和加载环境不一致。例如,文件在正式环境中上传,却在测试环境中加载,此时会找不到文件。

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 获取文件缩略图。

  1. 获取当前文件缩略图列表,仅支持 PDF,PPT,动态 PPT ,H5文件格式。
  2. 需要在文件加载成功后调用。
/**
* 获取当前文件缩略图列表,仅支持 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 文件,可以通过 nextSteppreviousStep 方法进行动态 PPT 的上一步和下一步的操作,进行动态 PPT 的上下步跳转。动态 PPT 的操作需要在文件加载完成后才能调用。

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

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

4 示例源码

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

相关文档

本篇目录