前端 PDF 导出：从文件流下载到自动分页

‍ 写在开头点赞 收藏 学会在工作中我们经常会遇到需要生成 PDF 的业务比如合同、报告等。前后端合作对于前端来说最省事的就是后端生成 PDF 文件前端根据返回的 URL 地址进行下载。URL 下载如果后端直接返回一个可访问的 URL 地址我们可以通过以下几种方式进行下载1. 使用 window.open 或 location.href这是最简单的方式但缺点是无法控制下载后的文件名且受浏览器拦截政策影响。const downloadByUrl (url: string) { window.open(url, _blank) }2. 使用 a标签推荐通过创建虚拟锚点并利用 download 属性可以更好地控制下载行为。/** * 通过 URL 下载文件 * param url 文件地址 * param fileName 自定义文件名 */ export const downloadFileByUrl (url: string, fileName?: string) { const link document.createElement(a) link.href url // 如果提供了文件名则设置 download 属性 if (fileName) { link.download fileName } link.target _blank link.style.display none document.body.appendChild(link) link.click() // 清理 document.body.removeChild(link) }文件流下载如果后端返回的是文件流Blob由于浏览器无法直接解析这种数据格式作为下载源我们需要通过 URL.createObjectURL 将其转换为一个临时的 blob:URL然后利用 标签触发下载。/** * 通过文件流下载文件 * param data 文件流数据 (Blob | ArrayBuffer | string) * param fileName 下载后的文件名 * param mimeType 文件的 MIME 类型 (可选如果不传则尝试从 data 中获取或使用默认值) */ export const downloadFileByStream (data: any, fileName: string, mimeType?: string) { // 1. 优先获取数据的类型 const type mimeType || (data instanceof Blob ? data.type : application/octet-stream) // 2. 将数据封装为 Blob 对象 const blob data instanceof Blob ? data : new Blob([data], { type }) // 3. 创建一个临时的 URL 指向该 Blob 对象 const blobURL window.URL.createObjectURL(blob) // 4. 创建虚拟锚点触发下载 const link document.createElement(a) link.href blobURL link.download fileName link.style.display none document.body.appendChild(link) link.click() // 5. 下载执行后释放 URL 对象和 DOM 节点 document.body.removeChild(link) // 不释放可能导致内存泄露过早释放可能会导致下载失败可以延迟触发 window.URL.revokeObjectURL(blobURL) }前端生成 PDF在有些业务上需要纯前端生成 PDF。window.print() 方法这是调用浏览器原生打印功能最简单的方法。它会将当前页面的内容渲染到打印预览窗口中用户可以选择保存为 PDF。其实并不推荐因为在很多复杂的结构中需要做很多工作才能达到理想的效果。并且会有打印预览弹窗无法实现无感打印。const handlePrint () { window.print() }CSS 控制为了让打印出来的效果更好我们通常需要使用 media print 查询来控制打印时的样式。media print { /* 隐藏不需要打印的元素如导航栏、侧边栏、按钮 */ .no-print { display: none !important; } /* 调整打印区域的宽度 */ .print-container { width: 100%; margin: 0; padding: 0; } /* 强制分页 */ .page-break { page-break-after: always; } }html2canvas-pro jsPDFhtml2canvas 可以将网页内容转换为图片然后 jsPDF 可以将图片转换为 PDF。html2canvas-pro 是 html2canvas 的加强版分叉完全兼容原版 API。它可以作为无缝替代品直接安装并导入只需将 import html2canvas from ‘html2canvas’ 改为 import html2canvas from ‘html2canvas-pro’。它修复了原版在处理现代 CSS如 object-fit、clip-path时的许多渲染 Bug。下面是通用的代码可用于 95% 的场景该方法会自动分页且不会切断元素。import html2canvas from html2canvas-pro // 推荐使用 pro 版本无缝替代 import jsPDF from jspdf /** * 将指定 DOM 导出为 PDF * param domId 目标 DOM 元素的 ID * param title 导出的文件名 */ export const exportPdf async (domId: string, title?: string): Promisevoid { const ele document.getElementById(domId) if (!ele) throw new Error(未找到目标元素) const scale window.devicePixelRatio 1 ? window.devicePixelRatio : 2 // 获取所有防截断元素防止元素被分页切开如表格行、标题、段落等 const nodes ele.querySelectorAll(tr, h2, h3, h4, h5, p, img) const containerRect ele.getBoundingClientRect() // 同时收集元素的 top 和 bottom 坐标 const breakPointsPx Array.from(nodes).map((node) { const rect node.getBoundingClientRect() return { top: rect.top - containerRect.top, bottom: rect.bottom - containerRect.top, } }) // 生成画布 const canvas await html2canvas(ele, { scale, useCORS: true, // 允许图片跨域 backgroundColor: #ffffff, }) const imgDataUrl canvas.toDataURL(image/jpeg, 1.0) // 初始化 PDF 对象p-竖向pt-点(单位)a4-纸张规格 const pdf new jsPDF(p, pt, a4) const a4Width pdf.internal.pageSize.getWidth() const a4Height pdf.internal.pageSize.getHeight() // 计算图片缩放比例根据宽度适配 A4 const ratio a4Width / canvas.width const imgWidth a4Width const imgHeight canvas.height * ratio // 将坐标单位从 px 转换为 pt (符合 PDF 内部计算) const breakPointsPt breakPointsPx.map((bp) ({ top: bp.top * ratio, bottom: bp.bottom * ratio, })) const topMargin 30 // 页眉预留 const bottomMargin 30 // 页脚预留 const pageContentHeight a4Height - topMargin - bottomMargin let currentRenderY 0 // 已完成渲染的 Y 轴偏移 while (currentRenderY imgHeight) { let expectedPageBottom currentRenderY pageContentHeight let actualPageBottom expectedPageBottom // 判断是不是最后一页 if (expectedPageBottom imgHeight) { actualPageBottom imgHeight } else { // 只有不是最后一页才去遍历判断是否被截断 for (let i 0; i breakPointsPt.length; i) { const { top, bottom } breakPointsPt[i] // 核心判断元素的头在当前页但尾巴超出了当前页的底部说明被“腰斩”了 if (top currentRenderY top expectedPageBottom bottom expectedPageBottom) { actualPageBottom top // 在被截断元素的顶部切一刀将其整体推到下一页 break } } } if (actualPageBottom currentRenderY) actualPageBottom expectedPageBottom // 1. 渲染当前页图像利用负偏移显示指定区域 pdf.addImage(imgDataUrl, JPEG, 0, topMargin - currentRenderY, imgWidth, imgHeight) // 2. 顶部遮罩覆盖负偏移区域产生的重叠部分 if (currentRenderY 0) { pdf.setFillColor(255, 255, 255) pdf.rect(0, 0, a4Width, topMargin, F) } // 3. 底部遮罩留白并遮挡截断处的残影 const currentRenderBottomY topMargin (actualPageBottom - currentRenderY) pdf.setFillColor(255, 255, 255) pdf.rect(0, currentRenderBottomY, a4Width, a4Height - currentRenderBottomY, F) currentRenderY actualPageBottom // 如果还没画完添加新的一页 if (currentRenderY 5 imgHeight) { pdf.addPage() } } const fileName title ? ${title}_${Date.now()} : Date.now().toString() pdf.save(${fileName}.pdf) }用法案例在 React 中使用该方案import { exportPdf } from ./utils/pdf const ReportPage () { const handleDownload async () { try { // 传入容器 ID 和文件名 await exportPdf(pdf-content, 月度分析报告) } catch (error) { console.error(生成 PDF 失败:, error) } } return ( div button onClick{handleDownload}下载报告/button {/* 这里的 ID 必须与 exportPdf 传入的一致 */} div idpdf-content style{{ padding: 20px, background: #fff }} h2报表标题/h2 p这里是很长很长的内容可能会跨页.../p table tbody tr td数据行 1/td /tr {/* 这里的 tr 会被防截断逻辑自动推送到下一页容器中 */} tr td数据行 2/td /tr /tbody /table /div /div ) }进阶PDF 模板架构设计当项目中需要管理多个 PDF 模板时建议采用“容器与显示分离”的架构这样可以保证模板的纯净度只负责 UI同时方便在后台静默生成 PDF。1. 目录结构建议src/ ├── components/ │ └── pdf-templates/ # 所有的 PDF UI 模板 │ ├── Contract.tsx # 合同模板 │ ├── Invoice.tsx # 发票模板 │ └── index.ts # 统一导出 └── utils/ └── pdf.ts # 核心 exportPdf 方法2. 模板编写建议模板组件应该只接收 data Props不处理任何业务逻辑。// src/components/pdf-templates/ContractTemplate.tsx interface IProps { data: any } export const ContractTemplate ({ data }: IProps) ( div idpdf-render-target style{{ width: 800px, padding: 40px }} h1{data.title}/h1 {/* 自由编写复杂的 PDF 样式 */} /div )3. 数据获取与导出架构推荐在需要导出 PDF 的页面中通过一个隐藏的“渲染容器”来实现。这样可以在不影响主页面 UI 的情况下获取最新的业务数据并生成 PDF。// src/pages/OrderDetails.tsx import { useState } from react import { createPortal } from react-dom import { exportPdf } from ../utils/pdf import { ContractTemplate } from ../components/pdf-templates const OrderDetails () { const [isExporting, setIsExporting] useState(false) const [data, setData] useState(null) const startExport async () { setIsExporting(true) // 1. 获取业务数据 (如从 API 获取) const res await fetchOrderData() setData(res) // 2. 等待 React 渲染 DOM (利用 setTimeout 确保渲染完成) setTimeout(async () { try { await exportPdf(pdf-render-target, 业务合同) } finally { setIsExporting(false) } }, 100) } return ( div button onClick{startExport} disabled{isExporting} {isExporting ? 正在生成... : 下载 PDF} /button {/* 通过 Portal 将模板渲染在屏幕外实现“无感”生成 */} {isExporting data createPortal( div style{{ position: absolute, left: -9999px, top: 0 }} ContractTemplate data{data} / /div, document.body )} /div ) }4. 架构优势关注点分离页面只管触发模板只管绘制utils 只管转换。数据解耦PDF 模板的数据可以由父页面统一注入也可以在 exportPdf 调用前按需加载。用户无感通过 createPortal 将渲染目标移出可视区域用户在页面上感知不到“截图”的过程。如果对您有所帮助欢迎您点个关注我会定时更新技术文档大家一起讨论学习一起进步。