React-PDF完全指南：使用React创建跨平台PDF文件的终极方案

你还在为生成PDF文件烦恼吗？使用React-PDF，只需React知识就能快速创建专业PDF文档。本文将带你从安装到高级应用，掌握在浏览器和服务器端生成PDF的全部技巧，让你轻松应对报告、发票、简历等各类PDF生成需求。

快速开始：5分钟上手React-PDF

React-PDF是一个基于React的PDF生成库，它允许你使用熟悉的JSX语法创建PDF文档。无论是在浏览器中直接预览，还是在服务器端生成并保存文件，React-PDF都能提供一致的开发体验。

安装步骤

使用yarn或npm安装核心包：

yarn add @react-pdf/renderer

第一个PDF文档

创建一个简单的PDF文档只需三步：

import React from 'react';
import { Document, Page, Text, View, StyleSheet } from '@react-pdf/renderer';

// 创建样式
const styles = StyleSheet.create({
  page: {
    flexDirection: 'row',
    backgroundColor: '#E4E4E4',
  },
  section: {
    margin: 10,
    padding: 10,
    flexGrow: 1,
  },
});

// 创建文档组件
const MyDocument = () => (
  <Document>
    <Page size="A4" style={styles.page}>
      <View style={styles.section}>
        <Text>Hello, React-PDF!</Text>
      </View>
    </Page>
  </Document>
);

核心组件解析

React-PDF提供了一套完整的组件系统，让你可以像构建网页一样构建PDF文档。

基础组件

• Document：PDF文档的根组件，包含一个或多个Page组件
• Page：表示PDF的一页，可设置尺寸、方向等属性
• View：类似于HTML的div，用于布局和分组
• Text：用于显示文本内容，支持样式和格式化

这些组件的源代码定义在packages/renderer/src/index.js中，你可以查看完整的实现细节。

组件层次结构

graph TD
    A[Document] --> B[Page]
    B --> C[View]
    C --> D[Text]
    C --> E[Image]
    B --> F[View]
    F --> G[Text]

这个层次结构允许你创建复杂的文档布局，就像使用React构建网页一样。

渲染PDF文档

React-PDF支持在浏览器中预览和在服务器端生成两种模式。

在浏览器中预览

使用PDFViewer组件可以在网页中直接预览PDF：

import ReactDOM from 'react-dom';
import { PDFViewer } from '@react-pdf/renderer';

const App = () => (
  <PDFViewer>
    <MyDocument />
  </PDFViewer>
);

ReactDOM.render(<App />, document.getElementById('root'));

在服务器端生成

在Node.js环境中，你可以将PDF保存为文件：

import ReactPDF from '@react-pdf/renderer';

ReactPDF.render(<MyDocument />, `${__dirname}/example.pdf`);

样式与布局

React-PDF提供了强大的样式系统，支持大多数CSS属性。

使用StyleSheet

StyleSheet.create方法可以创建可重用的样式：

import { StyleSheet } from '@react-pdf/renderer';

const styles = StyleSheet.create({
  title: {
    fontSize: 24,
    fontWeight: 'bold',
    marginBottom: 16,
  },
  paragraph: {
    fontSize: 12,
    lineHeight: 1.5,
  },
});

详细的样式支持可以参考packages/stylesheet/README.md。

支持的单位

React-PDF支持多种长度单位：

• 像素(px)
• 点(pt)
• 英寸(in)
• 厘米(cm)
• 毫米(mm)

响应式布局

使用media queries可以创建响应式PDF：

const styles = StyleSheet.create({
  container: {
    flexDirection: 'column',
    '@media orientation: landscape': {
      flexDirection: 'row',
    },
  },
});

高级功能

图片处理

React-PDF支持添加图片到PDF文档中：

import { Image } from '@react-pdf/renderer';

const MyDocument = () => (
  <Document>
    <Page>
      <Image src="/path/to/image.jpg" style={{ width: 200, height: 200 }} />
    </Page>
  </Document>
);

图片处理的核心逻辑在packages/image/src/index.ts中实现。

自定义字体

React-PDF允许你注册和使用自定义字体：

import { Font } from '@react-pdf/renderer';

Font.register({
  family: 'Roboto',
  src: '/path/to/roboto.ttf',
});

const styles = StyleSheet.create({
  text: {
    fontFamily: 'Roboto',
  },
});

系统默认字体的注册可以在packages/font/src/index.ts中查看。

分页控制

你可以控制内容在页面间的分布：

import { Page, Text, View, StyleSheet } from '@react-pdf/renderer';

const styles = StyleSheet.create({
  page: {
    flexDirection: 'column',
  },
  section: {
    margin: 10,
    padding: 10,
    flexGrow: 1,
  },
});

const LongDocument = () => (
  <Document>
    <Page size="A4" style={styles.page}>
      <View style={styles.section}>
        {/* 长文本内容 */}
      </View>
    </Page>
  </Document>
);

实际应用案例

生成简历PDF

使用React-PDF可以轻松创建格式化的简历：

const Resume = () => (
  <Document>
    <Page>
      <View style={styles.header}>
        <Text style={styles.name}>John Doe</Text>
        <Text style={styles.title}>Frontend Developer</Text>
      </View>
      
      <View style={styles.section}>
        <Text style={styles.sectionTitle}>Experience</Text>
        {/* 工作经历内容 */}
      </View>
      
      <View style={styles.section}>
        <Text style={styles.sectionTitle}>Education</Text>
        {/* 教育背景内容 */}
      </View>
    </Page>
  </Document>
);

生成报表

React-PDF非常适合生成数据报表：

const Report = ({ data }) => (
  <Document>
    <Page>
      <Text style={styles.title}>Monthly Report</Text>
      <View style={styles.table}>
        {/* 报表数据内容 */}
      </View>
    </Page>
  </Document>
);

常见问题解决

性能优化

对于大型文档，考虑使用以下优化技巧：

• 分页加载内容
• 减少不必要的嵌套
• 使用适当的缓存策略

样式不生效

如果遇到样式不生效的问题，可以：

1. 检查样式是否正确应用
2. 确认使用的是React-PDF支持的CSS属性
3. 查看控制台是否有错误信息

中文字体支持

要确保中文字体正常显示，需要：

1. 注册中文字体
2. 在样式中显式指定字体族

总结与展望

React-PDF为React开发者提供了一种直观、灵活的PDF生成方案。通过本文介绍的内容，你已经掌握了从基础到高级的使用技巧。

随着React生态系统的不断发展，React-PDF也在持续改进。未来我们可以期待更多高级功能，如表单支持、PDF加密等。

现在就开始使用React-PDF，将你的React应用扩展到PDF生成领域吧！

pie
    title React-PDF应用场景分布
    "报表生成" : 35
    "发票/收据" : 25
    "简历/文档" : 20
    "其他" : 20