文档阅读器iOS SDK开发指南

开发环境

使用SDK包搭建开发环境

  • 下载最新的文档阅读器iOS SDK,md5:2c342da713671ba361075254ea04af26。
  • Xcode版本:推荐使用Xcode 8.1。
  • 准备 iOS 运行环境:iOS 7.0 及以上的所有系统。
  • 适配 CPU 指令集:armv6、armv7/armv7s、arm64、i386/x86_64。
  • 上传文档并确保文档已转码成功后,通过API调用阅读文档接口或通过DOC Java SDK调用readDocument方法,获取docId,host,token三个变量。
  • 添加依赖:
    • 复制framework到工程路径下;
    • 通过Xcode菜单 File -> Add Files to YourProject... 添加到项目中;
    • Resources目录下的DocPlayerSDK.Bundle, 也通过上一步的方式添加到项目中;
    • vendor目录下的ZipArchive.hlibZipArchive.a,也通过上一步的方式添加到项目中;
    • 设置正确的Header Search PathsLibrary Search Paths来保证编译时能找到ZipArchive.hlibZipArchive.a
    • Build Settings 中设置 Other Linker Flags,加入参数 -ObjC
    • 在 'Build Phases' 中设置 Link Binrary With Libraries,加入 WebKit.frameworklibz.tbd

使用cocoapods搭建开发环境

请参见Cocoapods接入方式

文档参数定义

SDK提供的接口中,表示文档参数的类型为NSDictionary,相关键定义如下:

类型 是否必需 说明
BDocPlayerSDKeyDocID NSString* 文档ID
BDocPlayerSDKeyDocTitle NSString* 文档标题
BDocPlayerSDKeyTotalPageNum NSString* 文档总页数
BDocPlayerSDKeyToken NSString* 文档token,离线加载时不验证
BDocPlayerSDKeyHost NSString* 文档所属站点
BDocPlayerSDKeyDocType NSString* 文档类型,有效值:pptdoc
BDocPlayerSDKeyPageNumber NSNumber* 文档加载起始页数
BDocPlayerSDKeyPreviewPageNumber NSNumber* 文档加载预览页数

您可以通过API调用阅读文档接口或使用DOC Java SDKreadDocument方法获取docId,host,token等文档相关参数。

阅读器接口

BCEDocumentReader类接口

接口 参数名 参数类型 参数说明 接口说明
delegate - - - 事件代理
loadDoc:error: parameters
error
NSDictionary
NSError*
文档信息
错误信息
加载文档。当发生错误且error传入nil时,将抛出NSInvalidArgumentException。如果返回错误,参考阅读器错误处理
setFontSize size float 字体大小, 范围 (0, 2] 设置文档的字体大小(ppt类文档无效)

BCEDocumentReaderDelegate代理接口

接口 参数 参数类型 参数说明 接口说明
docLoadingStart - - - 开始加载文档
docLoadingEnded error NSError* 错误信息 文档加载完毕。如果返回错误,参考阅读器错误处理
currentPageChanged page NSInteger 当前阅读页码 阅读翻页事件

注意:以下两个接口中可能返回类型为NSError*的错误信息:

  • BCEDocumentReaderloadDoc:error:接口
  • BCEDocumentReaderDelegatedocLoadingEnded:接口

请您对照下面的错误码定义定位问题原因:

错误码 说明
BCEDocumentDownloadErrorCodeParameterError 传入的参数不正确
BCEDocumentErrorCodeInvalidToken 无效的token

下载管理相关接口

下载功能可将文档下载至本地,以便离线阅读文档。主要包含以下三个类:

  • BCEDocumentItem:抽象一个离线文档
  • BCEDocumentDownloadTask:抽象一个下载任务
  • BCEDocumentDownloader:抽象一个下载器,进行任务管理和调度

BCEDocumentItem接口

BCEDocumentItem代表一个离线文档的相关信息,有以下属性:

属性 类型 属性说明
parameters NSDictionary* 文档相关信息,当文档下载完成后,可将此属性传给阅读器进行离线加载
identify NSString* 离线文档标识,一般为文档的docId
title NSString* 离线文档标题
path NSString* 离线文档保存路径
size NSString* 离线文档大小,下载完成后有值
status BCEDocumentItemStatus 离线文档下载状态:
0 正在下载
1 下载完成
2 数据被删除需要重新下载
progress float 下载进度 [0, 100]

BCEDocumentDownloadTask接口

BCEDocumentDownloadTask表示一个下载任务,受BCEDocumentDownloader管理。

属性 类型 属性说明
item BCEDocumentItem* 离线文档
state BCEDocumentDownloadTaskState 下载状态:
0 等待中
1 下载中
2 已挂起
3 已取消
4 已完成
5 已失败
progress float 下载进度 [0, 100]

BCEDocumentDownloader接口

BCEDocumentDownloader提供任务的创建和管理,以及离线文档数据的管理功能。

