Создание PDF из React‑компонентов

Человек, подписывающий юридический документ

О чём эта статья

В этой статье вы найдёте практический гайд по установке и использованию react-pdf, примеры кода, рекомендации по стилям и макетам, советы о возможных ограничениях и альтернативы. В конце — чеклисты для разработчика и дизайнера, критерии приёмки и краткий справочник терминов.

Что такое react-pdf?

React-pdf — библиотека, позволяющая создавать PDF‑документы из React‑компонентов. Она предоставляет набор компонентов (Document, Page, Text, View, Image, Link и другие) и виртуальный рендерер, который конвертирует дерево компонентов в PDF. Краткое определение: react-pdf — это React‑ориентированный API для формирования PDF, похожий на создание интерфейса в React, но выводящий результат в файл формата PDF.

Быстрый старт — установка

Установите библиотеку в папке проекта:

npm install @react-pdf/renderer --save

Или с yarn:

yarn add @react-pdf/renderer

Важно: используйте совместимую версию React и Node.js, если вы генерируете PDF на сервере (Node). На клиенте react-pdf рендерит превью в iframe-подобном компоненте PDFViewer.

Пример: создание простого PDF-документа

Ниже — минимальный компонент документа. Document создаёт контейнер документа, Page — страницу, Text — кусок текста.

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

const MyDocument = () => (
  
    
      Hello There
    
  
);

export default MyDocument;

Рендер документа в приложении (превью)

Для просмотра в браузере используйте PDFViewer, обернув в него ваш компонент документа:

import React from 'react';
import { PDFViewer } from '@react-pdf/renderer';
import MyDocument from './MyDocument';

function App() {
  return (
    
      
    
  );
}

export default App;

При рендере вы увидите превью. Пример превью на изображении ниже.

Просмотр PDF‑документа с текстом «Hello There»

Стилизация: использование StyleSheet

react-pdf поддерживает объектный подход к стилям, похожий на React Native. Создавайте стили через StyleSheet.create и передавайте через prop style.

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

const styles = StyleSheet.create({
  page: {
    textAlign: 'center',
    marginTop: 30,
    fontSize: 30,
  },
  text: {
    color: '#228b22',
  }
});

const MyDocument = () => (
  
    
      Hello There
    
  
);

export default MyDocument;

Коротко о стилях: поддерживаются flex‑box свойства, margin/padding, fontSize, color и прочие базовые свойства. Не всё CSS из браузера доступно — см. раздел «Ограничения».

Макеты: контейнер View

View — контейнерный компонент (аналог div). С его помощью выстраивают строки и столбцы с помощью flexDirection, alignItems, justifyContent и т.п.

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

const styles = StyleSheet.create({
  page: {
    marginTop: 30,
    fontSize: 30,
    padding: 20,
  },
  layout: {
    marginTop: 30,
    flexDirection: 'row',
    justifyContent: 'space-between'
  }
});

const MyDocument = () => (
  
    
      
        
          Hello There
        
        
          Welcome!!!
        
      
    
  
);

export default MyDocument;

Работа с изображениями

Компонент Image отображает изображения в PDF. Поддерживаются форматы JPEG, PNG и SVG (ограниченно). Передавайте источник через src и размеры через стиль.

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

const styles = StyleSheet.create({
  page: {
    padding: 20,
    alignItems: 'center',
  },
  image: {
    width: 300,
    height: 200,
  }
});

const MyDocument = () => (
  
    
      
        
      
    
  
);

export default MyDocument;

Примечание по размерам: в стилях числа обычно интерпретируются как точки/пиксели контекста PDF. В тексте статьи часто используют px, но в коде оставляйте числа.

Ссылки внутри PDF

Компонент Link создаёт кликабельные ссылки, ведущие на внешний URL.

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

const styles = StyleSheet.create({
  page: {
    padding: 20,
    alignItems: 'center',
  },
  link: {
    color: '#333333',
    textDecoration: 'none'
  }
});

const MyDocument = () => (
  
    
      
        Click Me
      
    
  
);

export default MyDocument;

Когда react-pdf работает хорошо и когда нет (ограничения)

Важно: знать ограничения, чтобы не тратить время на невозможные вещи.

Подходит для: генерации печатных или сохраняемых отчётов, счетов, бланков, экспортов карточек/сертификатов, серверной генерации PDF по шаблонам.
Может не подойти для: полного воссоздания сложной интерактивной веб‑страницы с позиционированием через CSS Grid, анимациями или динамическими скриптами. react-pdf не поддерживает весь CSS и не выполняет JavaScript внутри PDF.
Шрифты: требуется явно подключать кастомные шрифты (регистрация шрифтов через Font.register). Если используете системные шрифты, убедитесь, что среда их видит (особенно на сервере).
SVG: поддержка есть, но сложные SVG с фильтрами/скриптами могут не отобразиться корректно.

Альтернативные подходы

