Создание PDF в React с помощью react-pdf

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

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

React — популярная библиотека JavaScript для создания интерфейсов. С помощью пакета @react-pdf/renderer можно генерировать PDF-файлы прямо из React-компонентов. Эта статья объясняет рабочий процесс шаг за шагом и даёт практичные советы для продакшн‑использования.

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

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

Краткое определение: react-pdf — renderer, который позволяет описывать содержание PDF с помощью знакомого JSX.

Установка react-pdf

В терминале проекта запустите одну из команд:

npm install @react-pdf/renderer --save

или

yarn add @react-pdf/renderer

Важно: используйте совместимую версию с вашей сборкой и версией React. Если проект работает в среде SSR или в Electron — проверьте документацию на предмет ограничений по окружению.

Создание базового PDF-документа

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

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

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

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

export default MyDocument;

В этом примере документ содержит одну страницу с текстом Hello There. Этот компонент ещё нужно отобразить в приложении.

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

Для предпросмотра в браузере используйте компонент PDFViewer. Он рендерит PDF внутри контейнера.

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

function App() {
  return (
    
      
    
  );
}

export default App;

Важно: PDFViewer — удобен для разработки и внутри браузера. Для сохранения на диск или генерации на сервере используйте другие API библиотеки (например renderToStream / renderToFile при поддержке).

Добавление стилей

react-pdf использует StyleSheet, похожий на React Native. Определите стили и примените через 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, margin, padding, alignItems, justifyContent, fontSize, color).
Нет CSS-брэкенд-движка: некоторые web‑свойства не поддерживаются.
Для кастомных шрифтов регистрируйте их через Font.register.

Макеты и вложенные контейнеры

Для группировки и колонок используется View. Он аналогичен div в вебе.

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;

Советы:

Для колонок используйте flexDirection: ‘row’.
Контент автоматически переносится на следующую страницу, но это поведение можно контролировать с помощью wrap и break.

Добавление изображений

Используйте компонент Image. Он принимает src и style.

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;

Поддерживаемые форматы: JPEG, PNG, SVG и другие. Для удалённых изображений учитывайте CORS и доступность URL. Для локальных файлов используйте import или base64.

Добавление ссылок

Для кликабельных ссылок используйте компонент Link. Он принимает src и стили.

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;

Ссылки сохраняют навигацию: при открытии PDF в поддерживающем просмотрщике клики направят пользователя на указанный URL.

Работа с шрифтами и локализацией

Если в документе используются нетипичные шрифты (кириллица, нестандартные веса), зарегистрируйте их через Font.register и указывайте family в стилях. Без регистрации кириллица может отображаться некорректно.

Пример:

import { Font } from '@react-pdf/renderer';
Font.register({
  family: 'RobotoCyr',
  src: 'https://example.com/fonts/roboto-cyr.ttf'
});

Важно: убедитесь в лицензии шрифта перед встраиванием.

Когда react-pdf не подходит

Важно:

react-pdf не заменит полноценный WYSIWYG-редактор для сложных публикаций. Он удобен для отчётов, счётов, бланков и печатных форм.
Для лёгкой верстки с абсолютным позиционированием и множеством сложных CSS-трюков откажитесь от попыток «перенести» весь CSS из веба — не всё поддерживается.
Для больших объёмов параллельной генерации на сервере проверьте потребление памяти и потоки рендеринга.

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

Если react-pdf не подходит, рассмотрите:

Генерация HTML и конвертация в PDF через headless Chrome (Puppeteer). Подходит для точной веб-верстки.
Серверные библиотеки (PDFKit, wkhtmltopdf) для более низкоуровневого контроля.
Шаблонизаторы + внешние сервисы (если хотите делегировать рендеринг).

Плюсы react-pdf: декларативность, повторное использование компонентов, однородность с кодовой базой React.

Контроль качества и критерии приёмки

Критерии приёмки для документа:

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

Тесты:

Рендер документа в трёх популярных PDF‑просмотрах (браузерный, Adobe Reader, мобильное приложение).
Генерация документа из тестового набора данных (edge‑кейсы: пустые поля, очень длинные строки, специальные символы).

Чек-лист ролей

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

Установил @react-pdf/renderer
Зарегистрировал шрифты при необходимости
Написал unit‑тесты для генерации метаданных
Проверил рендер в разных просмотрщиках

QA:

Тестовые данные с краевыми значениями
Проверка кликабельных ссылок
Проверка качества изображений
Сравнение с эталоном (визуальный регресс)

Продукт/PM:

Подтвердил содержание и метаданные документа
Одобрил ограничение размера PDF

Полезная шпаргалка по коду

Компоненты:

Document — корень документа.
Page — страница PDF.
Text — текст.
View — контейнер для layout.
Image — картинка.
Link — кликабельная ссылка.
StyleSheet — стили.

Короткая подсказка: используйте StyleSheet.create для читаемых стилей; выносите повторяющиеся блоки в отдельные компоненты.

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

При обновлении версии библиотеки:

Проверьте список breaking changes в релиз-нотах.
Тестируйте рендер ключевых шаблонов после обновления.
Если используете кастомные шрифты — убедитесь, что API регистрации не изменился.

Примеры ошибок и способы их устранения

Проблема: кириллица не отображается. Решение: зарегистрируйте подходящий шрифт и укажите family в стилях.

Проблема: изображение не загружается при локальном импорте. Решение: используйте URL или импортируйте как data URL / base64 или убедитесь, что путь доступен при сборке.

Проблема: большие таблицы разрываются некорректно. Решение: разбивайте данные по страницам вручную или используйте подход с нумерацией и контролем разрыва.

Краткое резюме

react-pdf даёт удобный способ описывать PDF через JSX. Библиотека подходит для большинства задач автоматической генерации отчётов, счетов и бланков. Она не заменит сложную веб‑верстку везде, но выигрывает благодаря декларативности и интеграции с React.

Важно: тестируйте финальные PDF в реальных просмотрщиках и следите за шрифтами и качеством изображений.

Ключевые шаги для старта: