更新记录

1.0.0（2026-10-03）

• 首次发布：uni-app x 标准模式 PDF 预览组件（蒸汽模式，Android，基于 MuPDF）
  • 打开本地 / file:// / http(s) 远程 PDF，支持加密文档密码
  • 适配宽度 / 整页适配双模式，手势滑动与点击翻页、双指捏合与 API 缩放
  • 回调式 API（open / close / goToPage / nextPage / prevPage / zoomIn / zoomOut / setFitMode）
  • 事件：load / pageChange / rendered / error，错误码 9030001 ~ 9030009

平台兼容性

uni-app x(4.36)

其他

zy-pdf-viewer

PDF 阅读器 uni-app x 标准模式组件（支持蒸汽模式）（uts-vue-component），基于 MuPDF（com.artifex.mupdf:fitz）实现。

• 仅实现 Android（iOS / HarmonyOS 未提供）
• 单页阅读模式：适配宽度 / 整页适配，滑动与点击翻页、双指缩放

功能

• 打开本地绝对路径、file://、http(s) 远程 PDF，支持加密文档密码
• 适配宽度（默认）/ 整页适配两种模式，可动态切换
• 翻页：左右滑动、点击屏幕两侧、goToPage / nextPage / prevPage
• 缩放：双指捏合、zoomIn / zoomOut
• 放大后单指平移（横向、纵向均可），到页边继续滑动自动翻页
• 页码与状态事件：load / pageChange / rendered / error
• 方法采用回调式 API（success / fail），同时通过事件回传

快速开始

easycom 规范，无需 import 即可直接使用：

<template>
    <view class="page">
        <zy-pdf-viewer ref="pdfRef" class="pdf" :src="src" @load="onLoad"
            @pageChange="onPageChange" @rendered="onRendered" @error="onError"></zy-pdf-viewer>
        <button @click="next">下一页</button>
    </view>
</template>

<script setup lang="uts">
    const pdfRef = ref<ComponentPublicInstance | null>(null)
    const src = ref<string>("https://mozilla.github.io/pdf.js/web/compressed.tracemonkey-pldi-09.pdf")

    function onLoad(pageCount: number) {
        console.log("已打开，共 " + pageCount + " 页")
    }

    function onPageChange(page: number, pageCount: number) {
        console.log("第 " + page + " / " + pageCount + " 页")
    }

    function onRendered(page: number, pageCount: number) {
        console.log("第 " + page + " 页渲染完成")
    }

    function onError(code: number, message: string) {
        console.log("错误 " + code + " " + message)
    }

    function next() {
        pdfRef.value?.$callMethod('nextPage', {
            success: (result) => {
                console.log(result.msg + " 当前第 " + result.data["page"] + " 页")
            },
            fail: (error) => {
                console.log(error.code + " " + error.message)
            }
        })
    }
</script>

<style>
    .pdf {
        width: 100%;
        flex: 1;
        min-height: 200px;
    }
</style>

组件根节点是 <native-view>，必须设置明确的宽高（常用 width: 100% + flex: 1 撑满父容器，或固定 height）。

调用说明

• 组件已通过 defineExpose 显式暴露全部方法，vapor 模式下使用 $callMethod('方法名', options) 调用。
• success / fail 每次调用最多触发一次，回调在主线程派发。
• 各方法的回调触发时机：

• getPageCount / getCurrentPage 为同步查询方法，直接返回数字（未打开时返回 0），无回调。
• src 变化（绑定响应式数据或再次 open）会自动重新打开文档。

手势交互

Props

API

方法

所有异步方法的 success 收到 PdfResult { code, msg, data }，fail 收到 PdfError { code, message }。

类型定义见 utssdk/interface.uts。

Options 类型

事件

错误码

注意事项

• 组件根为 <native-view>，需自身具备宽高；背景、边框、圆角等装饰样式建议写在外层 <view> 上，不要依赖组件根节点。
• 渲染带有像素预算保护（约 80MB 位图 + 100MB 画布上限），超大页面会自动限制最大缩放倍数，避免 Canvas: trying to draw too large bitmap 崩溃。
• 远程 PDF 会先下载到应用缓存目录再打开，失败回传 9030005。
• 页面切换时若页码已到边界（首页 / 末页），翻页方法不产生变化但仍然回调成功。
• 组件在 onUnmounted 时自动释放原生资源，页面卸载前无需手动销毁。

目录结构

zy-pdf-viewer/
├── components/zy-pdf-viewer/zy-pdf-viewer.uvue   # easycom 组件（方法转发 + defineExpose）
├── utssdk/
│   ├── interface.uts                             # 类型定义（Options / PdfResult / PdfError）
│   ├── unierror.uts                              # 错误码定义（9030001 ~ 9030009）
│   └── app-android/
│       ├── index.uts                             # PdfViewer：回调管理 + 事件桥接
│       ├── PdfPageView.kt                        # 原生渲染与手势（MuPDF）
│       └── config.json                           # MuPDF maven 依赖与仓库声明
├── changelog.md
└── readme.md

参考

• UTS 语法
• UTS 插件
• UTS 插件-标准模式组件
• MuPDF