更新记录

0.1.0（2026-06-13） 下载此版本

初次提交

平台兼容性

uni-app x(5.0)

其他

laoqianjunzi-pdf

laoqianjunzi-pdf 是一个面向 uni-app x 的 PDF 能力插件，提供以下两类能力：

• 页面内嵌预览组件：适合在业务页中直接展示 PDF。
• 受管 PDF 会话 API：适合在 App 端做翻页、批注、签名、导出图片、导出 PDF 等流程化处理。

插件同时提供了一个可直接运行的示例页：uni_modules/laoqianjunzi-pdf/pages/index。

功能概览

• 内嵌 PDF 预览组件 laoqianjunzi-pdf
• 通过插件页面打开 PDF 预览 launchPdfPreview
• 使用系统能力打开 PDF openPdfWithSystem
• 选取 PDF 文件 pickPdf
• 打开受管会话 openManagedPdf
• 获取受管会话状态 getManagedPdfState
• 受管会话翻页 moveManagedPdfPage previousManagedPdfPage nextManagedPdfPage
• 添加文本批注/高亮/下划线/矩形批注 addPdfAnnotation
• 添加签名图像 addPdfSignature
• 导出整份 PDF exportManagedPdf
• 导出指定页为图片 exportPdfPageImage
• 清理插件临时文件 clearPdfTempFile

平台支持

说明：

• Web 端当前定位为预览入口，不提供受管签批会话。
• Harmony 端当前未接入原生文件选择器，因此 pickPdf 会直接返回失败回调。
• Harmony 端 openPdfWithSystem 在非本地系统路径下会自动回退到插件预览页。

目录说明

uni_modules/laoqianjunzi-pdf/
├─ components/laoqianjunzi-pdf/laoqianjunzi-pdf.uvue  # 内嵌预览组件
├─ pages/index.uvue                                   # 综合演示页/插件预览页
├─ utssdk/index.uts                                   # API 导出入口
├─ utssdk/interface.uts                               # 类型定义
└─ hybrid/html/pdf-reader.html                        # 预览层页面

快速开始

1. 在页面中使用预览组件

<template>
  <view class="page">
    <laoqianjunzi-pdf
      class="pdf-viewer"
      :path="pdfPath"
      :quality="2"
      :zoom="1"
      :mode="'paged'"
      :show-toolbar="true"
      @load="handleLoad"
      @error="handleError"
      @pageChange="handlePageChange"
      ref="viewerRef"
    />
  </view>
</template>

<script setup lang="uts">
import { ref } from 'vue'

const pdfPath = ref('https://mozilla.github.io/pdf.js/web/compressed.tracemonkey-pldi-09.pdf')

function handleLoad(_payload: Map<string, any>): void {
  console.log('PDF load ok')
}

function handleError(payload: Map<string, any>): void {
  console.log('PDF load fail', payload.get('errMsg'))
}

function handlePageChange(payload: Map<string, any>): void {
  console.log('page changed', payload.get('currentPage'), payload.get('totalPages'))
}
</script>

<style>
.page {
  flex: 1;
}

.pdf-viewer {
  flex: 1;
}
</style>

2. 在脚本中调用插件 API

import {
  launchPdfPreview,
  openManagedPdf,
  getManagedPdfState,
  exportManagedPdf,
  exportPdfPageImage
} from '@/uni_modules/laoqianjunzi-pdf'

launchPdfPreview({
  source: 'https://mozilla.github.io/pdf.js/web/compressed.tracemonkey-pldi-09.pdf',
  title: '插件预览页'
})

openManagedPdf({
  source: '/storage/emulated/0/Download/demo.pdf',
  success: (_res) => {
    const state = getManagedPdfState()
    console.log('managed state', state)
  }
})

exportPdfPageImage({
  page: 1,
  outputPath: '',
  success: (res) => {
    console.log('image path', res.outputPath)
  }
})

exportManagedPdf({
  outputPath: '',
  includeMarkup: true,
  success: (res) => {
    console.log('pdf path', res.outputPath)
  }
})

组件 API

组件名称

• laoqianjunzi-pdf

Props

Events

组件实例方法

通过 ref 获取组件实例后可调用以下方法：

页面 API

launchPdfPreview(options)

打开插件内置页面 uni_modules/laoqianjunzi-pdf/pages/index。

参数：

说明：

• 该页面支持通过 path 与 title 查询参数直接打开。
• Web、Android、iOS、Harmony 都支持该预览入口。

openPdfWithSystem(options)

交给系统默认能力打开 PDF。

参数：

说明：

• Web 端会通过浏览器新标签页打开。
• Harmony 端当路径不适合系统直接打开时，会回退到插件预览页。

pickPdf(options)

让用户选择一个 PDF 文件。

返回：

说明：

• Android、iOS、Web 支持。
• Harmony 当前版本返回 1111，需要业务侧自行选取文件后再把路径传给插件。

受管会话 API

以下能力主要用于 App 端对 PDF 做进一步处理。使用顺序通常为：

1. openManagedPdf
2. getManagedPdfState
3. moveManagedPdfPage / previousManagedPdfPage / nextManagedPdfPage
4. addPdfAnnotation / addPdfSignature
5. exportPdfPageImage / exportManagedPdf
6. closeManagedPdf

openManagedPdf(options)

打开一份受管 PDF 会话。

成功回调返回：

getManagedPdfState()

返回当前受管会话状态，没有会话时返回 null。

moveManagedPdfPage(options)

跳转到指定页，页码从 1 开始。

previousManagedPdfPage() 与 nextManagedPdfPage()

切换受管会话当前页。

addPdfAnnotation(options)

添加批注。

addPdfSignature(options)

添加签名图片。

exportManagedPdf(options)

导出当前受管 PDF。

成功回调返回：

exportPdfPageImage(options)

导出指定页为图片。

closeManagedPdf()

关闭当前受管会话。

clearPdfTempFile(path?)

清理插件临时文件。

• 传入 path 时清理指定临时文件。
• 不传时由平台侧按插件实现策略清理。

错误码

示例页说明

插件自带综合演示页：uni_modules/laoqianjunzi-pdf/pages/index

这个页面会展示：

• PDF 地址输入与示例链接填充
• 组件内嵌预览
• 组件翻页、缩放、质量、模式切换
• 受管会话打开与状态同步
• 批注、签名、导出图片、导出 PDF
• 插件页预览与系统打开能力

如果你只想把这个页面当作纯预览页使用，也可以直接带参数打开：

/uni_modules/laoqianjunzi-pdf/pages/index?path=<编码后的PDF地址>&title=<编码后的标题>

使用建议

• 页面内嵌阅读优先使用组件 laoqianjunzi-pdf。
• 业务流程需要签批、导出、状态查询时，优先使用受管会话 API。
• 仅需要快速打开文件时，优先调用 launchPdfPreview 或 openPdfWithSystem。
• App 端建议先验证 PDF 源路径可访问，再调用受管会话 API。
• 需要签名时，请先准备好本地签名图片路径，再调用 addPdfSignature。