更新记录

4.3.1（2025-04-12）

Android组件嵌入预览

• 弹出对话框增加手动取消关闭对话框事件回调，code: 1016
• 修复targetPage参数跳页不准确问题

4.3.0（2024-12-21）

• 嵌入式组件支持自定义事件回调函数

4.1.3（2024-10-08）

• 新增参数showProgressDialog，控制是否显示弹出框，并且在回调函数中打印进度过程日志（返回码1015）
• IOS新增closeFile和removeCacheFile接口，详情查看README

平台兼容性

原生插件通用使用流程：

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原生插件配置”->”云端插件“列表中删除该插件重新选择

〇、前言

2023年3月13日，腾讯发布了调整公告：关于腾讯浏览服务内核SDK-内核文档能力调整公告，公告里面明确说明了：2023年4月13日零时起，内核文档能力正式下线。插件2.x版本使用了腾讯X5云服务能力，已经上线的项目需要及时升级插件到3.x版本哟，3.x版本不再依赖腾讯X5以及任何第三方插件，完全可以在内网环境中使用，同时支持在线文档和设备本地文档。

支持国产ofd，支持wps、doc、docx、xls、xlsx、csv、ppt、pptx、txt、properties、log、Log、ini、lua、conf、m、cpp、java、h、xml、html、htm等常见文档格式。

原生Android项目离线集成，查看Demo工程及README文档： Seal-Office-Android-Demo

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

一、快速上手

Github克隆（demo工程地址 ）或在右上角直接下载示例工程

安装开发工具：HBuilderX

安装依赖包环境：NodeJS

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

• 代码根目录下执行

  npm install --registry https://registry.npmmirror.com

Step2. 添加本文插件

插件名称：Seal-OfficeOnline

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

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

Step4. 使用插件

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

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

• initEngine方法：插件首次初始化（在应用启动时进行调用），注意：如果第一次进入空白，才进行手动初始化，否则不用调用此接口。
• openFile方法（推荐）：支持Android和IOS，预览Office文件，支持如下格式：国产ofd、pdf、txt、doc、docx、xls、xlsx、ppt、pptx、epub等近50种类型文件，同时支持常见的音视频格式。
• gotoPage方法：跳转文档指定页码。
• openFileWPS方法（推荐）：采用本机WPS客户端预览或编辑文档，支持pdf、txt、doc、xls、ppt等多种文件格式。
• checkWps方法：检查本机WPS客户端是否已经安装。
• openFileImage方法：仅支持IOS，预览图片，支持如下格式：jpg、jpeg、png、bmp、jpg、gif等，参数同openFile方法。
• removeCacheFile方法：仅支持Android，删除缓存文件。
• closeFile方法：关闭文档预览。

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

Step5. 调试

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

二、使用方法

0、插件首次初始化（在应用启动时进行调用）

注意：如果第一次进入空白，才进行手动初始化，否则不用调用此接口。

// 注意：如果第一次进入空白，请使用以下代码手动初始化
uni.showLoading({
  title: '插件首次初始化中'
});
sealOfficeOnlineModule.initEngine(res => {
  this.printInfo('插件首次初始化结果：', res);
  if (res.code === 1) {
    this.initPluginFirstSuccess = true;
    uni.showToast({
      title: '插件首次初始化成功',
      duration: 2000
    });
  } else {
    this.initPluginFirstSuccess = false;
  }
  uni.hideLoading();
})

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,
      // 顶部状态栏自定义菜单功能按钮
      menuItems: ['下载', '分享'],
    },
    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);
  //                        }
  //                    );
  //                }
  //            });
  //        }
  //    }
  // });
},

（1）跳转文档指定页码，注意：需要等文档加载完成之后，才能调用此接口，如果需要直接跳转，在openFile接口中传递targetPage参数

使用接口：gotoPage(int targetPage)

参数：targetPage，指定页码

sealOfficeOnlineModule.gotoPage(5)

2、组件嵌入预览

组件名：Seal-OfficeOnline

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

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

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

支持平台：Android、IOS

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

温馨提示：添加@callback="handleCallback"可以获取回调结果，参考第七章节回调结果

