更新记录

1.2.2（2026-10-24）

初始化版本 支持xlsx、pdf、docx、txt文档预览

平台兼容性

uni-app(4.0)

其他

muzi-officePreview

App 端（Android / iOS）纯前端解析的文档预览插件，一行组件即可唤起全屏预览。 解析库全部内置打包，离线可用、不依赖任何 CDN，文件在手机本地完成解析，不经过第三方服务。

• 支持：PDF、Word(.docx/.docm/.dotx)、Excel(.xlsx/.xlsm/.xltx)、TXT(.txt)、图片(.jpg/.png/.gif/.webp/.bmp/.svg)
• 不支持：老版二进制 .doc / .xls、PPT（会给出"建议导出为 PDF 后预览"的提示）
• 运行环境：App 端 Vue2 页面（Android 10.0+ / iOS 12.0+），不支持 H5 与小程序

一、插件接入

导入普通授权版插件/导入源码授权版插件

二、基本用法

<template>
    <view>
        <button @click="previewVisible = true">预览文档</button>

        <muzi-officePreview
            url="https://your-domain.com/files/contract.pdf"
            :visible.sync="previewVisible"
        ></muzi-officePreview>
    </view>
</template>

<script>
export default {
    data() {
        return {
            previewVisible: false
        }
    }
}
</script>

把 url 换成自己的文件地址（必须 http/https），通过 visible 控制显隐即可。

地址没有文件后缀时

下载地址形如 https://xxx.com/api/file?id=1 时无法识别类型，需要用 file-type 指定， 并建议传 fileName（同时决定保存时的文件名）：

<muzi-officePreview
    url="https://your-domain.com/api/file/download?id=1001"
    file-type="pdf"
    fileName="产品说明书.pdf"
    :visible.sync="previewVisible"
></muzi-officePreview>

file-type 可选值：pdf / word / excel / text / image。

三、完整用法

<template>
    <view>
        <button @click="handleOpen">预览合同</button>

        <muzi-officePreview
            :url="fileUrl"
            fileName="2026年度合同.pdf"
            :visible.sync="previewVisible"
            :max-size="60"
            theme="auto"
            @loaded="handleLoaded"
            @error="handleError"
            @progress="handleProgress"
            @save="handleSave"
            @close="handleClose"
        ></muzi-officePreview>
    </view>
</template>

<script>
export default {
    data() {
        return {
            fileUrl: 'https://your-domain.com/files/contract.pdf',
            previewVisible: false
        }
    },
    methods: {
        handleOpen() {
            this.previewVisible = true
        },
        handleLoaded(info) {
            // { type, fileName, size, pageCount, path }
            console.log('预览完成', info)
        },
        handleError(err) {
            // { code, message }
            console.log('加载失败', err)
        },
        handleProgress(data) {
            // { progress, stage } stage：download / parse
            console.log('加载进度', data.progress)
        },
        handleSave(data) {
            console.log('已保存', data.savedFilePath)
        },
        handleClose() {
            console.log('已关闭')
        }
    }
}
</script>

常用参数

常用事件

四、可选配置

暗黑模式

在 manifest.json 的 app-plus 节点下增加：

"darkmode": true,
"themeLocation": "theme.json"

并在项目根目录创建 theme.json：

{
    "light": {
        "bgColor": "#FFFFFF",
        "bgColorPage": "#F5F6F8",
        "textColor": "#1F2329",
        "lineColor": "#E5E6EB",
        "primaryColor": "#EF3912"
    },
    "dark": {
        "bgColor": "#1C1C1E",
        "bgColorPage": "#000000",
        "textColor": "#E5E5EA",
        "lineColor": "#3A3A3C",
        "primaryColor": "#FF6B45"
    }
}

组件默认使用上面的 CSS 变量，主题色可自行调整。

体积裁剪

只需要某几种格式时，可删除 static/muzi-officePreview/vendor/ 中多余的库， 详见 vendor/README.md。缺少库时组件会给出提示，不会崩溃。

五、常见问题

Q：老版 .doc / .xls、PPT 打不开？

A：它们无法在纯前端解析。请在服务端转换为 .docx / .xlsx，或把 PPT 导出为 PDF 后再预览。

Q：真机运行需要自定义基座吗？

A：不需要。本插件不含任何原生代码，属于纯前端插件，标准真机运行即可调试。

Q：预览出不来？

A：检查是否使用了 visible.sync（组件通过 update:visible 回写关闭状态）， 以及 pages.json 中的 easycom 规则是否配置正确。

Q：控制台怎么只看预览日志？

A：过滤关键字 [muzi-officePreview]，组件的下载、解析、交互节点都会打印日志。

常见错误码

六、更新记录

见 changelog.md。