更新记录

1.0.0（2026-07-04） 下载此版本

初始版本

平台兼容性

uni-app(4.25)

uni-app x(4.25)

其他

xyz-pdf

将本地图片拼接生成 PDF 文件的 UTS 插件，支持 Android、iOS、HarmonyOS 三端。

功能

• 将多张本地图片（jpg/png）按序生成为多页 PDF
• 图片等比缩放居中适配页面（contain 模式）
• 可配置页面尺寸（默认 A4）和边距
• 支持多次 addImages 追加页面
• 生成的 PDF 保存到临时目录，返回文件路径

安装

将 uni_modules/xyz-pdf 目录复制到项目的 uni_modules 下即可。

基本用法

import { XyzPdfDocument } from "@/uni_modules/xyz-pdf"

// 1. 创建文档实例
const doc = new XyzPdfDocument({
  pageSize: { width: 595, height: 842 }, // A4，可选
  margin: 20 // 页面边距（pt），可选，默认 0
})

// 2. 添加图片页
doc.addImages({
  images: ['/path/to/img1.png', '/path/to/img2.jpg'],
  success: (res) => {
    console.log(res.errMsg) // 'addImages:ok'

    // 3. 保存 PDF
    doc.save({
      success: (saveRes) => {
        console.log('PDF 路径:', saveRes.tempFilePath)
        // 可通过 uni.openDocument 预览
        // 可通过 uni.getFileSystemManager() 保存到指定位置
      },
      fail: (err) => {
        console.error(err.errCode, err.errMsg)
      }
    })
  },
  fail: (err) => {
    console.error(err.errCode, err.errMsg)
  }
})

API

new XyzPdfDocument(options?)

创建 PDF 文档实例。

doc.addImages(options)

批量添加图片页，每张图片占一页，等比缩放居中。可多次调用追加页面。

doc.save(options)

保存 PDF 到临时文件。

图片要求

• 支持格式：jpg/jpeg、png
• 图片必须为本地路径（网络图片请先通过 uni.getImageInfo 下载到本地）
• 截图路径（takeSnapshot 返回的 tempFilePath）可直接使用
• 图片以等比缩放适配方式放置（保持宽高比，居中，可能留白）
• 如需 cover/fill 效果，请先裁剪图片到目标比例后传入

错误码

完整示例

import { XyzPdfDocument } from "@/uni_modules/xyz-pdf"

// 截图 + 选图 → 生成 PDF → 打开预览
const imagePaths: string[] = []

// 添加截图
const pages = getCurrentPages()
const currentPage = pages[pages.length - 1]
currentPage.takeSnapshot({
  success: (res) => {
    imagePaths.push(res.tempFilePath)
  }
})

// 添加相册图片
uni.chooseImage({
  count: 9,
  success: (res) => {
    imagePaths.push(...res.tempFilePaths)
  }
})

// 生成 PDF
const doc = new XyzPdfDocument({ margin: 20 })
doc.addImages({
  images: imagePaths,
  success: () => {
    doc.save({
      success: (res) => {
        // 打开预览
        uni.openDocument({
          filePath: res.tempFilePath,
          fileType: 'pdf'
        })
      }
    })
  }
})

注意事项

• 生成的文件存储在系统临时目录，如需持久保存请使用 uni.getFileSystemManager() 复制到指定路径
• 图片数量较多时可能占用较多内存，建议控制单次 addImages 的数量
• 页面尺寸单位为 pt（1pt = 1/72 inch），A4 = 595×842pt