JS图片转PDF实战：用jsPDF实现多图合并+自动分页（附完整代码）

前端批量图片转PDF实战：用jsPDF实现智能分页与自适应布局

最近在做一个内部文档管理系统，需要把用户上传的一批产品截图自动整理成可打印的PDF报告。最初尝试了几个现成的库，要么功能太简单只能单图转换，要么配置复杂得让人头疼。最后发现jsPDF这个库其实完全能满足需求，只是需要自己动手处理多图合并和分页逻辑。

如果你也在寻找一个轻量级的前端解决方案，能够将多张不同尺寸的图片智能地合并到一个PDF文件中，并且自动处理分页、图片自适应等细节问题，那么这篇文章正是为你准备的。我会分享一套经过实战检验的完整方案，包含核心代码实现和多个实用技巧。

1. 环境准备与jsPDF基础配置

在开始处理多图合并之前，我们需要先搭建好基础环境。jsPDF虽然功能强大，但它的文档对于新手来说可能有些分散，特别是处理图片相关的功能。

1.1 安装与引入方式

目前主要有三种方式使用jsPDF：

// 方式1：通过npm安装（推荐用于现代前端项目）
npm install jspdf

// 方式2：使用CDN直接引入
<script src="/https://cdnjs.cloudflare.com/ajax/libs/jspdf/2.5.1/jspdf.umd.min.js"></script>

// 方式3：下载本地文件引入
<script src="./dist/jspdf.umd.min.js"></script>

对于现代前端项目，我推荐使用npm安装，这样可以更好地管理依赖和版本。如果你只是想在简单的HTML页面中快速测试，CDN方式最为方便。

1.2 基础PDF创建与配置

创建一个基本的PDF文档非常简单，但有几个关键参数需要理解：

// 创建A4尺寸的PDF文档（默认纵向）
const doc = new jsPDF();

// 或者指定更多参数
const doc = new jsPDF({
  orientation: 'portrait',  // 方向：portrait（纵向）或 landscape（横向）
  unit: 'mm',               // 单位：mm（毫米）、pt（点）、cm（厘米）
  format: 'a4'              // 纸张格式：a4、letter等
});

// 自定义页面尺寸
const doc = new jsPDF({
  orientation: 'portrait',
  unit: 'mm',
  format: [210, 297]  // 宽210mm，高297mm（A4尺寸）
});

注意：jsPDF默认使用点（pt）作为单位，1pt = 1/72英寸。但在实际开发中，我建议使用毫米（mm）作为单位，这样更符合我们的日常认知，也更容易计算。

1.3 图片加载与处理基础

在开始多图处理之前，我们需要确保图片能够正确加载。这里有几个常见的图片源处理方式：

// 从URL加载图片
const imgUrl = 'https://example.com/image.jpg';

// 从File对象加载图片（用户上传）
function loadImageFromFile(file) {
  return new Promise((resolve, reject) => {
    const reader = new FileReader();
    reader.onload = (e) => {
      const img = new Image();
      img.onload = () => resolve(img);
      img.onerror = reject;
      img.src = e.target.result;
    };
    reader.readAsDataURL(file);
  });
}

// 从Base64字符串加载图片
function loadImageFromBase64(base64String) {
  return new Promise((resolve, reject) => {
    const img = new Image();
    img.onload = () => resolve(img);
    img.onerror = reject;
    img.src = base64String;
  });
}

在实际项目中，我通常会封装一个通用的图片加载函数，处理各种来源的图片，并统一返回Promise，这样代码会更加清晰。

2. 单图处理与自适应缩放策略

处理单张图片是理解多图合并的基础。这里的关键在于如何让不同尺寸的图片都能在PDF页面中合理显示。

2.1 图片尺寸计算与缩放逻辑

当图片尺寸超过页面大小时，我们需要进行缩放。这里有两种主要的缩放策略：

等比例缩放策略：

function calculateImageSize(img, pageWidth, pageHeight, padding = 10) {
  const availableWidth = pageWidth - padding * 2;
  const availableHeight = pageHeight - padding * 2;
  
  const widthRatio = availableWidth / img.width;
  const heightRatio = availableHeight / img.height;
  
  // 选择较小的缩放比例，确保图片完全在页面内
  const scaleRatio = Math.min(widthRatio, heightRatio);
  
  return {
    width: img.width * scaleRatio,
    height: img.height * scaleRatio,
    x: padding,
    y: padding
  };
}

固定宽度策略（适合文档类图片）：

function calculateFixedWidthSize(img, targetWidth, padding = 10) {
  const scaleRatio = targetWidth / img.width;
  const scaledHeight = img.height * scaleRatio;
  
  return {
    width: targetWidth,
    height: scaledHeight,
    x: padding,
    y: padding
  };
}

2.2 图片质量与格式优化

不同的图片格式和压缩设置会影响最终PDF的大小和质量：

在实际使用中，我通常这样配置图片质量：

// 高质量设置（适合打印）
doc.addImage(imgData, 'JPEG', x, y, width, height, 'FAST', 'NONE', 0);

// 参数说明：
// 1. imgData: 图片数据（DataURL、Image对象等）
// 2. 'JPEG': 图片格式
// 3. x, y: 图片在页面中的位置
// 4. width, height: 图片显示尺寸
// 5. 'FAST': 压缩质量（FAST、MEDIUM、SLOW）
// 6. 'NONE': 压缩类型
// 7. 0: 旋转角度

提示：对于需要打印的PDF，建议使用较高的图片质量（'SLOW'压缩）。虽然文件会大一些，但打印效果更