更新记录

1.4.2（2026-09-06）

• 归并 uni-app x Android 示例修复：调用方显式构造公开 Options 类型，结果和错误回调按真实类型读取，避免示例运行时对象转换异常；版本号保持 1.4.2。
• 移除 Android 组件重复导入的 PDF 选项类型，修复 UTS bundler 合并时的内部 panic。
• 修复 uni-app x Android 组件在 UTS 合并生成 Kotlin 时，OpenPdfOptions、ClosePdfOptions 等选项类型不可见导致的编译失败。
• 为打开、翻页、搜索、批注和撤销/重做回调补充明确结果类型，公开 API 和运行逻辑保持不变。
• Android UTS 组件代码已变化，升级后需要重新制作并安装匹配的 Android 自定义基座或正式包。

1.4.1（2026-08-25）

• 修复 Android 云打包生成 Kotlin 时，HarmonyOS 专用图片操作名义子类错误进入 Android，调用父类型构造函数缺少必填 type 参数，导致 compileReleaseKotlin 失败。
• Android 生成逻辑改为直接构造包含 type=create-images 的强类型 PdfProcessOperation；公开 API、原生依赖、权限与 Manifest 均未改变。
• Android UTS 生成代码已变化，升级后需要重新制作并安装匹配的 Android 自定义基座或正式包。

1.4.0（2026-08-24）

• 修复 HarmonyOS 图片转 PDF 操作对象、可空错误消息与原生异常重抛的 ArkTS 严格类型编译错误，并补齐 create-images 公开操作类型。
• 新增多图片生成 PDF，支持 A4、Letter、自动/自定义尺寸、方向、边距和 contain/cover/stretch。
• 新增文字/图片水印、页面范围、单个/平铺/九宫格/自定义位置、透明度与旋转。
• 新增页码模板 {page}、{total}、{documentPage}、跳过首页、奇偶页和镜像位置。
• 新增默认串行、最高并发 2 的 PDF 批处理，支持部分失败、failFast、整批取消和逐项结果。
• 图片支持本地、网络及平台内容 URI；PNG、JPEG、WebP 和 GIF 首帧按平台真实解码，失败返回 9041022。
• 延续 FIFO、取消、加密拒绝、输出重开校验、安全覆盖恢复和 32MP/200MP 图片资源限制。
• Android、iOS、HarmonyOS 原生桥接均有变化，升级后必须重新制作并安装对应匹配自定义基座或正式包。

平台兼容性

uni-app(5.07)

uni-app x(5.07)

lizhao-pdf-pro

一句话能力说明

一套强类型 UTS API 打通 Android、iOS、Web 与 HarmonyOS 的 PDF 阅读、签批、图片生成、文档增强和批量交付流程。

Android/iOS 提供完整原生签批与真实写回；Web 内置 PDF.js 与 pdf-lib；HarmonyOS 使用官方 PDF Kit。四端统一支持九类批注、100 步撤销重做、跨端草稿和新 PDF 写回，uni-app x 额外提供页面内嵌原生 PdfView。

功能特色

• Android 使用系统 PdfRenderer，iOS 使用 PDFKit，不依赖 WebView 截图模拟。
• Web 自带 PDF.js、Worker 与 pdf-lib，安装后即可编译，支持阅读、搜索、九类批注、草稿、撤销重做和真实 PDF 写回。
• HarmonyOS 对接官方 PDF Kit，提供阅读、搜索、九类批注、跨端草稿、新 PDF 写回和页面图片；uni-app x 支持原生内嵌阅读与连续/单页布局。
• 支持本地、网络、密码 PDF、目录、缩略图、正文搜索和任务取消。
• 九类批注：文字、高亮、下划线、删除线、矩形、笔迹、签名、印章、水印。
• 稳定 annotationId、100 步撤销/重做和跨 Android/iOS/Web/HarmonyOS 的版本化草稿。
• 写回生成新 PDF，源文件不变；输出经重新打开校验后原子完成。
• 支持 PNG/JPEG 页面导出、系统打印、系统分享。
• 网络源支持 ETag/Last-Modified、304、过期清理和容量 LRU。
• 会话使用 sessionId + generation 隔离，旧异步结果不会覆盖新文档。
• 多张 PNG、JPEG、WebP 或 GIF 首帧可生成 A4、Letter、自动尺寸或自定义尺寸 PDF。
• 支持文字/图片水印、页码变量和默认串行、最高并发 2 的批量交付；单项失败不会吞掉其他结果。

