更新记录

1.0.0（2026-02-09）

新增功能

• ✅ 支持打开本地和网络 PDF 文件
• ✅ 支持翻页操作（上一页 / 下一页 / 指定页码）
• ✅ 支持跳转到指定页码
• ✅ 支持获取 PDF 信息（总页数、当前页）
• ✅ 支持在 PDF 上添加手写签名
• ✅ 支持添加批注（高亮、文字）
• ✅ 导出单页为图片（PNG/JPEG）

平台支持

• ✅ Android（API 21+）
• ✅ iOS（iOS 11.0+，使用 PDFKit）

平台兼容性

uni-app(4.35)

uni-app x(5.0)

其他

PDF 原生预览与签名插件

uni-app 原生 PDF 预览插件，支持预览、缩放、翻页、手写签名、批注等功能。Android/iOS 双端原生实现，性能优异，大文件不卡顿。

功能特性

• ✅ 原生预览：Android 使用 PdfRenderer，iOS 使用 PDFKit，性能优异
• ✅ 缩放翻页：支持上一页/下一页、页码跳转（UI 示例已集成）
• ✅ 手写签名：在 PDF 指定位置记录签名信息（坐标、宽高、图片路径）
• ✅ 批注功能：支持高亮、下划线、矩形框、文字批注（记录到内存结构中）
• ⚠️ 导出功能：
  • Android：exportPageToImage 导出的当前页图片中，已叠加当前页的签名和批注效果；exportPDF 目前导出的是“原文件副本”（暂未真正写入签名/批注）。
  • iOS：当前版本 exportPDF/exportPageToImage 导出结果为原始内容的渲染，尚未叠加签名/批注。
• ✅ 跨端一致：Android/iOS 一套 API，行为尽量保持一致，差异点在文档中明确说明。

说明：当前版本的 addSignature/addAnnotation 会先把签名/批注操作记录在内存中。
Android 端的 exportPageToImage 已将这些记录叠加到导出的图片中；
exportPDF() 目前仍是导出“原文件副本”，后续会把签名/批注真正写入导出的 PDF，以满足商业场景的「能签能标并导出」需求。

平台支持

安装

1. 在 DCloud 插件市场搜索「PDF 原生预览与签名插件」或 pdf-viewer
2. 点击「使用 HBuilderX 导入插件」
3. 在项目中引入插件

快速开始

1. 打开 PDF 文件

import { openPDF } from '@/uni_modules/uts-pdf-viewer'

// 打开本地 PDF
openPDF({
  path: '/static/sample.pdf',
  success: (res) => {
    console.log('打开成功，总页数：', res.pageCount)
  },
  fail: (err) => {
    console.error('打开失败：', err)
  }
})

// 打开网络 PDF
openPDF({
  path: 'https://example.com/document.pdf',
  success: (res) => {
    console.log('打开成功')
  }
})

2. 翻页操作

import { goToPage, previousPage, nextPage, getPDFInfo } from '@/uni_modules/uts-pdf-viewer'

// 跳转到第 5 页
goToPage({
  page: 5,
  success: () => {
    console.log('跳转成功')
  }
})

// 上一页
previousPage()

// 下一页
nextPage()

// 获取当前 PDF 信息
const info = getPDFInfo()
if (info) {
  console.log(`当前页：${info.currentPage} / 总页数：${info.pageCount}`)
}

3. 添加签名

import { addSignature } from '@/uni_modules/uts-pdf-viewer'

// 在 PDF 第 1 页的 (100, 200) 位置添加签名
addSignature({
  page: 1,
  signaturePath: '/static/signature.png', // 或 base64: 'data:image/png;base64,xxx'
  x: 100,
  y: 200,
  width: 150,
  height: 60,
  success: () => {
    console.log('签名添加成功')
  }
})

4. 添加批注

import { addAnnotation } from '@/uni_modules/uts-pdf-viewer'

// 添加高亮批注
addAnnotation({
  page: 1,
  type: 'highlight',
  x: 50,
  y: 100,
  width: 200,
  height: 20,
  color: '#FFFF00',
  success: () => {
    console.log('批注添加成功')
  }
})

// 添加文字批注
addAnnotation({
  page: 1,
  type: 'text',
  x: 50,
  y: 100,
  width: 200,
  height: 30,
  text: '这是批注内容',
  color: '#FF0000',
  success: () => {
    console.log('文字批注添加成功')
  }
})

5. 导出 PDF

import { exportPDF } from '@/uni_modules/uts-pdf-viewer'

// 导出 PDF（当前版本导出“原文件副本”，尚未真正写入签名和批注）
exportPDF({
  outputPath: '/storage/exported.pdf',
  includeAnnotations: true,
  success: (res) => {
    console.log('导出成功：', res.outputPath)
  }
})

