更新记录

0.6.10（2026-08-23）

• 该插件使用AI - gpt5.6开发，测试了IOS 安卓 鸿蒙 均正常。
• PDF 生成新增 logo 插入能力，支持 top-left、top-center、top-right、center、bottom-left、bottom-center、bottom-right 和 custom 定位，并支持 first / all 页面范围。
• 图片块与 Logo 统一支持本地路径、file://、unifile:// 以及 HTTP(S)/FTP 远程地址，生成前会先下载到临时文件再排版。
• 首页工作台导出默认在首页 PDF 右上角插入品牌 Logo。

平台兼容性

uni-app x(5.23)

其他

simple-pdf

simple-pdf 是面向 uni-app x Vapor 的独立 PDF 插件，包含结构化 PDF 生成、文件保存、系统查看器和页面内原生预览

原生嵌入式预览

<simple-pdf-view> 会直接嵌入当前页面：Android 使用系统 PdfRenderer，iOS 使用系统 PDFKit，HarmonyOS 使用系统 @kit.PDFKit。组件必须设置明确高度。

<simple-pdf-view
  ref="pdfView"
  :src="pdfPath"
  :page="0"
  :swipe-horizontal="false"
  :show-scroll="true"
  style="width: 100%; height: 560px;"
  @load="onPdfLoad"
  @fail="onPdfFail"
  @pageChanged="onPdfPageChanged"
/>

组件事件包括 load、fail、pageChanged。组件实例暴露 render、jumpTo、nextPage、prevPage、getPageSize 和 destroy。

Android 的系统 PdfRenderer 不提供密码解密接口，因此 Android 遇到加密 PDF 会触发 fail；iOS 与 HarmonyOS 支持通过 password 打开加密文档。

生成 PDF

import { createPdf } from '@/uni_modules/simple-pdf'

const result = await createPdf({
  fileName: 'expense-report.pdf',
  title: '支出统计',
  logo: {
    imagePath: '/static/logo.png',
    anchor: 'top-right',
    pages: 'first',
    width: 40,
    height: 40,
    fit: 'contain'
  },
  blocks: [
    {
      type: 'statCards',
      columnCount: 3,
      cards: [
        { label: '记录总金额（元）', value: '1680.00' },
        { label: '有效金额（元）', value: '1280.00', tone: 'success' },
        { label: '作废金额（元）', value: '400.00', tone: 'danger' }
      ]
    },
    { type: 'table', columns: ['类型', '金额'], rows: [['采购', '1280.00']] }
  ]
})

支持 title、paragraph、keyValue、statCards、table、chart、image、spacer、logo。logo 默认显示在首页右上角；logo.anchor 支持 top-left、top-center、top-right、center、bottom-left、bottom-center、bottom-right 和 custom；logo.pages 支持 first 和 all；自定义位置使用 x / y，角落锚点可额外使用 margin。statCards 支持一至四列卡片和 default、success、danger、info 语义色；表格支持自动换行、跨页和跨页重复表头，并可通过 headerBold 控制表头粗细，通过 bodyFontSize 控制正文字号，通过 borderless 输出无边框轻量表格。

原生图表

chart 支持 bar、progress、line、pie、donut。坐标轴、网格、图例和标签分别通过 showAxes、showGrid、showLegend、showLabels 控制。折线图默认不绘制数值为 0 的点，可通过 showZeroValues: true 显式显示 0。

HarmonyOS 端会把单个图表分组先栅格化为一张 PNG 再插入 PDF，避免大量 PDFKit annotation 或 image object 导致主线程冻结。

