Android文档播放器使用说明

1、工程配置

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

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
tokentoken私有密钥
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_UNMOUNTEDsd卡不可读写
ERROR_CODE_DOWNLOAD_ZIPFILE_FAILED下载zip包失败,非以上原因导致的失败
ERROR_CODE_DOWNLOAD_INVALID_TOKENtoken无效
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填错了会做动态兼容,但离线观看则不行。