接入方式选择

文档处理中心

文档处理能力不要求先创建阅读会话。调用后立即返回独立 taskId，任务进入 FIFO 队列；progress 可持续接收读取、处理、校验和发布进度，cancelPdfTask 可取消排队中或执行中的任务。

处理结果始终是新文件或新的 Web Blob URL。默认不覆盖已有文件；显式覆盖时，App 端会先备份旧目标，全部输出重新打开验证成功后才发布。多输入合并不能覆盖任何输入文件，拆分任务遵循“全部成功或全部回滚”。

图片生成与批量交付

最小图片生成示例

import { createPdfFromImages } from "@/uni_modules/lizhao-pdf-pro"

createPdfFromImages({
  images: [
    { itemId: 'cover', source: coverImagePath },
    { itemId: 'body', source: bodyImagePath, rotation: 90 }
  ],
  page: {
    size: 'a4',
    orientation: 'auto',
    imageFit: 'contain',
    margin: { top: 24, right: 24, bottom: 24, left: 24 }
  },
  success(res) {
    console.log(res.outputFiles[0])
  },
  fail(error) {
    console.error(`${error.errCode}：${error.errMsg}`)
  }
})

水印与页码

import { addPdfPageNumbers, addPdfWatermark } from "@/uni_modules/lizhao-pdf-pro"

addPdfWatermark({
  input: { source: sourcePdfPath },
  watermark: {
    kind: 'text',
    text: 'INTERNAL',
    layout: 'tile',
    opacity: 0.2,
    rotation: -30
  }
})

addPdfPageNumbers({
  input: { source: sourcePdfPath },
  pageNumber: {
    template: '{page} / {total}',
    startNumber: 1,
    position: 'bottom-center',
    mirrorOddEven: false
  }
})

英文和数字使用上述最小配置即可跨四端运行。中文字体边界如下：

• iOS 使用系统 PingFang，可直接绘制中文。
• Android 需通过 fontSource 传入 App 可读的 TTF/OTF 本地路径；否则明确失败，不输出方框。
• HarmonyOS 可通过 fontSource 传入可读字体路径，上线前应在目标设备核对字形覆盖。
• Web 当前仅支持标准英文/数字字体；中文或自定义字体返回 9041016。

Android/HarmonyOS 中文配置示例：watermark: { kind: 'text', text: '内部资料', fontSource: fontPath }。字体文件必须具有合法嵌入和商用授权。

批量交付

import { batchProcessPdf } from "@/uni_modules/lizhao-pdf-pro"

batchProcessPdf({
  concurrency: 1,
  failFast: false,
  items: [
    {
      itemId: 'contract-a',
      inputs: [{ source: firstPdfPath }],
      operations: [{ type: 'page-number', pageNumber: { template: '{page}/{total}' } }]
    },
    {
      itemId: 'contract-b',
      inputs: [{ source: secondPdfPath }],
      operations: [{ type: 'rotate', selection: { pages: [1] }, degrees: 90 }]
    }
  ],
  success(res) {
    console.log(`成功 ${res.successCount}，失败 ${res.failedCount}，取消 ${res.cancelledCount}`)
  }
})

批次正常完成调度后触发顶层 success，单项失败记录在 items 中；只有批次参数或调度器本身失败才触发顶层 fail。

createPdfFromImages(options) 参数

batchProcessPdf(options) 参数

场景选择表

最小合并示例

import { mergePdf } from "@/uni_modules/lizhao-pdf-pro"

