实现流程

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

3.1.1 引入头文件

// 引入 ZegoDocsView SDK 头文件
#import <ZegoDocsView/ZegoDocsView.h>

3.1.2 初始化 ZegoDocsView SDK

ZegoDocsViewConfig *config = [ZegoDocsViewConfig new];
config.appID = appID;//即构 AppID
config.appSign = appSign;//即构 appSign

config.dataFolder = [[NSHomeDirectory() stringByAppendingPathComponent:@"Documents/ZegoDocs"] stringByAppendingString:@"data"];//SDK 相关数据目录
config.cacheFolder = [[NSHomeDirectory() stringByAppendingPathComponent:@"Documents/ZegoDocs"] stringByAppendingString:@"doc"];//SDK 相关缓存目录
config.logFolder = [[NSHomeDirectory() stringByAppendingPathComponent:@"Documents/ZegoDocs"] stringByAppendingString:@"log"];//SDK 相关日志目录

[[ZegoDocsViewManager sharedInstance] initWithConfig:config completionBlock:^(ZegoDocsViewError errorCode) {
    if (errorCode == ZegoDocsViewSuccess) {
        NSLog(@"初始化 SDK 成功");
    } else {
        NSLog(@"初始化 SDK 失败 %ld",errorCode);
    }
}];

（可选）Token 过期更新

- (void)onTokenWillExpire:(int)remainTimeInSecond
{
    NSString * token = **; //后台获取到的token
    [[ZegoDocsViewManager sharedInstance] renewToken:token];
}

3.2 上传文件

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

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

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

3.2.1 上传普通文件

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

//filePath 待上传文件的绝对路径，可以使用 iOS 系统API获得。
NSString *filePath = [[NSBundle mainBundle] pathForResource:@"test" ofType:@"pdf"];

//上传文件后转码后渲染模式类型，默认为ZegoDocsViewRenderTypeVector格式，如果用户涉及到 iOS、Web、Windows、Mac、小程序各端的业务，推荐使用 ZegoDocsViewRenderTypeVectorAndIMG 模式。
ZegoDocsViewRenderType renderType = ZegoDocsViewRenderTypeVectorAndIMG;

[[ZegoDocsViewManager sharedInstance] uploadFile:filePath renderType:renderType completionBlock:^(ZegoDocsViewUploadState state, ZegoDocsViewError errorCode, NSDictionary * _Nonnull infoDictionary) {
  if (errorCode == ZegoDocsViewSuccess) {
    if (state == ZegoDocsViewUploadStateUpload) {
      // 上传中...
      NSString *uploadPercent = infoDictionary[@"upload_percent"];
      if(uploadPercent.intValue == 1){
        // 转码中...
      }
    } else if (state == ZegoDocsViewUploadStateConvert){
      // 转换成功，获取到文件 fileID，可通过 "upload_fileid" 键获取 fileID
      // 可以调用 ZegoDocsView 的 loadFile 接口，传入 fileID 加载文件。
      NSString *fileID = infoDictionary[@"upload_fileid"];

      /* 上传成功
          [self.zegoDocsView loadFileWithFileID:fileID authKey:nil completionBlock:^(ZegoDocsViewError errorCode) {
            NSLog(@"%d", errorCode);
             }];
             */
    }
  } else {
    // 上传失败
  }
}];

3.2.2 上传 H5 文件

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

//文件的绝对路径，可以根据iOS API 获得
    [[ZegoDocsViewManager sharedInstance] uploadH5File:[url path] config:config completionBlock:^(ZegoDocsViewUploadState state, ZegoDocsViewError errorCode, NSDictionary * _Nonnull infoDictionary) {
    if (errorCode == ZegoDocsViewSuccess) {
            if (state == ZegoDocsViewUploadStateUpload) {
                // 上传中...
                if(upload_percent.intValue == 1){
                    // 转码中...
                }
            } else if (state == ZegoDocsViewUploadStateConvert){
                // 转换成功
            }
        } else {
            // 上传失败
        }
    }];

3.3 加载文件

3.3.1 创建 ZegoDocsView

创建 ZegoDocsView 并添加到视图中。

// 1. init
self.docView = [[ZegoDocsView alloc] init]; //初始化文件View
self.docView.backgroundColor = UIColor.whiteColor; //设置文件View背景颜色
[self.docView setDelegate:self]; //设置文件View 代理通知
[self.view addSubview:self.docView]; //添加到自己需要展示的View 上
// 2.设置 frame
self.docView.frame = CGRectMake(0, 0, 100, 100);

3.3.2 加载并渲染文件

调用 ZegoDocsView 的 loadFileWithFileID 接口，传入之前上传成功后获取的 fileID 加载文件。

// fileID 在 uploadFile 成功之后获取
NSString *fileID = @"";
[self.docView loadFileWithFileID:fileID //后台获取到文件ID
 authKey:@"" //鉴权key。可以为空。根据你所申请环境是否需要鉴权填入。最好是通过后台获取 
 completionBlock:^(ZegoDocsViewError errorCode) {

}];

3.4 使用 ZegoDocsView 的基本功能

3.4.1 翻页

• 加载文件成功后，可调用 ZegoDocsView 的 flipPage 方法对文件进行翻页。
• 加载文件成功后，默认能通过指触对 ZegoDocsView 进行滚动/翻页。

// 举例：非动态PPT 跳转到第3页。
[self.docView flipPage:3 completionBlock:^(BOOL isScrollSuccess) {
            NSLog(@"翻页结束");
        }];

// 举例：动态PPT 跳转到第2页，第4步。
[self.docView flipPage:2 step:4 completionBlock:^(BOOL isScrollSuccess) {
            NSLog(@"翻页结束");
        }];

3.4.2 文件缩放

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

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

[self.docsView scaleDocsViewWithScaleFactor:scaleFactor scaleOffsetX:scaleOffsetX scaleOffsetY:scaleOffsetY];

3.4.3 获取文件缩略图

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

NSArray *thumbnailUrls = [self.docsView getThumbnailUrlList];

3.4.4 Excel 文件切换 sheet

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

 [self.docView switchSheet:0];

3.4.5 动态 PPT 操作

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

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

//上一步
[self.docViewFirst previousStepWithCompletionBlock:^(BOOL isScrollSuccess) {

}];
//下一步
[self.docViewFirst nextStepWithCompletionBlock:^(BOOL isScrollSuccess) {

}];

4 示例源码

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

相关文档

• 如何设置日志？
• 加载 PPT 时经常遇到的动画、文字、交互问题有哪些？
• 文件上传或加载失败怎么处理？
• 如何处理文件共享 SDK 所有接口均异常的问题？
• 如何处理文件共享常见问题？