所有文档

          文档服务 DOC

          文档阅读器iOS-SDK开发指南

          开发环境

          使用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.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搭建开发环境

          Podfiletarget中添加依赖:

              pod 'BaiduBCEReader', '~> 2.3.3'

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