<template>
    <div>
        <!-- 预览区域 -->
        <Seal-OfficeOnline :options="options" @callback="handleCallback"
            style="width:600rpx;height:800rpx;border: 1px solid red;"></Seal-OfficeOnline>
        <!-- 操作区域 -->
        <div style="margin: 20px 10px 0 10px;">
            <button type="primary" @click="handleRandomChangeDoc">随机切换</button>
        </div>
    </div>
</template>

<script>
    const modal = uni.requireNativePlugin('modal');
    export default {
        data() {
            return {
                options: {},
                docList: [
                    'http://silianpan.cn/upload/2022/01/01/2.pdf',
                    'http://silianpan.cn/upload/2022/01/01/1.txt',
                    'http://silianpan.cn/upload/2022/01/01/2.txt',
                    'http://silianpan.cn/upload/2022/01/01/1.docx',
                    'http://silianpan.cn/upload/2022/01/01/2.docx',
                    'http://silianpan.cn/upload/2022/01/01/1.xlsx',
                    'http://silianpan.cn/upload/2022/01/01/1.pptx',
                    'http://silianpan.cn/upload/2022/01/01/1.csv',
                    'https://static.gongkaoleida.com/2021/file/download/2021湖南省公务员考试《报考指导手册》.pdf',
                    'https://static.gongkaoleida.com/2021/file/download/' + encodeURIComponent('2021湖南省公务员考试《报考指导手册》') + '.pdf',
                ],
            }
        },
        onLoad(params) {
            console.log('params', params)
            this.options = {
                // 文档预览，传递url
                url: params.url,
                waterMarkText: '你好，世界\n准备好了吗？时刻准备着',
                // 禁止截屏
                canScreenshot: false,
            }
        },
        methods: {
            // 生成0~max之间的随机整数
            getRandomInt(max) {
              return Math.floor(Math.random() * max);
            },
            handleCallback(e) {
                console.log('callback: ', e.detail)
                modal.toast({
                    message: JSON.stringify(e.detail),
                    duration: 2,
                });
            },
            // 随机切换文档
            handleRandomChangeDoc() {
                this.options = {
                    ...this.options,
                    url: this.docList[this.getRandomInt(this.docList.length)]
                };
            }
        }
    };
</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

注意：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)
    });
},

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种视频格式，以及mp3，wav，wma，flac等音频格式
* 功能包括：播放、暂停、重播、全屏播放、直播等
* 支持Android和IOS
* @param {String} fileUrl 音视频url
*/
openVideo(fileUrl) {
  sealOfficeOnlineModule.openFile(
    {
      videoUrl: fileUrl,
      isLive: true,
      title: '音视频播放标题',
      isTopBar: true,
      isBackArrow: false,
      topBarBgColor: '#F77234',
      topBarTextColor: '#FCF26B',
      topBarTextLength: 12
    },
    res => {
      this.printInfo('播放音视频事件结果：', res);
    }
  );
}

7、删除缓存文件

使用接口：removeCacheFile

支持平台：仅支持Android

sealOfficeOnlineModule.removeCacheFile({
  filePath: 'xxx'
}, res => {});
或
sealOfficeOnlineModule.removeCacheFile({
  url: 'xxx',
  fileName: 'xxx', // 可选
  fileType: 'xxx', // 可选
}, res => {});

8、关闭文档预览

使用接口：closeFile

支持平台：目前仅支持Android

sealOfficeOnlineModule.closeFile();

三、openFile接口参数说明

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

支持平台：Android、IOS

四、openFileWPS接口参数说明

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

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

另，openMode打开模式说明：

五、回调结果

1、回调结果格式

// openFile接口
{
    "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

六、预览效果

1、Android

• 嵌入预览

  

• 预览docx

  

• 预览pptx

  

• 预览xlsx

  

• 预览pdf

  

• 预览txt

  

• 预览mp4

  

• 预览jpg

  

2、IOS

• 嵌入预览

  

• 预览docx

  

• 预览pptx

  

• 预览xlsx

  

• 预览pdf

  

• 预览txt

  

• 预览mp4

  

• 预览jpg

  

转载请注明：我的技术分享 » 跨平台Office文档预览原生插件，非腾讯X5，支持离线，稳定高可用