如何使用jsPDF正确实现HTML转PDF的元素尺寸匹配转换

核心问题成因 #

尺寸不匹配本质是三层单位/缩放逻辑没对齐，和页面本身写的样式没有直接关系：

• 单位换算差：jsPDF默认使用mm作为尺寸单位，浏览器DOM渲染用px，两者没有做锚定换算时，直接按DOM像素映射到PDF单位会出现固定比例的尺寸偏差
• 自动缩放误差：html模块默认会根据传入的内容宽高自动计算缩放比，如果没有手动锁定内容宽度，会因为边距、滚动条宽度、响应式样式触发意外缩放，连带字体、图片整体变形
• DPI不匹配：底层html2canvas默认渲染的画布DPI和PDF标准打印DPI（72DPI）不一致时，插入的图片会出现拉伸、模糊同时尺寸不对的问题

正确的相对尺寸配置方法 #

配置核心逻辑：所有尺寸锚定PDF实例的实际页面宽高做相对计算，不要硬编码固定像素值
可直接复用的基础配置模板：

// 初始化PDF时优先选pt作为单位，和DOM的px换算逻辑最简单，1pt对应1/72英寸
const doc = new jsPDF({
  unit: 'pt',
  format: 'a4',
  orientation: 'portrait'
})
// 动态获取当前PDF页面的实际可用内容尺寸，扣除预留边距
const [pageWidth, pageHeight] = [doc.internal.pageSize.getWidth(), doc.internal.pageSize.getHeight()]
const margin = 40
const usableContentWidth = pageWidth - margin * 2

doc.html(document.querySelector('#export-target'), {
  x: margin,
  y: margin,
  width: usableContentWidth, // 强制内容区宽度匹配PDF可用宽度，高度自动等比计算
  windowWidth: document.querySelector('#export-target').scrollWidth, // 锁定DOM渲染视口宽度，避免响应式样式改尺寸
  scale: 2, // 固定缩放系数，不要用默认自动计算值，2倍缩放兼顾清晰度和尺寸精度
  html2canvas: {
    scale: 2,
    useCORS: true, // 避免跨域图片加载失败触发默认尺寸占位
    letterRendering: true // 保证字体渲染尺寸和原DOM一致
  },
  callback: (generatedPdf) => {
    generatedPdf.save('export-file.pdf')
  }
})

需要重点掌握的配置参考要点 #

• 核心API：jsPDF实例的internal.pageSize对象提供的getWidth()、getHeight()方法，是所有相对尺寸计算的基准值，所有元素的定位、宽高设置都基于这个值换算，不要写死固定数值
• html模块参数联动逻辑：width参数控制DOM内容最终在PDF里占据的实际物理宽度，windowWidth参数控制html2canvas渲染DOM时模拟的浏览器视口宽度，两者的比值就是全局统一缩放比例，字体、图片、块级元素都会按这个比例等比缩放，不会出现错位
• 特殊元素适配：如果存在自定义字体、大图，要保证字体文件加载完成、图片全部load完成后再调用doc.html()方法，否则会因为元素未渲染完成触发默认尺寸 fallback

内容的提问来源于stack exchange，提问作者abduljalil