const taskId = mergePdf({
  inputs: [
    { source: firstPdfPath, sourceType: 'local' },
    { source: secondPdfPath, sourceType: 'local' }
  ],
  output: { path: mergedPdfPath, overwrite: false },
  progress(res) {
    console.log(`合并进度：${res.progress}%`)
  },
  success(res) {
    console.log(`已生成 ${res.outputFiles.length} 份 PDF`)
  },
  fail(error) {
    console.error(`${error.errCode}：${error.errMsg}`)
  },
  complete() {
    console.log('合并任务结束')
  }
})

拆分示例

import { splitPdf } from "@/uni_modules/lizhao-pdf-pro"

splitPdf({
  input: { source: contractPath, sourceType: 'local' },
  parts: [
    { name: 'cover', selection: { pages: [1] } },
    { name: 'body', selection: { ranges: [{ start: 2, end: 8 }] } }
  ],
  output: {
    directory: outputDirectory,
    baseName: 'contract',
    overwrite: false
  },
  success(res) {
    console.log(`拆分输出：${res.outputCount}`)
  },
  fail(error) {
    console.error(`${error.errCode}：${error.errMsg}`)
  }
})

不同拆分项可以选取相同页面；单个拆分项内部不能出现重复页码。

旋转示例

import { rotatePdfPages } from "@/uni_modules/lizhao-pdf-pro"

rotatePdfPages({
  input: { source: sourcePath, sourceType: 'local' },
  selection: {
    pages: [1],
    ranges: [{ start: 3, end: 5 }]
  },
  degrees: 90,
  output: { path: rotatedPath },
  success(res) {
    console.log(res.outputFiles[0])
  }
})

组合流水线示例

import { processPdf } from "@/uni_modules/lizhao-pdf-pro"

processPdf({
  inputs: [{ source: sourcePath, sourceType: 'local' }],
  operations: [
    { type: 'extract', selection: { ranges: [{ start: 1, end: 10 }] } },
    { type: 'delete', selection: { pages: [2] } },
    { type: 'reorder', order: [9, 8, 7, 6, 5, 4, 3, 2, 1] },
    { type: 'rotate', selection: { pages: [1] }, degrees: 90 },
    {
      type: 'split',
      parts: [
        { name: 'first', selection: { ranges: [{ start: 1, end: 4 }] } },
        { name: 'second', selection: { ranges: [{ start: 5, end: 9 }] } }
      ]
    }
  ],
  output: { directory: outputDirectory, baseName: 'processed' },
  fail(error) {
    console.error(`${error.errCode}：${error.errMsg}`)
  }
})

流水线限制：多输入第一项必须是 merge；单输入不能使用 merge；split 必须是最后一步；reorder.order 必须包含当前文档全部页码且每页只出现一次。

processPdf(options) 参数

文档处理返回值

最小 uni-app x 示例

<template>
  <lizhao-pdf-pro
    class="viewer"
    :source="source"
    :password="password"
    display-mode="continuous"
    @load="onLoad"
    @error="onError"
  />
</template>

<script setup lang="uts">
import { PdfProFail } from "@/uni_modules/lizhao-pdf-pro"

// source 应来自文件选择器、下载结果或业务参数。
const source = ref('')
// 密码只用于当前打开请求，插件不会记录密码。
const password = ref('')

function onLoad(result: UTSJSONObject): void {
  const info = result['info'] as UTSJSONObject
  console.log(`PDF 共 ${info['pageCount']} 页`)
}

function onError(error: PdfProFail): void {
  console.error(`${error.errCode}：${error.errMsg}`)
}
</script>

uni-app App-nvue 示例

普通 App-vue 页面建议跳转独立 App-nvue 页面，再嵌入组件：

<template>
  <lizhao-pdf-pro :source="source" @load="onLoad" @error="onError" />
</template>

<script>
export default {
  data() {
    return { source: '' }
  },
  methods: {
    onLoad(result) {
      console.log(`PDF 共 ${result.info.pageCount} 页`)
    },
    onError(error) {
      console.error(`${error.errCode}：${error.errMsg}`)
    }
  }
}
</script>

