# 使用 React-PDF 生成 PDF ## 何时使用 * 生成 PDF 文档（报告、发票、简历、表格、证书） * 创建需要复杂布局的 PDF（多列、网格、卡片） * 使用内联 SVG 图形、图表或图标构建 PDF * 使用自定义 Google 字体或表情符号生成文档 * 任何 Flexbox 布局比绝对坐标数学更容易的 PDF 任务 ## 何时不使用 * 从现有 PDF 中读取或提取文本 - 使用 `pdfplumber` 或 `pypdf` 代替 * 填写现有 PDF 表单 — 使用 Python `pypdf` 或 `pdftk` * 将 HTML 转换为 PDF — 使用 Playwright 或 WeasyPrint * 简单的一次性文本 PDF，无需布局 - Python 脚本可能更简单 ## 关键要求 1. **字体必须是本地文件** \- 远程字体 URL (http/https) 不起作用。使用字体之前，请务必将字体下载到本地文件。 2. **将异步代码包装在 IIFE** \- 顶级等待会导致错误。始终使用 `(async () => { ... })()` 模式。 3. **禁用自定义字体的连字符** \- 自定义字体缺少连字符字典，可能会错误地崩溃或断词。注册自定义字体后始终调用 `Font.registerHyphenationCallback((word) => [word]);`。 ## 文件 * `{baseDir}/skills/react-pdf/references/google-fonts.txt` \- 带有 TrueType URL 的约 65 种流行 Google 字体的元数据。每行都是制表符分隔格式的字体变体：`font name`、`style`、`category`、`weight`、`url`。 * `{baseDir}/skills/react-pdf/references/components.md` \- 完整的组件 API 参考和支持的 CSS 属性 * `{baseDir}/skills/react-pdf/assets/example-template.tsx` \- 演示固定页脚、页码和牢不可破的内容的最小工作示例。在开始理解基本模式之前请阅读本文。注意：此处并未显示所有 API - 请参阅文档和“{baseDir}/skills/react-pdf/references/components.md”以获取完整的 API。 ## 先决条件 npm 安装 React @react-pdf/renderer npm install -D tsx @types/react `tsx` 直接通过 Node 运行 TypeScript + JSX 文件，无需配置 - 不需要 `tsconfig.json`。它在底层使用 esbuild 并自动处理 JSX 转换。 ## 核心组件 * **文档** ：根组件（元数据、设置） * **页面** ：单个页面（A4、Letter 或自定义尺寸） * **View** ：容器组件（类似div） * **Text** ：文本内容，支持内联样式嵌套 * **图像** ：嵌入图像（JPG、PNG、base64） * **链接** ：可点击的超链接（外部或内部） * **注释** : 注释注释 * **Canvas** ：使用 pdfkit 方法进行自由绘图 * **Svg** ：矢量图形（圆形、矩形、路径、直线、多边形等） * **StyleSheet** ：创建可重用的样式有关完整的组件 props 和 CSS 属性，请参阅 [references/components.md]()。 ## 基本示例从“反应”导入反应；从“@react-pdf/renderer”导入{文档、页面、文本、视图、样式表、renderToFile}； const 样式 = StyleSheet.create({ 页面：{ flexDirection：“列”，背景颜色：“#ffffff”，填充：40 }，标题：{ fontSize：24，marginBottom：20，fontWeight：“粗体”}，文本：{ 字体大小：12，行高：1.5 }， }); const MyDocument = () => ( <文件> <页面大小=“A4”样式= {styles.page}> <视图样式={{边距：10，内边距：20}}> 文档标题此处为您的内容）；（异步（）=> { 等待 renderToFile(, "./output.pdf"); console.log("PDF 已保存！"); })(); ## 运行脚本 PDF生成脚本使用JSX，Node无法直接运行。使用 `tsx` 来执行它们： npx tsx my-document.tsx `npx tsx` 无需全局安装 tsx 即可工作 - 它按需下载。如果 tsx 作为开发依赖项安装（`npm install -D tsx`），它将立即运行，无需 npx 下载步骤。始终将渲染包装在异步 IIFE 中： // 好（异步（）=> { 等待 renderToFile(, "./output.pdf"); })(); // 不好 - 顶级等待可能会失败等待 renderToFile(, "./output.pdf"); ## 预览 PDF 要直观地检查生成的 PDF，请将页面转换为图像。首先尝试“pdftoppm”（通常是预安装的），如果不可用，则回退到 Python 的 PyMuPDF。 **选项 1：pdftoppm (poppler-utils)** — 首选，在许多环境中无需安装： pdftoppm -png -r 200 文档.pdf 预览 # → 预览-1.png、预览-2.png、... **选项 2：PyMuPDF (Python)** — 如果 pdftoppm 不可用，则后备： pip安装pymupdf 进口菲茨 doc = fitz.open("文档.pdf") 对于 i，枚举（doc）中的页面： pix = page.get_pixmap(dpi=200) pix.save(f"page-{i+1}.png") ## 渲染方法从“@react-pdf/renderer”导入{renderToFile，renderToBuffer}； // 到文件（异步（）=> { 等待 renderToFile(, "./document.pdf"); })(); // 缓冲（异步（）=> { const buffer =等待renderToBuffer(); })(); ## 造型三种方法：`StyleSheet.create()`、内联对象或混合数组。 const styles = StyleSheet.create({ 容器: { padding: 20 } }); <视图样式={styles.container} /> <视图样式={{ 填充: 20 }} /> ### 支持的单位 `pt`（默认，72 DPI）、`in`、`mm`、`cm`、`%`、`vw`、`vh` ### 常用样式属性 { // 弹性盒 flexDirection：“行”， justifyContent：“空间之间”，alignItems：“中心”， flexWrap：“包裹”，间隙：10， // 盒子模型边距：10，填充：20，宽度：“100%”，高度：200， // 边框 borderWidth: 1, borderColor: "#333", borderRadius: 5, borderStyle: "solid", // 颜色背景颜色：“#f0f0f0”，颜色：“#000”，不透明度：0.8， // 版式 fontSize：12，fontWeight：“粗体”，fontFamily：“Helvetica”，fontStyle：“斜体”， lineHeight：1.5，textAlign：“居中”，textDecoration：“下划线”， textTransform: "大写", letterSpacing: 1, // 位置位置：“绝对”，顶部：0，左侧：0，右侧：0，底部：0，zIndex：10， // 变换变换：“旋转（45度）”，变换原点：“中心”， } ## 图片本地文件最可靠。由于网络/CORS 问题，远程 URL 可能会失败。从'@react-pdf/renderer'导入{图像}；

