文档中心
文件共享
快速开始
实现流程

实现流程

更新时间：2023-04-06 16:15

1 概念解释

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

2 前提条件

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

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

文件共享功能不是默认开启的，使用前请在 ZEGO 控制台自助开通（开通步骤请参考项目管理 - 服务配置中的“文件共享”），或联系 ZEGO 技术支持开通。
2.3.0 或以上 版本的 SDK 支持 Token 鉴权，若您需要升级鉴权方式，可参考如何从 AppSign 鉴权升级为 Token 鉴权。

3 使用步骤

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

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

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

3.1 初始化 SDK

long appID = ;  /** 请通过官网注册获取，格式为 123456789L */
String appsign = ;  /** 请通过官网注册获取，格式为字符串*/
Application application ; //android app的 application

ZegoDocsViewConfig config = new ZegoDocsViewConfig();  
config.setAppID(appID);
config.setAppSign(appsign);

ZegoDocsViewManager.getInstance().init(application,config, new IZegoDocsViewInitListener() {
    @Override
    public void onInit(int errorCode) {
        if (errorCode == 0) {
            /** 初始化成功 */
        } else {
            /** 初始化失败 */
        }
    }
});

如果您需要切换鉴权方式，请参考如何从 AppSign 鉴权升级为 Token 鉴权。

（可选）Token 过期更新

此步骤介绍 Token 过期时如何处理；如果您未使用 Token 鉴权，可忽略此步。

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

ZegoDocsViewManager.getInstance().setTokenListener(new IZegoDocsViewSetTokenListener() {
    @Override
    public void onTokenWillExpire(int remainTimeInSecond) {
        //从服务器获取新的token
        String token = getTokenFromServer();
        ZegoDocsViewManager.getInstance().renewToken(token);
    }
});

3.2 上传文件

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

文件上传分为上传 ZegoDocsViewUploadStateUpload 和格式转换 ZegoDocsViewUploadStateConvert 两个阶段。

上传阶段：如果正常上传，会产生多次回调，每次都包含文件上传进度。例如当前上传 50%，则 "infoMap" 内容为 {"upload_percent":0.50}；当前上传 100%，则 "infoMap" 内容为 {"upload_percent":1.00}。
格式转换阶段：如果转换成功，只产生一次回调，包含转换后的文件 ID。例如当前转换完成，则 "infoMap" 内容为 {"upload_fileid":"ekxxxxxxxxv"}。

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

文件请使用 Microsoft Office 2013 或以上版本编辑/保存，不支持低版本 Microsoft Office 或其他办公软件保存的文件，如 WPS、Keynote、Microsoft Office 2003 等。
文件必须是可编辑的，不支持“只读”、“加密”、或其他保护的文档，否则会导致转码失败。
如果您使用的是 2.0 版本的文件共享 SDK，可能因为安卓分区存储问题导致上传文件失败，请升级 SDK 至最新版本或者参考上传文件失败怎么处理？进行设置。

全部规范请参照概述 - 文件规范。

3.2.1 上传普通文件

调用 uploadFile 方法上传普通文件。

String filePath = "";
int renderType = ZegoDocsViewConstants.ZegoDocsViewFileTypeIMG;//例如转换成image格式
ZegoDocsViewManager.getInstance().uploadFile(filePath, renderType, new IZegoDocsViewUploadListener() {
    @Override
    public void onUpload(int state, int errorCode, @NonNull HashMap<String, Object> infoMap) {
        if (errorCode == ZegoDocsViewConstants.ZegoDocsViewSuccess) {
            if (state == ZegoDocsViewConstants.ZegoDocsViewUploadStateUpload) {
                // 上传中...
                float uploadPercent = (float) infoMap.get("upload_percent");
                if(uploadPercent == 1f){
                /** 正在转码... */
                }
            } else if (state == ZegoDocsViewConstants.ZegoDocsViewUploadStateConvert){
                /** 转换成功 */
                String fileID = (String) infoMap.get(ZegoDocsViewConstants.UPLOAD_FILEID);
            }
        } else {
        /** 上传失败 */
        }
    }
});

3.2.2 上传 H5 文件

通过 ZegoDocsViewCustomH5Config 设置上传 H5 文件的配置参数，并调用 uploadH5File 方法上传 H5 文件。


String filePath = "";

ZegoDocsViewCustomH5Config mH5Config = new ZegoDocsViewCustomH5Config();
mH5Config.height = 960;
mH5Config.width = 540;
mH5Config.pageCount = 5;