Web 最小示例

Web 与 App 使用同一个组件标签和公开 API。插件已内置 PDF.js，不需要在客户项目中再次安装 pdfjs-dist。

<template>
  <lizhao-pdf-pro
    class="viewer"
    :source="networkPdfUrl"
    display-mode="continuous"
    @load="onLoad"
    @error="onError"
  />
</template>

<script>
export default {
  data() {
    return {
      // Web 推荐使用 HTTPS 且允许跨域访问的 PDF 地址。
      networkPdfUrl: 'https://example.com/contracts/demo.pdf'
    }
  },
  methods: {
    onLoad(result) {
      console.log(`Web PDF 已打开，共 ${result.info.pageCount} 页`)
    },
    onError(error) {
      // 跨域、密码、损坏文件等场景都会进入 fail/error，不会伪造成功。
      console.error(`${error.errCode}：${error.errMsg}`)
    }
  }
}
</script>

Web 端如果 PDF 位于其他域名，服务端必须允许浏览器跨域读取；插件无法绕过浏览器同源策略。

Web 批注、草稿与真实写回

Web 使用与 App 相同的公开 API。编辑状态保留在会话中，exportPdf 创建新的 PDF Blob 地址，不会覆盖输入文件。

import {
  addPdfAnnotation,
  exportPdf,
  openPdf
} from "@/uni_modules/lizhao-pdf-pro"

openPdf({
  source: selectedFile,
  editable: true,
  success: (opened) => {
    const now = Date.now()
    addPdfAnnotation({
      sessionId: opened.sessionId,
      annotation: {
        annotationId: `review-${now}`,
        type: 'rectangle',
        page: 1,
        bounds: { x: 0.1, y: 0.12, width: 0.35, height: 0.18 },
        points: [],
        text: '',
        color: '#2563EB',
        opacity: 0.85,
        lineWidth: 2,
        assetPath: '',
        rotation: 0,
        pageWidth: 0,
        pageHeight: 0,
        coordinateVersion: 1,
        createdAt: now,
        updatedAt: now,
        extra: null
      },
      success: () => {
        exportPdf({
          sessionId: opened.sessionId,
          validateOutput: true,
          success: (result) => console.log(`新 PDF：${result.path}`),
          fail: (error) => console.error(error.errMsg)
        })
      }
    })
  }
})

文字与水印会转成透明图片写入 PDF；签名和印章支持 PNG/JPEG 的本地、Blob 或 HTTP(S) 资源。加密 PDF 在浏览器端无法安全重写时会返回明确错误，不会伪造成功。

HarmonyOS 批注、草稿与真实写回

HarmonyOS 与 Android、iOS、Web 使用同一套公开 API 和草稿结构。用 editable: true 打开后即可新增批注、撤销重做、导出草稿，并把完整编辑状态写入一个新的 PDF 文件。

HarmonyOS 九类批注

import {
  addPdfAnnotation,
  exportPdf,
  exportPdfDraft,
  openPdf
} from "@/uni_modules/lizhao-pdf-pro"

openPdf({
  source: selectedPdfPath,
  editable: true,
  success: (opened) => {
    const now = Date.now()
    addPdfAnnotation({
      sessionId: opened.sessionId,
      annotation: {
        annotationId: `harmony-review-${now}`,
        type: 'highlight',
        page: 1,
        bounds: { x: 0.1, y: 0.18, width: 0.5, height: 0.08 },
        points: [],
        text: '',
        color: '#FFD54F',
        opacity: 0.5,
        lineWidth: 2,
        assetPath: '',
        rotation: 0,
        pageWidth: 0,
        pageHeight: 0,
        coordinateVersion: 1,
        createdAt: now,
        updatedAt: now,
        extra: null
      },
      success: () => {
        // 草稿可在 Android、iOS、Web 与 HarmonyOS 间流转。
        exportPdfDraft({ sessionId: opened.sessionId })
        // outputPath 必须与源文件不同，成功结果使用 result.path。
        exportPdf({
          sessionId: opened.sessionId,
          outputPath: customerOutputPath,
          overwrite: false,
          validateOutput: true
        })
      }
    })
  }
})