**SVG 文件不能用作图像源。** 读取 SVG 源并使用react-pdf Svg 组件重新创建。 ## SVG 图形从“@react-pdf/renderer”导入{Svg、Circle、Rect、Path、Line、G、Defs、LinearGradient、Stop}； <定义> <停止偏移=“0%”stopColor=“#3498db”/> <停止偏移=“100%”stopColor=“#9b59b6”/> <圆 cx="100" cy="100" r="50" fill="url(#grad1)" /> <矩形x =“10”y =“10”宽度=“50”高度=“50”填充=“#e74c3c”/> <路径d =“M10,50 Q50,10 90,50”笔画=“#2ecc71”笔画宽度=“2”填充=“无”/> ； ## 使用图标从图标库中读取 SVG 源并转换为react-pdf Svg 组件： npm 安装 lucide-static 从“@react-pdf/renderer”导入{Svg，Path，Rect}； // 从 lucide-static/icons/mail.svg 转换而来 const MailIcon = ({ 大小 = 12, 颜色 = "#888" }) => ( ）； ## 链接和导航访问网站目标跳转到第 1 部分 ## 动态内容和页码 `第 ${pageNumber} 页，共 ${totalPages}`} /> ## 固定页眉/页脚 <页面大小=“A4”> <视图固定样式={{位置：“绝对”，顶部：20，左侧：30，右侧：30}}> <文本>标题 <视图样式={{ marginTop: 60, marginBottom: 60 }}> <文本>内容 <文本固定的样式={{位置：“绝对”，底部：20，左：30，右：30，textAlign：“中心”}} render={({ pageNumber, totalPages }) => `第 ${pageNumber} 页，共 ${totalPages}`} /> ## 分页和换行 // 强制分页保持在一起 // 防止内部破裂长文本... // 孤儿/寡妇控制 Content // 中断前的最小间距 ## 自定义字体 **关键：所有字体源必须是本地文件路径。** 远程 URL 不起作用。从“@react-pdf/renderer”导入{字体}；字体.注册({ 家庭：“机器人”，字体：[ { src: "./fonts/Roboto-Regular.ttf", fontWeight: "正常" }, { src: "./fonts/Roboto-Bold.ttf", fontWeight: "粗体" }, { src: "./fonts/Roboto-Italic.ttf", fontStyle: "斜体" }, ], }); // 使用自定义字体时始终禁用连字符 Font.registerHyphenationCallback((word) => [word]); **内置字体**：Courier、Helvetica、Times-Roman（每种字体都有粗体、斜体/斜体变体） **字体粗细值**：细 (100)、超细 (200)、细 (300)、正常 (400)、中 (500)、半粗体 (600)、粗体 (700)、超粗体 (800)、粗体 (900) ## 谷歌字体使用 `{baseDir}/skills/react-pdf/references/google-fonts.txt` 查找字体 URL，然后下载到本地： # 找到字体URL grep“^Roboto”{baseDir}/skills/react-pdf/references/google-fonts.txt | grep“700”| grep “正常” # 下载 mkdir -p 字体 curl -sL "" -o fonts/Roboto-Bold.ttf # 验证 - 必须显示“TrueType 字体数据” 文件字体/Roboto-Bold.ttf 如果“file”显示“HTML 文档”或“ASCII 文本”，则下载失败。尝试使用不同的 URL 或在 GitHub 中搜索带有 TTF 文件的字体官方存储库。 ## 表情符号除非您注册表情符号源，否则表情符号不会在 PDF 中呈现。安装“twemoji-emojis”以获取本地 Twemoji PNG 资源 - 渲染时无需互联网。 npm 安装 twemoji-emojis 从“@react-pdf/renderer”导入{字体}；字体.registerEmojiSource({ 格式：“png”， url: "node_modules/twemoji-emojis/vendor/72x72/", }); 然后直接在Text中使用emoji：`Hello` ## 其他功能 // 画布绘图 <画布样式={{宽度：200，高度：200}} 油漆={(画家, w, h) => { 画家.circle(w/2, h/2, 50).fill("#3498db"); }} /> // 注释注释注释文字 // 连字符 Font.registerHyphenationCallback((word) => [word]); // 禁用 // 调试模式 - 可视化边界 <查看调试><文本调试>调试文本 // 文档元数据 <文档标题=“我的文档”作者=“作者”主题=“报告”语言=“en-US”pdfVersion=“1.5”/> ## 最佳实践 1. 使用 `StyleSheet.create()` — 定义一次样式并重复使用 2.嵌入前压缩图像，对远程图像使用`cache={true}` 3. 测试分页符——内容的流动可能与预期不同 4. 更喜欢 Flexbox 而不是绝对定位 5. 对每个页面的页眉/页脚使用 `fixed` 属性 6. 使用 `debug={true}` 可视化元素边界 7. 将渲染包装在 try-catch 块中 ## 常见问题 **文本溢出** : `...` **缺少字体**：本地下载并注册到本地文件路径。远程 URL 将不起作用。 **意外分页** ：使用 `wrap={false}` 将内容保持在一起，或使用 `` 强制分页。

反应.pdf

包含技能