跨平台Office文档预览原生插件,非腾讯X5,支持离线,稳定高可用

发布于:2023-04-29 ⋅ 阅读:(833) ⋅ 点赞:(0)

引言

2023年4月13日零时起,腾讯浏览服务内核文档能力正式下线,要实现真正离线文档预览,于是有了这边文章。

前面写了多篇关于<跨平台文件在线预览解决方案>,不管使用pdf.js、LibreOffice,还是永中DCS,各自都有自己的优缺点,比如:pdf.js不支持双指放大缩小,LibreOffice加载缓慢,永中DCS收费等等。

本文基于uni-app平台实现了Office文档在线预览原生插件Seal-OfficeOnline,同时支持Android和iOS,欢迎下载使用~,

另外单独抽离了图片预览和视频播放原生插件:Seal-ImageVideo,根据自己情况,选择使用~,Seal-ImageVideo插件下载使用地址,另附Github文档地址

Seal-OfficeOnline插件下载使用地址

<span style="color:red">各位同学,对于插件使用还有疑问的,可以加QQ群(170683293)咨询。</span>

<div class="half">

<img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/3c2197fec1c246049301059beac293e3~tplv-k3u1fbpfcp-zoom-1.image" height="600" style="height:600px" />

<img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/ea7a059dfdf143c29f33424bce36a600~tplv-k3u1fbpfcp-zoom-1.image" height="600" style="height:600px" />

</div>

