SVG-логотипы React-pdf: вывод контуров в PDF

Для небольшого SVG-логотипа в @react-pdf/renderer соберите графику из Svg, Path и других поддерживаемых компонентов. Задайте внешнему Svg явные размеры и сохраните исходный viewBox. Документация Image рендерера перечисляет входные форматы PNG и JPG; передача URL SVG в Image не является описанным здесь векторным способом.

В руководстве используется полный пример Node с квадратной эмблемой и отверстием в центре. Мы отрендерили PDF с закрепленными зависимостями и проверили результат. Пример разделяет три вещи, которые легко перепутать: исходную графику, дерево компонентов и размер размещения в PDF.

Проверьте, какой пакет React PDF вы используете

Эта статья генерирует документы с @react-pdf/renderer. Отдельный пакет react-pdf показывает существующие PDF. Проверьте импорт в своем файле, прежде чем копировать решение из поисковой выдачи.

Внутри Document рендерера используйте компоненты, экспортируемые этим рендерером. Строчные браузерные элементы svg и path относятся к другой среде рендеринга. Официальный справочник компонента SVG определяет Svg как контейнер области просмотра и показывает внутри него импортированные фигуры React-pdf.

Справочник Image описывает растровые входные данные. Запасной PNG может быть полезен, когда сложный внешний вид важнее сохранения векторной геометрии. Он меняет итоговый файл, поэтому храните векторный оригинал отдельно.

Есть и официальный пакет @react-pdf/svg. Его README описывает parseSvg(), возвращающий дерево узлов-примитивов и переводящий имена атрибутов в camelCase. Неподдерживаемые элементы пропускаются с предупреждением. Это контракт парсера, а не обещание идентичного отображения любого браузерного SVG. В примере ниже используются явные компоненты, чтобы геометрию и оформление было легко проверить.

Отрендерите минимальный логотип перед импортом своего

Мы запускали пример с @react-pdf/renderer 4.9.0, React 19.2.4 и Node 22.19.0. Эти версии определяют проверенное окружение и не гарантируют поведение другого дерева зависимостей.

В новом каталоге установите два пакета, необходимые для запуска:

npm install --save-exact @react-pdf/renderer@4.9.0 react@19.2.4

Сохраните код как logo.mjs, затем запустите node logo.mjs. Он использует React.createElement, поэтому Node может выполнить его без этапа сборки JSX.

import React from 'react';
import { fileURLToPath } from 'node:url';
import {
  Document, Page, Svg, Path, Rect, renderToFile,
} from '@react-pdf/renderer';
 
const h = React.createElement;
const ring = 'M10 10H90V90H10Z M30 30H70V70H30Z';
 
const logo = h(
  Svg,
  { width: 144, height: 144, viewBox: '0 0 100 100' },
  h(Rect, {
    x: 0, y: 0, width: 100, height: 100, fill: '#f3ede2',
  }),
  h(Path, { d: ring, fill: '#087f8c', fillRule: 'evenodd' }),
);
 
await renderToFile(
  h(Document, null,
    h(Page, { size: 'A4', style: { padding: 36 } }, logo),
  ),
  fileURLToPath(new URL('./logo.pdf', import.meta.url)),
);

Внешний и внутренний квадраты входят в один составной контур. fillRule: 'evenodd' оставляет внутренний квадрат открытым, и сквозь него виден светлый прямоугольник снизу. Центр не прикрыт белым участком. Поэтому отверстие удобно проверять при замене теста логотипом с просветами или вырезами.

Координаты SVG занимают 100 единиц в каждом направлении, а размещенная область просмотра имеет размер 144 на 144. viewBox описывает систему координат рисунка; width и height — отображаемую область просмотра. Сохраняйте это различие при изменении размера логотипа. Официальная таблица свойств Svg описывает эти параметры и preserveAspectRatio.

Проверяйте сохраненный PDF вместе с предпросмотром

Наш тест создал одну страницу A4 с бирюзовой квадратной рамкой возле верхнего левого угла. Мы отрендерили файл с Poppler и визуально проверили, что светлый фон виден через отверстие. Команда Poppler pdfimages -list logo.pdf не нашла встроенных изображений в этом отдельном документе.

Этот результат намеренно узкий: он описывает тест, состоящий только из контуров. Он не доказывает, что документ с фотографиями, встроенными изображениями SVG или неподдерживаемыми эффектами полностью векторный.

Если Poppler доступен на вашем компьютере, эти команды дают две разные проверки:

pdfimages -list logo.pdf
pdftoppm -png -singlefile -scale-to 1000 logo.pdf logo-preview

