文档服务DOC

    文档阅读器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* 文档加载预览页数

    阅读器接口

    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];
    上一篇
    简介
    下一篇
    版本更新记录