文档阅读器iOS-SDK开发指南
更新时间:2020-08-10
开发环境
使用SDK包搭建开发环境
- 下载最新的文档阅读器iOS SDK,md5:28fe411b76678426c4bfb209ef7606fa。
- Xcode版本:推荐使用Xcode 11.5。
- 准备 iOS 运行环境:iOS 8.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.h
和libZipArchive.a
,也通过上一步的方式添加到项目中; - 设置正确的
Header Search Paths
和Library Search Paths
来保证编译时能找到ZipArchive.h
和libZipArchive.a
。 - 在
Build Settings
中设置Other Linker Flags
,加入参数-ObjC
; - 在 'Build Phases' 中设置
Link Binrary With Libraries
,加入WebKit.framework
和libz.tbd
。
使用cocoapods搭建开发环境
在Podfile
的target
中添加依赖:
pod 'BaiduBCEReader', '~> 2.3.3'
文档参数定义
SDK提供的接口中,表示文档参数的类型为NSDictionary,相关键定义如下:
键 | 类型 | 是否必需 | 说明 |
---|---|---|---|
BDocPlayerSDKeyDocID | NSString* | 是 | 文档ID |
BDocPlayerSDKeyDocTitle | NSString* | 是 | 文档标题 |
BDocPlayerSDKeyTotalPageNum | NSString* | 是 | 文档总页数 |
BDocPlayerSDKeyToken | NSString* | 是 | 文档token,离线加载时不验证 |
BDocPlayerSDKeyHost | NSString* | 是 | 文档所属站点 |
BDocPlayerSDKeyDocType | NSString* | 是 | 文档类型,有效值:ppt 和 doc |
BDocPlayerSDKeyPageNumber | NSNumber* | 否 | 文档加载起始页数 |
BDocPlayerSDKeyPreviewPageNumber | NSNumber* | 否 | 文档加载预览页数 |
阅读器接口
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*
的错误信息:
- BCEDocumentReader的
loadDoc:error:
接口 - BCEDocumentReaderDelegate的
docLoadingEnded:
接口
请您对照下面的错误码定义定位问题原因:
错误码 | 说明 |
---|---|
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*
的错误信息:
- BCEDocumentDownloader的
downloadTask:error:
接口 - BCEDocumentDownloaderDelegate的
taskEnd: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];