更新记录

2.5.3（2023-03-16）

Android文档预览openFile方法

• 解决图片预览时，上下滑动和拖动冲突问题

2.5.2（2023-03-10）

Android文档预览openFile方法

• 新增参数isSaveImg：是否长按保存图片

平台兼容性

原生插件通用使用流程：

1. 购买插件，选择该插件绑定的项目。
2. 在HBuilderX里找到项目，在manifest的app原生插件配置中勾选模块，如需要填写参数则参考插件作者的文档添加。
3. 根据插件作者的提供的文档开发代码，在代码中引用插件，调用插件功能。
4. 打包自定义基座，选择插件，得到自定义基座，然后运行时选择自定义基座，进行log输出测试。
5. 开发完毕后正式云打包

付费原生插件目前不支持离线打包。
Android 离线打包原生插件另见文档 https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/android
iOS 离线打包原生插件另见文档 https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/ios

注意事项：使用HBuilderX2.7.14以下版本，如果同一插件且同一appid下购买并绑定了多个包名，提交云打包界面提示包名绑定不一致时，需要在HBuilderX项目中manifest.json->“App原生插件配置”->”云端插件“列表中删除该插件重新选择

一、注意事项

• manifest.json->App模块配置不要勾选Android X5 Webview`

• 不要同时使用其他任何预览插件，否则，会引起打包冲突

• 如遇预览失败，（1）把APP卸载，重新打基座运行，第一次运行会自动安装X5插件；（2）或者换手机（华为或小米）进行测试

• url或参数中是否含有中文字符串，请使用encodeURIComponent或encodeURI进行转码，详细说明见下面问题二

二、问题解决

问题一：

问题描述：真机测试有4部手机测试， 小米MAX3、坚果pro2 、华为P20 这个三个手机测试预览都能成功，小米redmi K30 预览 就不成功， "canLoadVideo": false, "canLoadX5": false, "coreVersion": 0, "sdkVersion": 43967, "canLoadX5FirstTimeThirdApp": false, "isCoreInited": true X5内核没有加载成功，反复卸载APP和重新打包基座好几次了，X5内核都是没有加载成功，这个问题该如何解决

后面想了一下可能是CPU支持类型的问题，

解决方案：manifest.json -APP常用其他设置 -支持CPU类型 armeabi-v7a arm64-v8a 两个都勾选的，

重新打一下自定义基座 问题就解决了。

问题二：

插件安装成功，但是文档预览失败。

解决方案：检查文档url或参数中是否含有中文字符串，如果有，请使用encodeURIComponent或encodeURI进行转码。

如果参数有http://链接，使用encodeURIComponent；如果要对整个url进行转码，使用encodeURI

encodeURIComponent和encodeURI区别

它们都是编码URL，唯一区别就是编码的字符范围，其中

encodeURI方法不会对下列字符编码 ASCII字母 数字 ~!@#$&*()=:/,;?+'

encodeURIComponent方法不会对下列字符编码 ASCII字母 数字 ~!*()'

所以encodeURIComponent比encodeURI编码的范围更大。

各位同学，对于插件使用还有疑问的，可以加QQ群（170683293）咨询。

三、快速上手

demo工程地址 或在右上角直接下载示例工程

开发工具：HBuilderX

Step1. 下载demo工程，使用HBuilderX打开

Step2. 下载本文插件

插件名称：Seal-OfficeOnline

点击右上角试用或者购买，选择你的云打包插件

Step3. 选择manifest.json->App原生插件配置中加载云端插件

Step4. 使用插件

• 在vue或nvue组件中，导入插件

const sealOfficeOnlineModule = uni.requireNativePlugin("Seal-OfficeOnline")

• openFile方法（推荐）：支持Android和IOS，预览Office文件，支持如下格式：pdf、txt、doc、docx、xls、xlsx、ppt、pptx、epub等
• openFileWPS方法（推荐）：采用本机WPS客户端预览或编辑文档，支持pdf、txt、doc、xls、ppt等多种文件格式。
• checkWps方法：检查本机WPS客户端是否已经安装。
• openFileBS方法：仅支持Android，打开在线文档，支持Excel在线编辑，PPT全屏浏览，查看最近打开文件，发送分享文档，采用其他应用打开等
• openFileImage方法：仅支持IOS，预览图片，支持如下格式：jpg、jpeg、png、bmp、jpg、gif等，参数同openFile方法
• getX5CoreInfo方法（调试）：获取内核安装信息，用于调试

接口使用方法，参考如下章节《四、使用方法》

Step5. 调试

• 制作自定义调试基座：在开发工具中点击“运行到手机或模拟器-》制作自定义调试基座”
• 选择自定义调试基座：然后“运行到手机或模拟器-》基座运行选择-》自定义调试基座”
• 连接真机，运行调试

四、使用方法

1、组件嵌入预览

组件名：Seal-OfficeOnline

组件嵌入预览，是采用nvue原生组件的方式，嵌入页面预览，用于页面的局部文档预览。

在线内核、离线内核均可使用，也支持自定义水印。

注意：要采用nvue原生组件方式，不可以采用vue组件方式。

支持平台：Android、IOS

新建组件：seal-officeonline-component.nvue

<template>
    <div><Seal-OfficeOnline :options="options" style="width:600rpx;height:800rpx;border: 1px solid red;"></Seal-OfficeOnline></div>
</template>

<script>
export default {
    data() {
        return {
            options: {}
        }
    },
    onLoad(params) {
        console.log('params', params)
        this.options = {
            // 文档预览，传递url
            url: params.url,
            waterMarkText: '你好，世界\n准备好了吗？时刻准备着',
        }
    }
};
</script>

2、本地（离线）文档预览

使用接口：openFIle，参数参考章节《五、openFile接口参数说明》

内核插件下载地址：地址一、地址二

本地（离线）文档预览，是离线预览手机本地文档的方式。

前提，需要传递coreUrl参数（内核在线地址）。或者将离线内核安装包本地路径传递到接口参数coreLocalPath中，也可以先从在线地址下载到本地，获取本地路径传递到参数中。

同样，文档也可以下载到手机本地，获取文档本地路径，传递到接口url参数中。

注意：添加参数isDeleteFile: false，否则退出预览，文件删除

支持平台：Android

// 方法一、传递coreUrl参数
openOfflineFile(fileUrl) {
    sealOfficeOnlineModule.openFile(
        {
            url: url,
            isDeleteFile: false,
            installOfflineCore: true, // 是否离线安装内核
            coreUrl: 'https://tbs.imtt.qq.com/release/x5/tbs_core_045738_20210925205342_nolog_fs_obfs_armeabi_release.tbs', // 离线内核包在线地址
        },
        res => {
            uni.showModal({
                content: '打开本地文档事件结果：' + JSON.stringify(res)
            });
        }
    );
}

// 方法二、传递coreLocalPath参数
/**
* 应用刚进入或页面刚进入，初始化下载内核到本机，获取本地路径
*/
downloadCoreToLocal() {
    uni.showLoading({
        title: '正在下载安装内核，请稍后~'
    });
    const coreUrl = 'https://tbs.imtt.qq.com/release/x5/tbs_core_045738_20210925205342_nolog_fs_obfs_armeabi_release.tbs';
    // const coreUrl = 'http://silianpan.cn/upload/2022/09/tbs_core_045738_20210925205342_nolog_fs_obfs_armeabi_release-c5d6cd8bba8843b780e5943f9806c028.tbs'
    uni.downloadFile({
        url: coreUrl,
        success: res => {
            if (res.statusCode === 200) {
                // 保存到应用目录
                uni.saveFile({
                    tempFilePath: res.tempFilePath,
                    success: resSave => {
                        uni.hideLoading();
                        // 获取本地路径
                        this.coreLocalPath = resSave.savedFilePath;
                    }
                });
            }
        }
    });
},

/**
* 打开本地文档
* @param {Object} fileUrl 文档url
*/
openOfflineFile(fileUrl) {
    // 方式一：直接传递本机文件绝对路径
    // 注意：添加参数`isDeleteFile: false`，否则退出预览，文件删除
    // 比如：/storage/sdcard0/Android/data/com.seal.uniplugin/files/file/test.docx
    // sealOfficeOnlineModule.openFile({
    //      url: '/storage/sdcard0/Android/data/com.seal.uniplugin/files/file/test.docx',
    //      isDeleteFile: false,
    //      installOfflineCore: true, // 是否离线安装内核
    //      coreLocalPath: this.coreLocalPath, // 离线安装内核本地路径
    //  },
    //  res => {
    //      uni.showModal({
    //          content: '打开本地文档事件结果：' + JSON.stringify(res)
    //      });
    //  });

    // 方式二：先下载文件保存到手机目录，再获取文件绝对路径
    uni.showLoading({
        title: '正在下载文件，请稍后~'
    });
    uni.downloadFile({
        url: fileUrl,
        success: res => {
            if (res.statusCode === 200) {
                // 直接传递本地文件地址
                // 传递本地文件绝对路径，res.tempFilePath的前缀是_doc，而实际目录为doc，没有下划线_，所以要substr取子串
                // const url = '/storage/sdcard0/Android/data/APP包名/apps/APPID/' + res.tempFilePath.substr(1)
                // 可以通过以下方式获取文件绝对路径
                uni.saveFile({
                    // 需要保存文件的临时路径
                    tempFilePath: res.tempFilePath,
                    success: resSave => {
                        uni.hideLoading();
                        const savedFilePath = resSave.savedFilePath;
                        // 转换为绝对路径
                        const url = plus.io.convertLocalFileSystemURL(savedFilePath);
                        console.log('tempFilePath', res.tempFilePath);
                        console.log('savedFilePath', savedFilePath);
                        console.log('url', url);
                        // 预览本地文件
                        sealOfficeOnlineModule.openFile(
                            {
                                url: url,
                                isDeleteFile: false,
                                installOfflineCore: true, // 是否离线安装内核
                                coreLocalPath: this.coreLocalPath // 离线安装内核本地路径
                            },
                            res => {
                                uni.showModal({
                                    content: '打开本地文档事件结果：' + JSON.stringify(res)
                                });
                            }
                        );
                    }
                });
            }
        }
    });
},

3、在线文档预览

使用接口：openFIle

在线文档预览，是内核初次采用在线安装，预览在线文档url地址的方式。

此方式最为简单，直接传入在线url参数即可。

支持平台：Android、IOS

/**
* 打开在线文档
* @param {Object} fileUrl 文档url
*/
openOnlineFile(fileUrl) {
    sealOfficeOnlineModule.openFile(
        {
            url: fileUrl, // 同时支持在线和本地文档，三种参数传递方式，具体查看文档说明
            title: 'Office文档在线预览', // 顶栏标题，默认为：APP名称
            topBarBgColor: '#3394EC', // 顶栏背景颜色，默认为：#3394EC（科技蓝）
            waterMarkText: '你好，世界\n准备好了吗？时刻准备着' // 水印文本
            // installOfflineCore: true, // 是否离线安装内核
            // coreLocalPath: this.coreLocalPath, // 离线安装内核本地路径
        },
        res => {
            uni.showModal({
                content: '打开在线文档事件结果：' + JSON.stringify(res)
            });
        }
    );
},

4、WPS预览或编辑文档

使用接口：openFileWPS，参数参考《六、openFileWPS接口参数说明》

WPS预览或编辑文档，是采用本机WPS客户端预览或编辑文档，支持pdf、txt、doc、xls、ppt等多种文件格式。

支持5种模式，包括文档编辑。前提，本地需要安装WPS客户端。

支持平台：Android、IOS（分享功能，第三方APP打开）

/**
* WPS预览或编辑文档
* @param {String} fileUrl 文档url
* @param {String} openMode 打开模式
* openMode取值：
* Normal：正常模式，正常打开，WPS默认打开方式
* ReadOnly：只读模式，以只读的方式打开，WPS会隐藏编辑按钮
* EditMode：编辑模式，可对文档进行编辑
* ReadMode：阅读器模式，支持左右翻页，仅Word、TXT文档支持
* SaveOnly：另存模式(打开文件,另存,关闭)，仅Word、TXT文档支持
*/
openOnlineFileWPS(fileUrl, openMode) {
    sealOfficeOnlineModule.openFileWPS(
        {
            url: fileUrl,
            openMode
        },
        res => {
            uni.showModal({
                content: 'WPS打开文档事件结果：' + JSON.stringify(res)
            });
        }
    );
},

5、检查本机是否安装WPS客户端

5.1、方法一（推荐）、使用原生接口：checkWps，无参数。

注意：返回结果格式：{ "hasWps": true }

支持平台：Android、IOS

注意：IOS配置应用访问白名单：manifest.json—》App常用其他设置—》IOS设置—》应用访问白名单，

添加：KingsoftOfficeApp,KingsoftOfficeAppEnterprise,WPSOfficeApi

/**
* 检查WPS客户端是否已经安装
* 返回结果：{ "hasWps": true }
*/
checkWps() {
    const checkWps = sealOfficeOnlineModule.checkWps();
    console.log('checkWps', checkWps);
    uni.showModal({
        content: 'WPS是否安装：' + JSON.stringify(checkWps)
    });
},

5.2、方法二、直接调用plus.runtime.isApplicationExist

参考链接：https://www.cnblogs.com/goloving/p/14384105.html

// 判断第三方程序(WPS) 是否安装
function checkApp() {
    if (plus.runtime.isApplicationExist({pname:'cn.wps.moffice_eng', action:'KingsoftOfficeApp://'})) {
      console.log("WPS应用已安装");
    } else {
      console.log("WPS应用未安装");
    }
}

6、QQ浏览服务预览文档

使用接口：openFileBS，参数参考《七、openFileBS接口参数说明》

QQ浏览服务预览文档，是调用QQ浏览服务预览文档的方式，支持Excel在线编辑，PPT全屏浏览，查看最近打开文件，发送分享文档，采用其他应用打开等。

前提，需要本机安装QQ浏览器客户端。

支持平台：Android

/**
* QQ浏览服务预览接口，支持Excel在线编辑，PPT全屏浏览，查看最近打开文件，发送分享文档，采用其他应用打开等
* 平台支持：仅Android，支持以下参数
* @param {Object} fileUrl 文档url
*/
openOnlineFileBS(fileUrl) {
    sealOfficeOnlineModule.openFileBS(
        {
            url: fileUrl, // 同时支持在线和本地文档，三种参数传递方式，具体查看文档说明
            topBarBgColor: '#3394EC', // 顶栏背景颜色，默认为：#3394EC（科技蓝）
            isDeleteFile: true // 退出是否删除缓存的文件，默认为true（删除缓存文件）
        },
        res => {
            uni.showModal({
                content: 'QQ浏览器打开文档事件结果：' + JSON.stringify(res)
            });
        }
    );
},

7、图片预览

使用接口：openFile

支持平台：Android、IOS

/**
* 图片预览，支持jpg、jpeg、png、bmp、jpg、gif等多种常用图片格式
* 图片可以来源于列表或九宫格，传递给imageUrls数组
* @param {Object} fileUrl 图片url
* @param {Object} imageCurrentIndex 当前图片位置下标，从0开始
*/
openImage(fileUrl, imageCurrentIndex) {
    if (this.platform === 'android') {
        // Android
        sealOfficeOnlineModule.openFile({
            imageUrls: this.imageList,
            imageCurrentIndex, // 当前点击图片在imageUrls中的下标，从0开始，默认为0
            imageIndexType: 'number', // 图片底部指示器类型，默认为'dot'，可选：'number':数字；'dot':点
            isSaveImg: true, // 是否长按保存图片
        });
    } else if (this.platform === 'ios') {
        // IOS
        sealOfficeOnlineModule.openFileImage(
            {
                url: fileUrl, // 同时支持在线和本地文档，三种参数传递方式，具体查看文档说明
                title: 'IOS图片预览', // 顶栏标题，默认为：APP名称
                topBarBgColor: '#3394EC' // 顶栏背景颜色，默认为：#3394EC（科技蓝）
            },
            res => {
                uni.showModal({
                    content: 'IOS图片预览事件结果：' + JSON.stringify(res)
                });
            }
        );
    }
},

8、视频播放

使用接口：openFile

支持平台：Android、IOS

/**
* 视频播放，支持市面上几乎所有的视频格式，包括mp4, flv, avi, 3gp, webm, ts, ogv, m3u8, asf, wmv, rm, rmvb, mov, mkv等18种视频格式
* 功能包括：全屏播放、锁屏、分享、画面比例调节、左边上下滑动调节亮度，右边上下滑动调节音量等
* 支持Android和IOS
* @param {Object} fileUrl 视频url
*/
openVideo(fileUrl) {
    sealOfficeOnlineModule.openFile(
        {
            videoUrl: fileUrl, // 视频在线url，此参数优先于图片预览和文档预览
            installOfflineCore: true, // 是否离线安装内核
            coreLocalPath: this.coreLocalPath // 离线安装内核本地路径
        },
        res => {
            uni.showModal({
                content: '播放视频事件结果：' + JSON.stringify(res)
            });
        }
    );
}

9、获取内核信息，用于调试

支持平台：Android

/** 获取内核信息，用于调试 
* 返回结果格式
* {
*     'isCoreInited': false, // 内核是否加载
*     'coreVersion': 0, // 内核版本
*     'sdkVersion': 43967, // sdk版本
*     'X5CoreLoadHelp': '', // 内核加载帮助信息
* }
*/
getX5CoreInfo() {
    const coreInfo = sealOfficeOnlineModule.getX5CoreInfo();
    console.log('coreInfo', coreInfo);
    uni.showModal({
        content: '插件内核信息：' + JSON.stringify(coreInfo)
    });
},

五、openFile接口参数说明

支持打开在线文档，本地文档

支持平台：Android、IOS

六、openFileWPS接口参数说明

本机WPS客户端预览或编辑文档

支持平台：Android、IOS（分享功能，第三方APP打开）

另，openMode打开模式说明：

七、openFileBS接口参数说明

QQ浏览服务打开在线文档

同openFile接口参数，支持：url，fileType，fileName，isDeleteFile，initTitle，initBody，docDownloadTitle，docDownloadBody，installOfflineCore，coreLocalPath，coreUrl，topBarBgColor

支持平台：Android

• 支持QQ浏览器在线编辑、全屏播放、阅读模式等
• 支持QQ浏览器打开46种文件格式文件
• 查看最近打开文件
• 发送分享文档
• 采用其他应用打开等

八、回调结果

1、回调结果格式：

// openFile、OpenFileBS接口
{
    "code": 200,
    "msg": "文档预览成功",
    "result": {
        // 本地文件名
        "fileName": "test.docx",
        // 本地文件路径，前提，参数isDeleteFile=false，否则预览预览结束，本地文件被删除
        "filePath": "/storage/sdcard0/Android/data/com.seal.uniplugin/files/file/test.docx"
    }
}

// OpenFileWPS接口
{
    "code": 1021,
    "msg": "WPS动作事件",
    "result": {
        // 本地文件名
        "fileName": "test.docx",
        // 本地文件路径，前提，参数isDeleteFile=false，否则预览预览结束，本地文件被删除
        "filePath": "/storage/sdcard0/Android/data/com.seal.uniplugin/files/file/test.docx",
        // WPS动作类型：back，返回键；home，Home键；save，保存文件；close，关闭文件
        "actionType": "back",
        // 文件另存为本机路径
        "fileSavePath": "/storage/sdcard0/Android/Download/test2.docx"
    }
}

2、回调结果状态码说明：

3、WPS动作事件类型actionType说明

支持平台：Android

九、后续计划

• [x] 添加水印
• [x] 支持小窗口模式
• [ ] 支持右上角自定义菜单
• [x] 支持当前页面回调

十、Android预览效果

预览docx

预览pptx

预览xlsx

预览pdf

预览txt

iOS预览效果

预览docx

预览pptx

预览xlsx

预览pdf

预览txt

转载请注明：我的技术分享 » 跨平台文件在线预览解决方案（四）-Android和IOS原生插件