const chartBlocks: SimplePdfBlock[] = [
  {
    type: 'chart',
    chartType: 'bar',
    text: '月度收支',
    categories: ['1月', '2月', '3月'],
    series: [
      { name: '收入', values: [3200, 4100, 3800], color: '#3491FA' },
      { name: '支出', values: [2100, 2600, 2400], color: '#FF8F1F' }
    ],
    showAxes: true,
    showGrid: true,
    showLegend: true,
    showLabels: true,
    height: 220
  },
  {
    type: 'chart',
    chartType: 'progress',
    text: '课程消耗进度',
    maxValue: 100,
    items: [
      { label: '书法班', value: 82, color: '#3491FA' },
      { label: '阅读班', value: 64, color: '#2BA471' }
    ],
    height: 120
  },
  {
    type: 'chart',
    chartType: 'donut',
    text: '支出构成',
    items: [
      { label: '采购', value: 1280, color: '#3491FA' },
      { label: '维护', value: 680, color: '#2BA471' },
      { label: '其他', value: 320, color: '#FF8F1F' }
    ],
    showLegend: true,
    showLabels: true,
    height: 210
  }
]

柱状图和折线图使用 categories + series；进度条、饼图和环形图使用 items。数值按非负数处理，无数据时输出稳定的空状态。

图片插入

const imageBlock: SimplePdfBlock = {
  type: 'image',
  imagePath: '/static/一页间.png',
  imageFit: 'contain',
  width: 220,
  height: 120,
  align: 'center'
}

图片和 Logo 支持应用资源、本地绝对路径、file://、unifile:// 以及 HTTP(S)/FTP 远程地址；远程地址会先下载到临时文件，再交给三端本地解码器处理。contain 保持原始宽高比并完整显示，fill 填满目标区域。推荐使用三端系统解码器稳定支持的 PNG 或 JPEG；路径不存在、文件损坏或格式不受支持时返回 PDF_IMAGE_INVALID。

iOS 使用 UIGraphicsPDFRenderer 直接绘制矢量文字和图形，不创建整页位图。Android 和 iOS 原生绘制图表；HarmonyOS 使用 PDFKit，并仅为单个图表区域生成临时 PNG。公共排版最多生成 80 页；超过限制时 createPdf 返回 PDF_PAGE_LIMIT_EXCEEDED，调用方应提示用户缩小数据范围。

批量插入图片（images）

options.images 以数组形式批量插入图片，数组项既可以是图片路径字符串，也可以是携带坐标、尺寸的对象：

const result = await createPdf({
  fileName: 'activity-photos.pdf',
  title: '活动照片',
  pageWidth: 595,
  pageHeight: 842,
  margin: 48,
  images: [
    '/static/photo-1.png',
    { imagePath: '/static/photo-2.png', caption: '书店外景' },
    { imagePath: 'https://example.com/stamp.png', x: 60, y: 60, width: 120, height: 120, page: 0 }
  ]
})

SimplePdfImage 字段语义：

• 数组项是字符串时按整页模式处理，每张图片独立一页并居中。
• 数组项是对象且同时指定 x、y 时按坐标定位到 page 页；目标页不存在时自动补空页。
• 数组项是对象但未同时指定 x、y 时同样按整页模式处理。
• 远程图片先下载到临时文件再交给三端本地解码器，与 block.type: 'image' 一致；图片无效返回 PDF_IMAGE_INVALID。

平台差异

simple-pdf 在三个目标平台复用同一套公共排版（common/builder）和远程资源归一化（common/remote），公开接口保持一致，但底层原生实现和个别能力存在差异：

• 错误码三端统一为 PDF_PAGE_LIMIT_EXCEEDED、PDF_IMAGE_INVALID、PDF_WRITE_FAILED；HarmonyOS 的 savePdf 额外返回 PDF_SAVE_CANCELLED、PDF_SAVE_FAILED。
• 图片建议使用三端系统解码器稳定支持的 PNG / JPEG，其余格式可能在某平台解码失败并返回 PDF_IMAGE_INVALID。
• 目标平台若包含 Android，请避免依赖加密 PDF 的预览能力。

保存与系统查看器

savePdf(options, callbacks) 生成 PDF 并保存：Android 与 iOS 直接生成到应用目录，将 path 通过回调返回；HarmonyOS 会额外弹出系统 DocumentViewPicker 让用户选择保存位置，并将最终 URI 通过 outputUri 返回。previewPdf(options) 仍然保留，但它只负责调用系统文件查看器，和页面内的 <simple-pdf-view> 是两套明确区分的能力。