用React写PDF：react-pdf让文档生成像搭组件

react-pdf是一个基于React的PDF渲染器，允许用组件化和声明式的方式在浏览器与Node端生成高质量PDF。它复刻Flexbox布局模型、提供PDFViewer在线预览与服务端导出能力，兼顾工程化与开发体验，适合报表、合同、发票等文档场景。

适用人群：熟悉React的前端与全栈开发者，需要生成结构化PDF的工程师；从事报表、合同、发票等文档模板化产出的产品与研发团队；希望在前后端统一文档渲染方案的技术决策者与架构师

适用场景：在Web应用中提供用户实时预览并下载的报表或凭证生成功能；在服务端批量产出合同、发票、账单等PDF；需要复用现有React组件与样式体系，实现与UI一致的文档渲染

推荐理由： react-pdf以组件化与Flexbox为核心，降低PDF排版复杂度；同时提供Web预览与服务端导出，提升开发与交付效率。开源社区活跃、TypeScript支持友好、上手成本可控，值得纳入文档生成技术选型。

项目定位与背景

react-pdf是一个用React创建PDF文件的渲染器，定位为面向前端与服务端的组件化PDF生成方案。项目采用TypeScript编写，GitHub Star数量超过1.6万，Fork超过1.3千，说明在React生态中具备较高认可度。它的出现解决了传统PDF生成中“命令式、模板化、难以工程化”的痛点，让熟悉React的开发者可以用熟悉的思维与工具来产出结构化文档。项目在浏览器与Node环境均可运行，覆盖了“在线预览”与“服务端批量导出”的典型诉求。

核心功能与技术架构

react-pdf的核心是将PDF文档抽象为React组件树。开发者通过Document、Page、View、Text等组件描述文档结构，并用StyleSheet定义样式。样式系统复刻了CSS的Flexbox布局模型，支持flexDirection、margin、padding、flexGrow等常见属性，使PDF排版更接近Web开发体验。渲染层面，项目作为React renderer，接管组件树到PDF指令的转换，在客户端可用PDFViewer组件嵌入DOM实现即时预览；在服务端通过render方法将组件树输出为文件，实现无头生成。这种“同一套声明式结构，两端渲染”的架构，便于复用模板与数据模型。

创新点与亮点

第一，组件化与声明式。把页面内容与布局用JSX描述，让PDF模板与应用代码一致可版本化、可测试，避免传统PDF库中“脚本式绘制”的可维护性问题。第二，Flexbox布局模型。在PDF中实现了接近Web的布局能力，让图文混排、多列、自适应伸缩更直观。第三，双端能力。Web端用PDFViewer即时查看，Node端可直接落地为文件，满足交互式与批处理的不同场景。第四，TypeScript支持。类型约束带来更稳健的开发体验，适合团队协作与模板抽象。第五，生态友好。与React生态无缝衔接，便于将现有组件与数据流接入PDF生成。

与同类项目对比

与PDFBox、iText等偏底层的Java库相比，react-pdf的学习曲线更平缓，工程化能力更强；与WeasyPrint、Puppeteer等基于HTML/CSS或页面截图的方案相比，它更贴近React的组件思维，无需维护单独的HTML模板，且布局更可控。pdfmake、jsPDF等前端PDF库也提供脚本化绘制，但在“组件化”和“Flexbox布局”上不如react-pdf自然。值得提醒的是，react-pdf专注于“用React生成PDF”，如果需要“在React中显示已有PDF”，应选择react-pdf（wojtekmaj/react-pdf）这一查看器项目，两者定位不同但互补。

上手指南或快速开始

安装方面，项目通过npm包@react-pdf/renderer分发。在项目中执行yarn add @react-pdf/renderer即可。基本使用是定义样式与文档组件，例如用StyleSheet创建页面与段落样式，然后在Document中组合Page、View、Text，形成结构化内容。Web端可用PDFViewer组件包裹MyDocument，在DOM中渲染一个可预览的PDF窗口；Node端则通过render方法把组件树输出为指定路径的PDF文件。示例代码展示了创建两种区块的页面布局，并应用Flexbox的flexGrow实现等宽分布。对于模板抽象，可以将组件与样式抽离为独立文件，配合数据注入，实现通用报表或票据生成器。

总结与展望

react-pdf把“PDF生成”从工具型API提升到“React组件渲染”的层次，带来更一致的工程实践与更好的可维护性。它的Flexbox样式模型与双端渲染能力，是其在前端与服务端都能落地的关键。优势在于组件化、开发体验、与React生态兼容性；局限在于PDF排版能力与CSS相比仍有边界，复杂图文混排或高精度印刷需求需要额外调优。整体而言，react-pdf是React团队生成PDF的优质选择，适合报表、合同、发票、教育资料等结构化文档场景。未来随着模板生态与渲染能力的完善，它在企业级文档自动化中具备更大潜力。