Android文档播放器使用说明

1、工程配置

下载的zip包解压后，有三个文件(文件夹):assets文件夹、demo文件夹、jar包。

将jar包复制到您工程的libs目录下；
将assets文件夹中的内容复制到您工程的assets目录下；
参考demo工程与该文档，学习sdk的使用；

2、功能概述

文档播放器提供两个主要功能：

文档播放功能(在线)
- 视图控件类：创建视图控件并添加至控件树；
- 加载与翻页回调：回调加载结果、当前页变化等；
文档下载功能&离线播放
- 下载管理接口：包括文档的开启下载、暂停下载、删除下载等；
- 下载状态回调：回调下载状态、进度、本地下载路径等；
- 离线播放：指定本地下载路径，使用播放控件播放；

3、文档播放

3.1 准备BDocInfo

/**
 * 特注：因token有时间限制，以下字段请填写为您自己的信息，否则文档无法显示。
 */
String host = "BCEDOC"; // 开放云传回的host
String docId = "doc-gkjraanw4f89uu5"; // 开放云传回的docId
String docType = "doc"; // 开放云传回的文档类型 doc/ppt/ppts等
String token = "TOKEN"; // 开放云传回的token
String thisDocDir = ""; // 指定为空串""表示在线浏览
int totalPage = 3; // 总页数，必须准确填写 否则在离线浏览时会有问题
String docTitle = "百度云文档服务";
int startPage = 1; // 起始浏览页，最小值为1，请不要填入小于1的值
BDocInfo docInfo = new BDocInfo(host, docId, docType, token)
                .setLocalFileDir(thisDocDir)
                .setTotalPage(totalPage)
                .setDocTitle(docTitle)
                .setStartPage(startPage);

3.2 准备视图控件

xml方式引入播放控件:

<com.baidu.bdocreader.BDocView 
    android:id="@+id/dv_doc"
    android:layout_width="match_parent"
    android:layout_height="match_parent"/>

BDocView mDocView = (BDocView) findViewById(R.id.dv_doc);

3.3 加载文档

设置回调接口并加载文档

mDocView.setOnDocLoadStateListener(new OnDocLoadStateListener() {
    @Override
    public void onDocLoadComplete() {
        Log.d("test", "onDocLoadComplete");
    }
    @Override
    public void onDocLoadFailed(String errorDesc) {
        // errorDesc format: ERROR_XXXX_DESC(code=xxxxx)
        Log.d("test", "onDocLoadFailed errorDesc=" + errorDesc);
    }
    @Override
    public void onCurrentPageChanged(int currentPage) {
        // 记录当前页面
        Log.i("test", "currentPage = " + currentPage);
    }
});
// 加载文档
mDocView.loadDoc(docInfo);

3.4 阅读设置

3.4.1 改变字号

mDocView.setFontSize(fontSize); // fontSize为float类型，取值范围(0,2]

3.4.2 设置起始页

如需让阅读用户下次阅读时，从之前的位置继续阅读，可设置阅读起始页面。
设置： BDocInfo类中的startPage，可以设置起始页，页数从1开始。
存储： 章节3.3中的onCurrentPageChanged可以回调当前用户翻页动作。

3.4.3 设置文档预览

文档阅读器可以仅显示前几页的内容(即：仅预览前几页)，请确保在docView.loadDoc之前调用。

docInfo.enablePagePreview(2); // 仅允许用户预览文档的前2页
// docInfo.disablePagePreview() // 默认不预览，即用户可查看完整文档

4、文档下载

4.1 文档下载管理主要通过DocDownloadManager单例类来进行。

如开始(恢复)下载：

DocDownloadManager.getInstance(context, userName)
    .startOrResumeDownloader(docInfo.getDocId(),
                             docInfo.getToken(),
                             docInfo.getHost(),
                             observer);

注：userName仅用于隔离App内不同用户的文档存储路径，故只要传入可区分的字符串即可，如：md5(realUserName),若您的App不涉及用户登录逻辑，则将userName传入固定字符串即可。

DocDownloadManager单例类的下载操作方法如下表：

方法名	传入参数	备注
startOrResumeDownloader(String docId, String token, String host, DocDownloadObserver observer)	`docId`文档ID `token`token私有密钥 `host`开放云传回的host `observer`下载观察者，回调下载状态与进度	开始或继续下载
pauseDownloader(String docId)	`docId`文档ID	暂停下载
deleteDownloader(String docId)	`docId`文档ID	删除该下载，会移除该DocId的所有下载记录与本地文件
stopAll()	-	暂停所有下载，一般用于退出应用或用户登出时
changeMaxDownloadingItems(int maxItems)	`maxItems`最大并行下载数	默认为5，可接受 (0,10]的值

DocDownloadManager单例类的获取下载对象方法如下表：

方法名	传入参数	返回类型
getDocDownloadableItemByDocId(String docId)	`docId` 文档ID	DocDownloadableItem类
getAllDocDownloadableItems()	无	HashMap<String, DocDownloadableItem> 所有下载项，key为docId

4.2 下载状态回调

4.1中提到的下载观察者，为DocDownloadObserver类，您需要创建该类的子类，并在继承自该类的 update(DocDownloadableItem item) 方法中更新下载的信息。
其中，DocDownloadableItem类具有以下方法：

方法名	返回值	备注
getDocId()	String类型，文档ID	-
getLocalAbsolutePath()	String类型，本地下载路径	该路径由下载器产生，离线播放时需要您回填到BDocInfo类中
getStatus()	DownloadStatus枚举类型，下载状态	下载状态枚举为 `DOWNLOADING`下载中 `PAUSED`已暂停 `COMPLETED`下载完成 `ERROR`下载失败，可通过错误码判断原因 `DELETED`删除，仅在删除下载时回调一次，后续item就被移除了 `PENDING`等待下载，可作为`下载中`状态的一种
getProgress()	float类型，下载百分比	取值范围[0,100]
getErrorCode()	int类型，错误码	下载状态为DownloadStatus.ERROR时，该值有效，取值为：DocDownloadableItem.`ERROR_CODE_NETWORK_FAILED` 网络连接有问题 `ERROR_CODE_FETCH_ZIPURL_FAILED`获取下载zip包失败 `ERROR_CODE_ZIPSERVER_CODE_NOT_2XX`服务器返回非200/206之类的状态码 `ERROR_CODE_SDCARD_UNMOUNTED`sd卡不可读写 `ERROR_CODE_DOWNLOAD_ZIPFILE_FAILED`下载zip包失败，非以上原因导致的失败 `ERROR_CODE_DOWNLOAD_INVALID_TOKEN`token无效

4.3 离线播放

将下载完成的路径设置到BDocInfo中：

String locaDirForThisDoc = downloader.getLocalAbsolutePath();
docInfo.setLocalFileDir(locaDirForThisDoc);

之后按照第3部分中描述的文档播放步骤播放即可。

5、防混淆

-keep class com.baidu.bdocreader.** {
  public *;
}

6、FAQ

1、docId、token、host、docType等参数从哪里获取？

答：百度云提供了API接口供获取相关信息，可参考：https://cloud.baidu.com/doc/DOC/API.html

2、为何无法显示文档，也无法下载文档？

答：请确保host\docId\docType\docId\totalPage等参数均从服务端获取而非自己随意填入。另外，私有文档的显示或下载，需要token参数，该参数有时间限制。

3、文档可在线观看，但下载完成之后无法观看，请问是什么原因？

答：请参考章节4.3，确保将下载地址回填到bdocinfo中。确认回填后，仍然无法显示，请确认您填写的docType是否正确。在线观看时，docType填错了会做动态兼容，但离线观看则不行。