接口 参数 参数类型 参数说明 接口说明
delegate - - - 事件代理
downloadTask:error: parameters
error
NSDictionary
NSError*
文档参数
错误信息
传入文档信息来创建一个下载任务。当发生错误且error传入nil时,将抛出NSInvalidArgumentException。返回错误时请参考下载错误处理
suspendTask task BCEDocumentDownloadTask* 要挂起的任务 挂起指定的任务
resumeTask task BCEDocumentDownloadTask* 要恢复的任务 恢复指定的任务
cancelTask task BCEDocumentDownloadTask* 要取消的任务 取消指定的任务。调用后数据将被删除。
stopAllTasks - - - 停止所有任务
resumeUncompletedTasks - - - 继续上次未完成的下载任务
documents - - - 获取所有离线文档
removeDocument item BCEDocumentItem* 离线文档 删除一个离线文档
frozen - - - 冻结或者解除冻结。
冻结后将不调度处于等待状态的任务。
clean - - - 删除此用户的所有数据。需要在没有正在下载的任务时调用。调用后,下载器将不再可用。
initWithUser User(用户名)
Delegate(代理)
Path (文档数据存储路径)
NSString
BCEDocumentDownloaderDelegate
NSString
- 指定用户名、代理和存储路径进行初始化。在没有账户系统时,用户可指定默认值。
存储路径为空时,文档数据存储在SDK默认存储路径Cache目录下。

BCEDocumentDownloaderDelegate 代理提供以下事件回调:

接口 参数 参数类型 参数说明 接口说明
taskStart task BCEDocumentDownloadTask* 任务 任务开始执行
task:needAuthentication: task
parameters
BCEDocumentDownloadTask
NSMutableDictionary
任务
存储鉴权信息的字典
任务需要鉴权,目前需要传入token。token有实效性,只有任务真正开始执行的时候才会回调要求传入token。
task:progress: task
progress
BCEDocumentDownloadTask*
float
任务
进度
任务进度汇报
taskEnd:error: task
error
BCEDocumentDownloadTask
NSError
任务
错误信息
任务结束。如果error不为空,表示任务执行失败。参考下载错误处理

下载错误处理

以下两个接口中可能返回类型为NSError*的错误信息:

  • BCEDocumentDownloaderdownloadTask:error:接口
  • BCEDocumentDownloaderDelegatetaskEnd:error:接口

请您参照下述错误码定义定位问题原因:

错误码 说明
BCEDocumentDownloadErrorCodeParameterError 传入的参数不正确
BCEDocumentDownloadErrorCodeAlreadyExists 本地已存在要下载的文档
BCEDocumentDownloadErrorCodeCancelledByUser 被用户取消
BCEDocumentDownloadErrorCodeSuspendByUser 被用户挂起
BCEDocumentDownloadErrorCodeOpenFileFailure 打开文档文件失败
BCEDocumentDownloadErrorCodeProcessFileFailure 处理文档文件失败
BCEDocumentDownloadErrorCodeNeedToken 需要在回调中设置token
BCEDocumentDownloadErrorCodeHTTPCodeError 请求响应的HTTP状态码不在[200, 300)区间
BCEDocumentDownloadErrorCodeInvalidToken token无效
BCEDocumentDownloadErrorCodeTokenExpired token已过期
BCEDocumentDownloadErrorCodeResponseInvalid 请求的响应格式不正确
BCEDocumentDownloadErrorCodeStorageServiceError 文档的存储服务返回错误
BCEDocumentDownloadErrorCodeUnknown 未知错误

加载在线文档

初始化文档阅读器

// 假设self是一个UIViewController对象。
self.reader = [BCEDocumentReader alloc] initWithFrame:frame];
self.reader.delegate = self;
[self.view addSubview:self.reader];

准备文档参数

初始化一个NSDictionary表示文档相关参数:

NSDictionary* parameters = @{
    BDocPlayerSDKeyDocID: @"<docId>",
    BDocPlayerSDKeyToken: @"<token>",
    BDocPlayerSDKeyHost: @"<host>",
    BDocPlayerSDKeyDocType: @"<docType>",
    BDocPlayerSDKeyTotalPageNum: @"<totalPageNum>",
    BDocPlayerSDKeyDocTitle: @"<title>",
    BDocPlayerSDKeyPageNumber : @(<startPageNum>)
};

加载文档

NSError* error;
[self.reader loadDoc:parameters error:&error];

下载文档

初始化下载器

self.downloader = [[BCEDocumentDownloader alloc] initWithUser:@"baidu" delegate:self];

实现代理方法

task:needAuthentication:是必须实现的代理方法。

- (void)task:(BCEDocumentDownloadTask*)task 
        needAuthentication:(NSMutableDictionary*)parameters {
    [parameters setObject:@"<token>" forKey:BDocPlayerSDKeyToken]; 
}

创建下载任务

这里假设文档参数已经准备好,具体参见准备文档参数

NSError* error;
BCEDocumentDownloadTask* task = [self.downloader downloadTask:parameters error:&error];
[self.tasks addObject:task];

自定义数据下载路径

/**
 *  @brief 指定用户名、代理和存储路径进行初始化。在没有账户系统时,用户可指定默认值。存储路径为空时,文档数据存储在SDK默认存储路径Cache目录下。
 *  @param user     用户名。
 *  @param delegate 代理。
 *  @param path     文档数据存储路径。
 *  @return 下载管理器。
 */

objectivec
- (instancetype)initWithUser:(NSString*)user
                    delegate:(id<BCEDocumentDownloaderDelegate>)delegate
                     storage:(NSString*)path;

离线加载

当文档下载完成后,就可以离线加载。

获取文档信息

从下载完成的Task中获取:

NSDictionary* parmaeters = task.item.parameters;

或者通过下载器的接口获取:

NSDictionary* parmaeters;
NSArray<BCEDocumentItem*>* documents = [self.downloader documents];
for (BCEDocumentItem* document in documents) {
    if (document.state == BCEDocumentItemStatusReady 
        && [document.identify isEqualToString:@"<docId>"]) {
        parmaeters = document.parameters;
    }
}

加载文档

NSError* error;
[self.reader loadDoc:parameters error:&error];