加密 PDF 可以阅读、添加进程内批注并导入/导出草稿。HarmonyOS 在不能确保原密码和安全属性完整保留时会拒绝真实写回并返回 9041011，不会调用移除安全设置的接口，也不会生成未加密副本。

网络、密码、搜索和取消

import {
  cancelPdfTask,
  openPdf,
  searchPdfText
} from "@/uni_modules/lizhao-pdf-pro"

openPdf({
  source: networkUrl,
  sourceType: 'network',
  password: userInputPassword,
  success: (opened) => {
    const taskId = searchPdfText({
      sessionId: opened.sessionId,
      keyword: '审批意见',
      success: (result) => console.log(`命中 ${result.matches.length} 项`),
      fail: (error) => console.error(error.errMsg),
      complete: (_result) => console.log('搜索结束')
    })

    // 用户点击取消时传入原搜索任务 ID。
    cancelPdfTask({ sessionId: opened.sessionId, taskId })
  },
  fail: (error) => console.error(error.errMsg),
  complete: (_result) => console.log('打开流程结束')
})

9041005 表示需要密码，9041006 表示密码错误。公开页码均从 1 开始。

批注、草稿和真实写回

编辑前需使用 editable: true 打开文档。批注坐标采用左上角原点的归一化值，x / y / width / height 范围为 0..1。

import {
  addPdfAnnotation,
  exportPdf,
  openPdf
} from "@/uni_modules/lizhao-pdf-pro"

openPdf({
  source: selectedPdfPath,
  editable: true,
  success: (opened) => {
    const now = Date.now()
    addPdfAnnotation({
      sessionId: opened.sessionId,
      annotation: {
        annotationId: `signature-${now}`,
        type: 'signature',
        page: 1,
        bounds: { x: 0.55, y: 0.72, width: 0.3, height: 0.12 },
        points: [],
        text: '',
        color: '#000000',
        opacity: 1,
        lineWidth: 2,
        assetPath: selectedSignaturePath,
        rotation: 0,
        pageWidth: 0,
        pageHeight: 0,
        coordinateVersion: 1,
        createdAt: now,
        updatedAt: now,
        extra: null
      },
      success: () => {
        exportPdf({
          sessionId: opened.sessionId,
          outputPath: customerOutputPath,
          overwrite: false,
          validateOutput: true
        })
      }
    })
  }
})

• 草稿使用 schemaVersion=1 和 coordinateVersion=1。
• exportPdf 始终生成新 PDF，不修改会话源文件。
• 同一会话只能执行一个 PDF 导出；冲突返回 9041017。
• Android 分享成功表示系统面板已呈现；系统无法确认目标 App 最终发送，因此 completed=false。

完整示例

• uni-app App-nvue：uni_modules/lizhao-pdf-pro/example/uniapp/pdfPro.nvue
• uni-app x：uni_modules/lizhao-pdf-pro/example/uniappx/index.uvue

完整示例包含阅读、搜索、批注签章、草稿、写回、页面图片、打印分享和缓存管理。

组件 API

属性

showNavigation / showOutline / followPageScroll / pagePadding 是 Web 阅读体验增强属性；原生端翻页和目录仍通过公开 API 或示例工作台控制。

事件

组件方法

通过组件 ref 调用。调用前应等待 @load，组件卸载后不要继续复用旧实例。

<template>
  <lizhao-pdf-pro
    ref="pdfViewer"
    :source="source"
    @load="onReady"
    @page-change="onPageChange"
  />
</template>

<script>
export default {
  data() {
    return { source: '', ready: false }
  },
  methods: {
    onReady() {
      // @load 后再调用组件实例方法。
      this.ready = true
    },
    nextPage() {
      if (this.ready) this.$refs.pdfViewer.goToPage(2)
    },
    onPageChange(result) {
      console.log(`当前第 ${result.page} 页`)
    }
  }
}
</script>