6. 导出单页为图片

import { exportPageToImage } from '@/uni_modules/uts-pdf-viewer'

// 导出第 1 页为 PNG
// Android：导出的图片中会叠加当前页的签名和批注（高亮、下划线、矩形、文字）
// iOS：当前版本导出的是原始页面缩略图，暂未叠加签名和批注
exportPageToImage({
  page: 1,
  outputPath: '/storage/page1.png',
  format: 'png',
  success: (res) => {
    console.log('导出成功：', res.outputPath)
  }
})

API 文档

openPDF(options)

打开 PDF 文件。

参数：

• path (string): PDF 文件路径（本地路径或网络 URL、本地 content:// 等）
• success (function, 可选): 成功回调
• fail (function, 可选): 失败回调
• complete (function, 可选): 完成回调

返回值： 无

closePDF()

关闭当前打开的 PDF。

getPDFInfo()

获取当前 PDF 信息（同步方法）。

返回值： PDFInfo | null

goToPage(options)

跳转到指定页码。

参数：

• page (number): 目标页码（从 1 开始）
• animated (boolean, 可选): 是否使用动画
• success (function, 可选): 成功回调
• fail (function, 可选): 失败回调
• complete (function, 可选): 完成回调

previousPage()

跳转到上一页。

nextPage()

跳转到下一页。

addSignature(options)

添加签名到 PDF。

参数：

• page (number): 页码（从 1 开始）
• signaturePath (string): 签名图片路径（本地路径或 base64）
• x (number): X 坐标
• y (number): Y 坐标
• width (number, 可选): 签名宽度
• height (number, 可选): 签名高度
• success (function, 可选): 成功回调
• fail (function, 可选): 失败回调
• complete (function, 可选): 完成回调

addAnnotation(options)

添加批注到 PDF。

参数：

• page (number): 页码（从 1 开始）
• type (string): 批注类型（'highlight' | 'underline' | 'rectangle' | 'text'）
• x (number): 起始 X 坐标
• y (number): 起始 Y 坐标
• width (number): 宽度
• height (number): 高度
• text (string, 可选): 批注内容（type 为 'text' 时使用）
• color (string, 可选): 批注颜色（十六进制，如 '#FF0000'）
• success (function, 可选): 成功回调
• fail (function, 可选): 失败回调
• complete (function, 可选): 完成回调

exportPDF(options)

导出 PDF。

参数：

• outputPath (string): 导出文件路径
• includeAnnotations (boolean, 可选): 是否包含签名和批注
• success (function, 可选): 成功回调
• fail (function, 可选): 失败回调
• complete (function, 可选): 完成回调

exportPageToImage(options)

导出单页为图片。

参数：

• page (number): 页码（从 1 开始）
• outputPath (string): 导出图片路径
• format (string, 可选): 图片格式（'png' | 'jpeg'，默认 'png'）
• quality (number, 可选): 图片质量（1-100，仅 jpeg 有效，默认 90）
• success (function, 可选): 成功回调
• fail (function, 可选): 失败回调
• complete (function, 可选): 完成回调

错误码

注意事项

1. 文件路径：本地文件建议使用绝对路径或 uni.getFileSystemManager() 获取的路径
2. 网络文件：插件会自动下载网络 PDF 到临时目录，下载完成后才打开
3. 内存管理：大文件预览时注意内存占用，建议预览完成后调用 closePDF() 释放资源
4. 签名和批注：当前版本中，签名和批注会记录在内存中：
   • Android：调用 exportPageToImage() 导出的当前页图片会叠加签名和批注效果；exportPDF() 仍导出原始 PDF 副本，尚未真正写入签名和批注。
   • iOS：exportPDF/exportPageToImage 目前均导出原始内容的渲染结果，暂未叠加签名和批注。
5. H5 平台：H5 平台会降级使用系统打开或 pdf.js，部分功能可能受限

常见问题

Q: 支持哪些 PDF 格式？
A: 支持标准 PDF 1.0+ 格式。关于加密 PDF：iOS（PDFKit）支持带密码的 PDF；Android 端基于 PdfRenderer，当前不支持加密 PDF，调用时会返回明确错误提示。

Q: 签名和批注会直接修改原文件吗？
A: 不会。签名和批注仅记录在内存中：Android 端导出单页图片时会叠加这些效果，但 exportPDF() 目前仍导出原文件副本（不包含签名和批注）；iOS 端导出的 PDF/图片暂时也不包含签名和批注。

Q: 支持表单填写吗？
A: 当前版本不支持表单填写，后续版本可能会添加。

Q: 可以在小程序中使用吗？
A: 不支持。小程序平台建议使用 web-view 组件打开 PDF。