话说回来，

在现代 Web 应用中。合同、报告、发票等业务往往需要以 PDF 的形式导出。其实，者常遇到的痛点包括：分页不准确、文件名无法自定义、跨浏览器兼容性差、内存泄漏导致页面卡顿还有在前端渲染大内容时出现卡顿或崩溃。

前后端协作时的常见难点

最省事的方式是让后端直接生成 PDF 并返回一个可访问的 URL，前端只需下载即可。但这也带来以下痛点：

URL 直接下载

如果后端返回的是一个可访问的链接。前端有三种实现方式，但每种都有缺陷。

. 使用 window.open 或 location.href

这是最简单的方式。但无法控制下载后的文件名，且容易被浏览器拦截弹窗阻止下载。

const downloadByUrl = => {
window.open
}

. 使用

通过创建虚拟锚点并利用 download 属性。能更好地控制下载行为，并兼容大多数现代浏览器。

/**
* 通过 URL 下载文件
* @param url 文件地址
* @param fileName 自定义文件名
*/
export const downloadFileByUrl = => {
const link = document.createElement
link.href = url
// 如果提供了文件名。则设置 download 属性
if {
link.download = fileName
}
link.target = '_blank'
link.style.display = 'none'
document.body.appendChild
link.click
// 清理
document.body.removeChild
}

文件流下载

后端返回 Blob 时浏览器无法直接处理，需要先将其转换为临时 URL。若忘记释放该 URL，容易导致内存泄漏甚至页面崩溃。

/**
* 通过文件流下载文件
* @param data 文件流数据
* @param fileName 下载后的文件名
* @param mimeType 文件的 MIME 类型
*/
export const downloadFileByStream = => {
// . 优先获取数据的类型
const type = mimeType ||
// . 将数据封装为 Blob 对象
const blob = data instanceof Blob?data : new Blob
// . 创建一个临时的 URL 指向该 Blob 对象
const blobURL = window.URL.createObjectURL
// . 创建虚拟锚点触发下载
const link = document.createElement
link.href = blobURL
link.download = fileName
link.style.display = 'none'
document.body.appendChild
// . 下载执行后立即点击触发，随后释放资源避免泄漏
link.click
document.body.removeChild
window.URL.revokeObjectURL // 防止内存泄漏的关键步骤
}

纯前端生成 PDF 的挑战与方法

当业务需要完全由前端完成 PDF 渲染时常见痛点包括：打印弹窗影响使用者体验、复杂布局难以精准分页、CSS 与 JS 渲染不一致导致内容错位或被裁切。

windows.print

This method is easy but triggers a print preview dialog that cannot be bypassed. It also fails to handle custom page breaks or hidden elements.

const handlePrint = => {
window.print
}

. CSS 控制打印样式

使用 @media print 可以隐藏不需要打印的元素和强制分页。但手写这些规则往往繁琐且易出错，特别是对多列布局或嵌套表格。

@media print {
/* 隐藏不需要打印的元素，如导航栏、侧边栏、按钮 */
.no-print { display:none!important，}
/* 调整打印区域宽度与边距 */
.print-container { width:%;margin:，padding:;}
/* 强制分页 */
.page-break { page-break-after: always;}
}

+

This approach converts DOM into an image n embeds it into a PDF. The key advantages are:

• No print dialog: fully controlled by JavaScript.
• Avoids “腰斩”: automatically detects element boundaries and pushes truncated elements onto next page.
• CORS support: `useCORS:true` solves image loading issues.
• MIME & scaling: preserves visual fidelity across devices.

import html2canvas from 'html2canvas-pro' // 推荐使用 pro 无缝替代
import jsPDF from 'jspdf'
/**
* 将指定 DOM 导出为 PDF
* @param domId - ID of target element
* @param title - Exported file name prefix
*/
export const exportPdf = async :Promise{
const ele=document.getElementById;if{ throw new Error }
/* 防截断节点集合 */
const nodes=ele.querySelectorAll
/* 获取所有节点相对容器顶部和底部坐标 */
const containerRect=ele.getBoundingClientRect
const breakPointsPx=Array.from.map(node=>{
const rect=node.getBoundingClientRect
return {top:rect.top-containerRect.top,bottom:rect.bottom-containerRect.top}
})
/* Render canvas */
const canvas=await html2canvas,useCORS:true,backgroundColor:'#ffffff'})
/* Convert canvas to image */
const imgDataUrl=canvas.toDataURL
/* Initialize jsPDF */
const pdf=new jsPDF
const a4Width=pdf.internal.pageSize.getWidth
const a4Height=pdf.internal.pageSize.getHeight
/* Calculate scaling ratio */
const ratio=a4Width/canvas.width
/* Convert breakpoints from px to pt */
let breakPointsPt=breakPointsPx.map)
/* Page margins - adjust as needed */
let topMargin=30 // 页眉预留空间
let bottomMargin=30 // 页脚预留空间
let pageContentHeight=a4Height-topMargin-bottomMargin
let currentRenderY=0 // 已绘制内容高度
while{
let expectedPageBottom=currentRenderY+pageContentHeight
let actualPageBottom=expectedPageBottom
if{ actualPageBottom=imgHeight }else{
for{
let {top。bottom}=brkPointsPt
if{
actualPageBottom=top // 在被截断元素顶部切页
break
}
}
}
pdf.addImage
currentRenderY+=actualPageBottom-currentRenderY
if pdf.addPage
}
let fileName=}`:`${Date.now}`)+'.pdf'
pdf.save


}

CodeSandbox 案例演示

. 用法案例

import { exportPdf } from './utils/pdf'
const ReportPage=>=>{
async function handleDownload{
try{
await exportPdf
}catch{
console.error
}
}
return (


下载报告
 {/* 必须与 exportPdf 参数一致 */}


报表标题

长文本内容会自动换页...


{.map=>(
)}



)


}
export default ReportPage;

. 高级：PDF 模板架构设计

当项目中存在多种模板，可以使用“容器与显示分离”的架构。
这样可以保证模板 UI 独立、不受业务逻辑干扰。并能在后台静默渲染生成 PDF，从而避免页面闪烁和渲染卡顿。

. 建议目录结构


src/
├── components/
│ └── pdf-templates/
│ ├── Contract.tsx # 合同模板 UI
│ ├── Invoice.tsx # 发票模板 UI
│ └── index.ts # 批量导出所有模板组件


└── utils/
└── pdf.ts # exportPdf 主要实现


. 模板编写规范

// src/components/pdf-templates/ContractTemplate.tsx interface IProps{data:any}
export function ContractTemplate{
return(
{data.title}{/* ...其他细节 ...*/}

)}


. 数据获取与导出流程示例

// src/pages/OrderDetails.tsx import React,{useState} from 'react'
import {createPortal} from 'react-dom';import {exportPdf} from '../utils/pdf';import {ContractTemplate} from '../components/pdf-templates';

function OrderDetails{
const =useState;const =useState;

async function startExport{
setIsExporting;其实，try{
const res=await fetchOrderData;// 从 API 拉取最新订单信息
setData;// 等待 React 完成一次渲染周期后再执行导出，以确保 DOM 已更新完毕。await new Promise);await exportPdf;}catch{
console.error;}finally{
setIsExporting;}
}

return(



{/* 在屏幕外创建无感渲染区域 */}
{isExporting && data && createPortal(


document.body)}