更新记录

1.2.1（2026-07-29）

• 修复 Android 云打包生成 Kotlin 时的泛型、整数下标、可空快照、抽象 Number 构造和失败闭包返回类型错误。
• 修复普通 uni-app Android 错误生成 uni-app x 专属 UniNativeViewElement、getAndroidActivity 和 bindAndroidView 引用的问题。
• 清理 uni-app nvue 示例中 Android 不支持的 min-height 样式告警。
• Android 云打包已由用户确认成功；公开 API、Android/iOS 原生依赖和 Manifest 均未改变。
• Android UTS 联编代码包含修复，使用本版本做真机验收时需要重新制作并安装匹配的 Android 自定义基座。

1.2.0（2026-07-29）

• HarmonyOS 使用官方 PDF Kit 补齐文字、高亮、下划线、删除线、矩形、手写、签名、印章和水印九类批注。
• HarmonyOS 支持稳定批注 ID、100 步撤销/重做、schemaVersion=1 跨端草稿导入导出和新 PDF 真实写回。
• 写回采用独立临时文件并重新打开核对页数与批注 ID，源文件保持不变；同会话并发导出返回明确冲突错误。
• 加密 PDF 可继续阅读和维护草稿，但在无法保证安全属性完整保留时拒绝真实写回，不会静默生成未加密副本。
• 示例补齐九类批注入口；uni-app x HarmonyOS 原生组件在编辑成功后同步当前页。
• 本版本修改 HarmonyOS 原生 UTS/ETS 代码，必须重新制作并安装 Harmony 自定义基座或原生包；Android/iOS/Web 无需因本次升级重做基座。

1.1.1（2026-07-29）

• 修复 Harmony 真机 CompileArkTS 的 HTTP、ImagePacker、回调结构类型和数值转换编译错误。
• uni-app 与 uni-app x 的 Harmony native-view 类型按平台条件隔离，避免普通 uni-app 工程引用不可见的原生 View 类型。
• 已通过 HBuilderX 5.15 的 uni-app 与 uni-app x Harmony appResource 编译、导出验证。
• 本版本修改了 Harmony 原生 UTS 实现，发布后必须重新制作并安装 Harmony 自定义基座或原生包；Android/iOS 无需因本次修复重新制作基座。

平台兼容性

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 隔离，旧异步结果不会覆盖新文档。

接入方式选择

最小 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。
• 本插件包含 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 插件

以下均为已确认公开市场页的作者系列插件，可按业务场景组合使用。