API 列表

所有 API 均从 @/uni_modules/lizhao-pdf-pro 根目录导入。

能力与平台差异

“明确失败”表示 API 保持一致，但会通过 fail 和 complete 返回 9041016，不会返回虚假成功。

openPdf(options) 参数

searchPdfText(options) 参数

exportPdf(options) 参数

clearPdfCache(options) 参数

通用结果字段

错误码

支持平台

权限、缓存与自定义基座

• 网络 PDF 需要网络权限；本地文件需由业务取得合法读取权限。
• 密码、完整路径、URL、批注正文和签章图片不会写入插件日志。
• clearPdfCache 默认不删除任何层，活动会话源文件始终受保护。
• 页面图片建议保持默认最大长边 2048；大文档预览优先使用缩略图 API。
• 文档处理最多 50 个输入、2000 页、单文件 256 MiB、合计 512 MiB；App 端临时可用空间至少为预计输出的两倍再加 64 MiB。
• 加密 PDF 可以继续按既有阅读能力打开，但 processPdf 处理链路统一返回 9041020，不接受密码字段，也不会生成未加密副本。
• 本插件包含 Android Kotlin、iOS Swift 和 Android PDFBox 依赖，首次接入或原生代码更新后必须重新制作对应平台自定义基座。
• HarmonyOS 核心桥接要求 HarmonyOS 5.0.0(API 12) 及以上和 SystemCapability.OfficeService.PDFService.Core。
• uni-app x HarmonyOS 组件使用官方内嵌 PdfView；安装新自定义基座后，应在业务真机验证本地/网络文件、九类批注、草稿往返、新 PDF 写回、连续/单页切换和销毁重建。
• appResource/WGT 不能替换已经编译进旧基座的原生代码。

第三方许可见 THIRD_PARTY_NOTICES.md。

常见问题

为什么打开网络 PDF 失败，但浏览器直接访问地址正常？

Web 必须满足浏览器跨域规则。请检查 PDF 响应是否允许当前站点域名、HTTPS 页面是否请求了 HTTP 资源，以及鉴权 Cookie/请求头是否能在浏览器环境中发送。Android/iOS 网络下载不受浏览器 CORS 限制，但仍受业务鉴权和网络安全配置约束。

为什么普通 App-vue 页面不直接显示原生 PDF View？

Android/iOS 的完整阅读器是原生 View。uni-app 普通 App-vue 建议跳转到独立 App-nvue 阅读页；uni-app x 可直接使用标准模式组件。只调用信息、搜索、导出等 API 时不要求页面嵌入组件。

为什么 Web 批注成功，但页面上看不到签名或导出失败？

签名和印章必须是浏览器可读取的 PNG/JPEG，本地文件建议使用文件选择器得到的 Blob；远程资源需要满足 CORS。加密 PDF、损坏资源或并发导出会进入 fail，不会生成看似成功的空文件。导出结果是新的 Blob 地址，关闭其新会话后该地址会被释放。

密码会不会被缓存或打印到日志？

不会。密码只参与当前打开请求；插件日志不记录密码、完整 URL、完整本地路径、批注正文和签章图片内容。

页码和批注坐标怎么计算？

公开页码从 1 开始。批注坐标使用左上角原点的归一化坐标，x / y / width / height 范围为 0..1，这样草稿可以跨 Android/iOS/Web/HarmonyOS 和不同页面尺寸复用。

为什么改完插件后页面更新了，但原生能力没变化？

Android Kotlin、iOS Swift、HarmonyOS UTS 原生代码和原生依赖会编译进自定义基座。修改这些文件后必须重新原生联编或重做对应平台自定义基座；仅更新 WGT/appResource 不能替换旧基座里的原生代码。

推荐业务组合

作者系列 UTS 插件

以下为已在 DCloud 插件市场上架的作者系列 UTS 插件，可按业务场景组合使用。未列出的插件表示当前未确认公开市场页，后续上架后再补充。