Вторая команда создает растровый предпросмотр для визуальной проверки, а не превращает исходный PDF в растр. Проверьте отверстие, углы, цвета и размещение в предпросмотре, затем откройте сохраненный PDF в просмотрщике получателя. Одна лишь четкость предпросмотра не доказывает наличие контуров в исходном документе: крупный растр тоже может выглядеть четким.

Для более надежной проверки изучите инструкции рисования PDF и связанные объекты вокруг логотипа. Сложные отчеты могут содержать вложенные объекты, поэтому начните с отдельного документа с логотипом, прежде чем диагностировать весь отчет. Руководство по SVG в PDFKit описывает другой процесс импорта SVG и проверки сохраненного PDF.

Переносите графику, проверяя по одной возможности SVG

Замените значение d тестового контура своими данными, затем сохраните соответствующие заливку, правило заливки, обводку и преобразование. Если скопировать только форму контура без оформления, результат может измениться даже при корректных данных контура.

Для небольшого статичного знака задайте цвета непосредственно поддерживаемым фигурам. Если логотип зависит от таблицы стилей веб-страницы, эти зависимости нужно разрешить до превращения в самостоятельный компонент документа. Храните исходный SVG рядом с кодом рендеринга, чтобы последующие изменения можно было сравнить с утвержденной графикой.

Официальный обзор SVG перечисляет доступные примитивы. Используйте его как список поддерживаемых возможностей, а не полный набор возможностей браузерного SVG. Проверьте надписи, обрезку и градиенты в установленной версии до добавления в рабочий отчет.

Если SVG содержит встроенный PNG, перенос контейнера не восстанавливает недостающую геометрию. Руководство по встроенному растру показывает, как отличить контуры от растрового изображения внутри SVG.

Если логотип начинается с PNG или JPG

Если есть оригинальный SVG, AI или другой редактируемый векторный оригинал, сначала запросите его. Если остались только пиксели, векторизатор логотипов PerfectVector может подготовить вариант SVG до работы с React-pdf. Сравните его контуры, маленькие отверстия и отдельные цветовые области с исходником, прежде чем адаптировать поддерживаемые фигуры к компоненту PDF.

Векторизация не исправляет интеграцию рендерера, не создает компонент React и не гарантирует поддержку всех возможностей SVG. Надписи, требующие точной фирменной геометрии, проверяйте вручную. Руководство по векторизации логотипа помогает выбрать между трассировкой, повторным набором и перерисовкой.

Для растрового исходника полезный результат — проверенный векторный вариант, за которым следует проверенный PDF. Для существующего векторного исходника сразу переходите к проверкам компонентов и размещения. Дополнительные советы по подготовке исходников есть в блоге.

FAQ

Можно ли передать SVG-файл в React-pdf Image? Документированные входные форматы Image — PNG и JPG. Для процесса с контурами из этого руководства используйте примитивы Svg рендерера и проверяйте установленную версию, прежде чем полагаться на другое поведение входных данных.

Нужно ли переносить каждый SVG вручную? Нет. Официальный пакет @react-pdf/svg разбирает строки SVG в деревья узлов-примитивов. Изучите поддерживаемые элементы и предупреждения, затем подключите и проверьте вывод в своем процессе рендеринга. Пример с явными компонентами здесь позволяет обойти дополнительный этап парсера.

Почему центр логотипа заполняется? Проверьте составной контур и его правило заливки. Тестовая эмблема использует evenodd, поэтому внутренний квадрат остается открытым. Сохраните исходную геометрию и правила оформления, прежде чем менять графику.

Доказывает ли четкий предпросмотр PDF, что логотип векторный? Нет. Проверьте содержимое и объекты изображений сохраненного PDF вместе с внешним видом. В отдельном тесте этого руководства не было встроенных изображений; этот результат не распространяется автоматически на другой логотип.

Sources

1. React-pdf — Svg component — Определяет область просмотра, размеры, viewBox и управление соотношением сторон.
2. React-pdf — Image component — Описывает варианты ввода PNG и JPG для размещения растра.
3. React-pdf — SVG primitives — Перечисляет поддерживаемые рендерером компоненты SVG.
4. React-pdf — SVG parser — Описывает дерево примитивов, преобразование атрибутов и предупреждения о неподдерживаемых элементах.

Есть только PNG- или JPG-логотип? Подготовьте вариант SVG с PerfectVector, сравните контуры и отверстия с исходником, затем адаптируйте поддерживаемые фигуры и проверьте сохраненный PDF.