一、注意事项

  • 本插件不需要其他任何配置,也不需要依赖其他任何库,不要在manifest.json->App模块配置中勾选Android X5 Webview`
  • 不要同时使用其他同类文档预览插件,否则,可能会引起包冲突
  • url或参数中是否含有中文字符串,请使用encodeURIComponentencodeURI进行转码,详细说明见下面“问题一”

二、问题解决

问题一:

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

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

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

encodeURIComponent和encodeURI区别

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

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

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

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

<span style="color:red">各位同学,对于插件使用还有疑问的,可以加QQ群(170683293)咨询。</span>

三、快速上手

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

开发工具:HBuilderX

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

Step2. 添加本文插件

插件名称:Seal-OfficeOnline

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

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

<img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/54e4d10fda594fb8846cdf2705ad2aeb~tplv-k3u1fbpfcp-zoom-1.image" width="600" style="width:600px" />

Step4. 使用插件

  • 在vue或nvue组件中,导入插件
const sealOfficeOnlineModule = uni.requireNativePlugin("Seal-OfficeOnline")
  • openFile方法(推荐):支持Android和IOS,预览Office文件,支持如下格式:pdf、txt、doc、docx、xls、xlsx、ppt、pptx、epub等近50种类型文件。
  • openFileWPS方法(推荐):采用本机WPS客户端预览或编辑文档,支持pdf、txt、doc、xls、ppt等多种文件格式。
  • checkWps方法:检查本机WPS客户端是否已经安装。
  • openFileImage方法:仅支持IOS,预览图片,支持如下格式:jpg、jpeg、png、bmp、jpg、gif等,参数同openFile方法

<span style="color:red">接口使用方法,参考如下章节《四、使用方法》</span>

Step5. 调试

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

四、使用方法

1、离线文档预览,非腾讯TBS,摆脱内核加载困扰,支持在线文档URL

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

离线文档预览,非腾讯TBS,无内核加载,摆脱腾讯X5内核加载失败的困扰。

同时支持在线文档URL或设备本地文档绝对路径。

两种使用方式,一,直接传递文档在线URL,二,先下载到设备本地,传递绝对路径,参考一下代码。

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

支持平台:Android、IOS

/**
* 打开文档,非腾讯TBS,无内核加载,真正离线
* @param {Object} fileUrl 文档url
*/
openFile(fileUrl) {
  // 方式一:直接传递文件在线url
  sealOfficeOnlineModule.openFile(
    {
      url: fileUrl, // 同时支持在线和本地文档,三种参数传递方式,具体查看文档说明
      // fileType: 'pdf',
      // fileName: 'example',
      title: 'Office文档在线预览', // 顶栏标题,默认为:APP名称
      topBarBgColor: '#3394EC', // 顶栏背景颜色,默认为:#3394EC(科技蓝)
      waterMarkText: '你好,世界\n准备好了吗?时刻准备着', // 水印文本
      docRequestHeaders: {
        'Authorization': 'Token xxxxxxxx',
        'Other': 'other'
      }, // 文档下载请求头
      isDeleteFile: false,
      topBarAutoHide: true,
      isTopBar: true,
    },
    res => {
      this.printInfo('打开在线文档事件结果:', 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
  //                         },
  //                         res => {
  //                             this.printInfo('打开本地文档事件结果:', res);
  //                         }
  //                     );
  //                 }
  //             });
  //         }
  //     }
  // });
},

2、组件嵌入预览

组件名:Seal-OfficeOnline

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

在线文档URL和离线设备文档均可预览,也支持自定义水印。

注意:要采用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>

3、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)
            });
        }
    );
},

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

4.1、方法一(推荐)、使用原生接口:checkWps,无参数。

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

支持平台:Android、IOS

<span style="color:red">注意:IOS配置应用访问白名单:</span>manifest.json—》App常用其他设置—》IOS设置—》应用访问白名单,

添加:KingsoftOfficeApp,KingsoftOfficeAppEnterprise,WPSOfficeApi

<img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/8669acf9bccc42538488fe18806442e6~tplv-k3u1fbpfcp-zoom-1.image" alt="应用访问白名单" style="zoom: 50%;" />

/**
* 检查WPS客户端是否已经安装
* 返回结果:{ "hasWps": true }
*/
checkWps() {
    const checkWps = sealOfficeOnlineModule.checkWps();
    console.log('checkWps', checkWps);
    uni.showModal({
        content: 'WPS是否安装:' + JSON.stringify(checkWps)
    });
},
4.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应用未安装");
    }
}

5、图片预览

使用接口:openFile(Android)、openFileImage(IOS)

支持平台: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)
                });
            }
        );
    }
},

6、视频播放

使用接口: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)
            });
        }
    );
}

五、openFile接口参数说明

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

支持平台:Android、IOS
参数名 说明 类型 是否必填 默认值 可选值
url 支持如下三种地址方式:
(1)文件网络地址,如:http://113.62.127.199:8090/fileUpload/1.xlsx
(2)手机本地文件地址,如:/data/user/0/APP包名/files/1.xlsx 文件名,如:1.xlsx,
(3)访问默认目录文件,默认目录为:/data/user/0/APP包名,如:com.HBuilder.UniPlugin
注意:手机本地地址目录需要有权限访问<br/><span style="color:red">IOS端只支持在线地址</span>
string
docRequestHeaders 文档下载请求头,如:
{ 'Authorization': 'Token xxxxxxxx', 'Other': 'other' }
,<span style="color:red">IOS端无此配置</span>
object
fileType 可以指定文件类型,如:xlsx,在url参数无法判断文件类型时,可以指定文件类型 string
fileName 指定文件名,如:file1,注意此处不带文件扩展名,如果同时指定fileName和fileType,那么最后的文件名通过这两个参数组合起来,即:fileName.fileType string
isDeleteFile 退出是否删除缓存的文件,<span style="color:red">IOS端无此配置</span> bool true false
initTitle 初始化插件动画标题,<span style="color:red">IOS端无此配置</span> string 插件初始化
initBody 初始化插件动画内容,<span style="color:red">IOS端无此配置</span> string 加载中...
docDownloadTitle 文档下载进度框标题,<span style="color:red">IOS端无此配置</span> string 加载文档
docDownloadBody 文档下载进度框内容,<span style="color:red">IOS端无此配置</span> string 请稍后...
waterMarkText 水印文本,默认以\n作为分隔符换行 string null
waterMarkTextSep 水印文本分隔符,<span style="color:red">注意:IOS端只支持\n换行</span> string \n
waterMarkFontSize 水印字体大小,单位为sp
使用sp作为字体大小单位,会随着系统的字体大小改变
int 13
waterMarkFontColor 水印字体颜色 string #40F3F5F9
waterMarkDegree 水印旋转角度,<span style="color:red">IOS端无此配置</span> string -30(逆时针30度)
isTopBar 是否显示顶栏,<span style="color:red">IOS端无此配置</span> bool true false
title 顶栏标题,isTopBar为true时有效 string APP名称
topBarAutoHide 顶栏是否自动隐藏,isTopBar=true时生效,<span style="color:red">IOS端无此配置</span> bool false true
topBarHeight 顶栏自定义高度,isTopBar为true时有效,类型为正整数,<span style="color:red">IOS端无此配置</span> int actionBarSize
topBarBgColor 顶栏背景颜色,isTopBar为true时有效 string #3394EC(科技蓝)
topBarTextColor 顶栏文本颜色(isTopBar为true时有效) string #FFFFFF(白色)
topBarTextLength 顶栏标题文字长度(isTopBar为true时有效),<span style="color:red">IOS端无此配置</span> int 12
isBackArrow 是否显示返回按钮(isTopBar为true时有效),<span style="color:red">IOS端无此配置</span> bool true false
videoUrl 视频在线url,此参数优先于图片预览和文档预览 string
imageUrls 图片url数组,此参数优先于文档预览;长按图片底部弹出保存图片菜单,保存图片至相册,<span style="color:red">IOS端无此配置</span> array<string>
imageCurrentIndex 当前点击图片在imageUrls中的下标,从0开始,<span style="color:red">IOS端无此配置</span> int 0
imageIndexType 图片底部指示器类型,<span style="color:red">IOS端无此配置</span> string 'dot' 'number':数字;'dot':点
isSaveImg 是否长按保存图片,<span style="color:red">IOS端无此配置</span> bool null true/false

六、openFileWPS接口参数说明

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

支持平台:Android、IOS(分享功能,第三方APP打开)
参数名 说明 类型 是否必填 默认值 可选值
url 支持如下三种地址方式:
(1)文件网络地址,如:http://113.62.127.199:8090/fileUpload/1.xlsx
(2)手机本地文件地址,如:/data/user/0/APP包名/files/1.xlsx 文件名,如:1.xlsx,
(3)访问默认目录文件,默认目录为:/data/user/0/APP包名,如:com.HBuilder.UniPlugin
注意:手机本地地址目录需要有权限访问<br/><span style="color:red">IOS端只支持在线地址</span>
string
fileType 可以指定文件类型,如:xlsx,在url参数无法判断文件类型时,可以指定文件类型,<span style="color:red">IOS端无此配置</span> string
fileName 指定文件名,如:file1,注意此处不带文件扩展名,如果同时指定fileName和fileType,那么最后的文件名通过这两个参数组合起来,即:fileName.fileType,<span style="color:red">IOS端无此配置</span> string
docDownloadTitle 文档下载进度框标题,<span style="color:red">IOS端无此配置</span> string 加载文档
docDownloadBody 文档下载进度框内容,<span style="color:red">IOS端无此配置</span> string 请稍后...
openMode 打开模式:
Normal:正常模式,正常打开,WPS默认打开方式
ReadOnly:只读模式,以只读的方式打开,WPS会隐藏编辑按钮
EditMode:编辑模式,可对文档进行编辑
ReadMode:阅读器模式,支持左右翻页,仅Word、TXT文档支持
* SaveOnly:另存模式(打开文件,另存,关闭),仅Word、TXT文档支持
string Normal 见说明

另,openMode打开模式说明:

打开模式 说明
Normal 正常模式,正常打开,WPS默认打开方式
ReadOnly 只读模式,以只读的方式打开,WPS会隐藏编辑按钮
EditMode 编辑模式,可对文档进行编辑
ReadMode 阅读器模式,支持左右翻页,仅Word、TXT文档支持
SaveOnly (不常用)另存模式(打开文件,另存,关闭),仅Word、TXT文档支持

七、回调结果

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、回调结果状态码说明:

状态码 说明
200 文档预览成功
301 文档下载失败
302 内核下载失败,自动重新下载
303 内核安装失败,自动重新安装
304 内核加载失败,可忽略该错误
305 内核下载失败,可忽略该错误
1001 文档下载成功
1002 开始初始化内核
1003 开始离线安装内核
1004 开始在线安装内核
1005 内核下载成功
1006 内核安装成功
1007 内核初始化成功
1008 缓存文档删除成功
1021 WPS动作事件

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

支持平台:Android
动作类型 说明
back 返回键
home Home键
save 保存文件
close 关闭文件

八、后续计划

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

九、Android预览效果

预览docx

<img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/ad58f115348c4de8b07f134ee4a2bed2~tplv-k3u1fbpfcp-zoom-1.image" height="600" style="height:600px" />

预览pptx

<img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/49ed6333c7bc47f18e870fabef336956~tplv-k3u1fbpfcp-zoom-1.image" height="600" style="height:600px" />

预览xlsx

<img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/974130ffe87f4400bf65ef09d9e9d119~tplv-k3u1fbpfcp-zoom-1.image" height="600" style="height:600px" />

预览pdf

<img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/558466c941b6489ca24ec0f28cc2c28c~tplv-k3u1fbpfcp-zoom-1.image" height="600" style="height:600px" />

预览txt

<img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/82c3921eca3f4a24a751bcbbcef63838~tplv-k3u1fbpfcp-zoom-1.image" height="600" style="height:600px" />

iOS预览效果

预览docx

<img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/88e14b1a2cb042b4bd7864dbfb498411~tplv-k3u1fbpfcp-zoom-1.image" height="600" style="height:600px" />

预览pptx

<img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/f0f0e4498af04b6e80fc04a504d212ae~tplv-k3u1fbpfcp-zoom-1.image" height="600" style="height:600px" />

预览xlsx

<img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/347fc40efe474063a5222afe7ba6a26e~tplv-k3u1fbpfcp-zoom-1.image" height="600" style="height:600px" />

预览pdf

<img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/05192d08957a417fbd0cdbaf73600f70~tplv-k3u1fbpfcp-zoom-1.image" height="600" style="height:600px" />

预览txt

<img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/4ba44da97df34544b4a77f5ea4b278ac~tplv-k3u1fbpfcp-zoom-1.image" height="600" style="height:600px" />

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

本文含有隐藏内容,请 开通VIP 后查看