ZegoDocsViewManager.getInstance().uploadH5File(filePath, mH5Config, new IZegoDocsViewUploadListener() {
    @Override
    public void onUpload(int state, int errorCode, @NonNull HashMap<String, Object> infoMap) {
        if (errorCode == ZegoDocsViewConstants.ZegoDocsViewSuccess) {
            if (state == ZegoDocsViewConstants.ZegoDocsViewUploadStateUpload) {
                // 上传中...
                float uploadPercent = (float) infoMap.get("upload_percent");
                if(uploadPercent == 1f){
                    /** 正在转码... */
                }
            } else if (state == ZegoDocsViewConstants.ZegoDocsViewUploadStateConvert){
                /** 转换成功 */
                String fileID = (String) infoMap.get(ZegoDocsViewConstants.UPLOAD_FILEID);
            }
        } else {
            /** 上传失败 */
        }
    }
});

3.3 加载文件

调用 loadFile 方法加载文件。

加载文件需要请求 Android 的文件权限，如遇到加载失败的情况，请参考常见错误码。可能的失败场景如下：

无加载文档所需权限。
AppID 与要加载的文档不匹配。
文档在正式环境而初始化的 SDK 在测试环境。

当前 DocsView 已调用 loadFile 接口加载文件后，需要先调用 unloadFile 接口卸载文件，才能再次使用 loadFile 加载文件。
只有之前调用过 loadFile 接口，后续才能调用 reloadFile 接口。

ZegoDocsView zegoDocsView = new ZegoDocsView(context);
addView(zegoDocsView, 0, new ViewGroup.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT,ViewGroup.LayoutParams.MATCH_PARENT))
String fileID = "";  // 上传文件得到fileID
String authKey = ""; // 用于鉴权，可以传""
//本指引使用docs_view_container作为布局中的view容器(与demo保持一致)，容器可为FrameLayout等        
zegoDocsView.loadFile(fileID, authKey, new IZegoDocsViewLoadListener() {
     @Override
     public void onLoadFile(int errorCode) {
         if (errorCode == 0) {
         /** 加载成功 */
         } else {
         /** 加载失败 */
         }
     }
});

3.4 使用 ZegoDocsView 的基本功能

3.4.1 滚动翻页

调用 flipPage 对文件进行翻页。

滚动翻页针对动态 PPT 和非动态 PPT 提供给了两个对外接口。
跳转页面和步数都是以 1 为起始。

ZegoDocsView zegoDocsView = new ZegoDocsView(context);
int page = 1;
zegoDocsView.flipPage(page, new IZegoDocsViewScrollCompleteListener() {
    @Override
    public void onScrollComplete(boolean isScrollSuccess) {
        if (isScrollSuccess) {
        // 翻页成功
        } else {
        // 翻页失败
        }
     }
});

    /** 仅对动态PPT有效 */
int page = 1;
int step = 1;
zegoDocsView.flipPage(page, step, new IZegoDocsViewScrollCompleteListener() {
    @Override
    public void onScrollComplete(boolean isScrollSuccess) {
        if (isScrollSuccess) {
        // 翻页成功
        } else {
        // 翻页失败
        }
    }
});

3.4.2 文件缩放

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

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


ZegoDocsView zegoDocsView = new ZegoDocsView(context);
float scaleFactor = 1.0f;
float scaleOffsetX = 1.0f;
float scaleOffsetY = 1.0f;
zegoDocsView.scaleDocsView(scaleFactor, scaleOffsetX, scaleOffsetY);

3.4.3 获取文件缩略图

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

获取当前文件缩略图列表，仅支持 PDF、PPT 、动态 PPT和 H5 文件四种文件格式。
需要在文件加载成功后调用。

ZegoDocsView zegoDocsView = new ZegoDocsView(context);
ArrayList<String> thumbnailUrlList = zegoDocsView.getThumbnailUrlList();

3.4.4 Excel 文件切换 sheet

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

ZegoDocsView zegoDocsView = new ZegoDocsView(context);
int sheetIndex = 1;
zegoDocsView.switchSheet(sheetIndex, new IZegoDocsViewLoadListener() {
   @Override
    public void onLoadFile(int errorCode) {
        boolean isSuccess = errorCode == 0;
    }
});

3.4.5 动态 PPT 操作

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

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

ZegoDocsView zegoDocsView = new ZegoDocsView(context);

/** 上一步 */
zegoDocsView.previousStep(new IZegoDocsViewScrollCompleteListener() {
    @Override
     public void onScrollComplete(boolean isScrollSuccess) {

    }
});

/** 下一步 */
zegoDocsView.nextStep(new IZegoDocsViewScrollCompleteListener() {
     @Override
    public void onScrollComplete(boolean isScrollSuccess) {

    }
});

4 示例源码

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