html2pdf / jsPDF / Puppeteer: если у вас готовая HTML‑страница, Puppeteer (или headless Chrome) делает высококачественную печать в PDF, сохраняя CSS более полно. Подходит, если вы хотите рендерить стандартный HTML+CSS.
Server-side libraries (wkhtmltopdf, PrinceXML): для задач с серверной генерацией и строгой типографикой.
Шаблонизаторы + библиотеки для PDF (PDFKit): для программной генерации без React.

Выбор зависит от: необходимости точного визуального соответствия (в пользу Puppeteer), гибкости шаблонов (в пользу React/templating) и производительности/стоимости (в пользу серверных инструментов).

Ментальные модели и лучшие практики

Представляйте PDF как статическое дерево компонентов без DOM‑манипуляций и событий. Планируйте макет заранее.
Разделяйте логику данных и шаблон: компонент документа должен принимать готовые данные и не выполнять эффекты рендера.
Подготовьте набор типографических токенов (шрифты, размеры, отступы) для консистентности.
Тестируйте на примерах с длинным текстом и переносами, чтобы выявить проблемы с переносом слов и разрывом страниц.

Мини‑методология: шаги для внедрения react-pdf в проект

Оцените требования (кто будет генерировать PDF — клиент или сервер, нужен ли офлайн).
Установите @react-pdf/renderer и проверьте совместимость версий.
Зарегистрируйте шрифты (Font.register), если требуются кастомные шрифты.
Создайте базовый Document/Page/Text/View набор компонентов.
Реализуйте стили и компонент для печати/скачивания.
Протестируйте на длинных данных, нескольких страницах и с изображениями.
Автоматизируйте тесты и добавьте критерии приёмки.

Чек-листы по ролям

Разработчик:

Установил пакет и запустил пример.
Зарегистрировал шрифты и проверил их доступность в среде.
Обработал кейсы перелома страниц (page-breaks через style).
Настроил экспорт в файл/скачивание при необходимости.

Дизайнер/Верстальщик:

Подготовил сетку/макет в пикселях или точках.
Предоставил файлы шрифтов и размеры заголовков/отступов.
Протестировал отображение изображений и их соотношение сторон.

Критерии приёмки

PDF соответствует макету (шрифты, цвета, отступы).
Все ссылки корректно работают.
Изображения не искажены и имеют требуемое разрешение.
Тесты на длинный контент показывают корректный перенос и разбиение на страницы.
Размер генерируемого файла в разумных пределах (без избыточной встраивки больших картинок).

Тестовые сценарии / приемочные тесты

Генерация простого документа с одним заголовком и параграфом.
Документ с несколькими страницами: текст должен переноситься автоматически.
PDF с изображениями разного формата (JPEG/PNG/SVG).
Ссылки ведут на внешние URL и открываются в браузере.
Экспорт на сервере: проверить, что шрифты загружаются и PDF корректен без доступа к браузерным ресурсам.

Совместимость и советы по миграции

Если раньше вы генерировали PDF из HTML с Puppeteer и хотите перейти на react-pdf, оцените потери в стилизации: сложный CSS может не мигрировать напрямую.
Для серверной генерации убедитесь, что все шрифты доступны в окружении (файлы на сервере или CDN с загрузкой).
Для больших объёмов генерируемых PDF продумайте очереди задач (например, через очереди сообщений), чтобы избежать блокировки потоков.

Безопасность и приватность

Если вы генерируете документы с конфиденциальными данными, избегайте передачи этих данных в сторонние сервисы.
На сервере храните PDF только по необходимости и с правильными разрешениями.
При встраивании изображений по внешним URL учитывайте риски утечки реферера и возможных ошибок загрузки.

Краткая справочная таблица (факт‑бокс)

Основные компоненты: Document, Page, View, Text, Image, Link, StyleSheet, PDFViewer.
Поддержка форматов изображений: JPEG, PNG, частично SVG.
Поддерживаемые стили: flex, margin/padding, fontSize, color, textAlign и др.
Не поддерживается: полный набор браузерного CSS, выполнение JS внутри PDF.

Короткий глоссарий

Document — корневой компонент PDF.
Page — страница внутри документа.
View — контейнер (аналог div).
Text — текстовый блок.
PDFViewer — компонент‑просмотрщик для браузера.

Итог

React-pdf даёт удобный декларативный способ генерировать PDF с использованием знакомой модели React. Он идеален для отчётов, счётов и шаблонов, но нужно учитывать ограничения по стилям и шрифтам. Выберите инструмент в зависимости от требований к точности визуала и инфраструктуры (клиент/сервер).

Важно: протестируйте ключевые кейсы — переносы, шрифты, изображения и экспорт — прежде чем запускать в продакшен.

Список ссылок и ресурсов для изучения:

Официальная документация @react-pdf/renderer
Альтернативы: Puppeteer, jsPDF, PDFKit

Создание PDF из React‑компонентов с react-pdf