Logos SVG no React-pdf: traçados no seu PDF

Para um pequeno logo SVG em @react-pdf/renderer, construa a arte com seus componentes Svg, Path e outros compatíveis. Dê ao Svg externo um tamanho explícito e mantenha o viewBox da origem. A documentação de Image do renderizador lista entradas PNG e JPG; colocar uma URL SVG em Image não é o caminho vetorial descrito aqui.

Este guia usa um exemplo Node completo com um emblema quadrado e uma abertura no centro. Renderizamos o PDF com dependências de versões fixadas e inspecionamos o resultado. O exemplo isola três coisas fáceis de confundir: a arte de origem, a árvore de componentes e o tamanho de inserção no PDF.

Confira qual pacote React PDF você usa

Este artigo gera documentos com @react-pdf/renderer. O pacote chamado react-pdf, que é separado, exibe PDFs existentes. Confira a importação em seu arquivo antes de copiar uma solução de um resultado de busca.

Dentro de um Document do renderizador, use componentes exportados por ele. Os elementos svg e path minúsculos do navegador pertencem a outro ambiente de renderização. A referência oficial de componentes SVG define Svg como o contêiner da viewport e mostra formas React-pdf importadas dentro dele.

A referência de Image descreve entradas bitmap. Uma alternativa PNG pode ser útil quando uma aparência complexa importa mais do que manter geometria vetorial. Isso muda a entrega, portanto guarde o original vetorial separadamente.

Também existe um pacote oficial @react-pdf/svg. Seu README documenta parseSvg(), que retorna uma árvore de nós primitivos e converte os nomes de atributos para camelCase. Ele informa que elementos incompatíveis são ignorados com um aviso. Esse é um contrato do parser, não uma promessa de que todo SVG de navegador seja renderizado de forma idêntica. O exemplo abaixo usa componentes explícitos para manter a geometria e a pintura fáceis de inspecionar.

Renderize um logo mínimo antes de importar o seu

Executamos este exemplo com @react-pdf/renderer 4.9.0, React 19.2.4 e Node 22.19.0. Essas versões identificam a configuração testada; não garantem o comportamento de uma árvore de dependências diferente.

Em um diretório novo, instale os dois pacotes de execução:

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

Salve isto como logo.mjs e execute node logo.mjs. Ele usa React.createElement para que o Node possa executá-lo sem uma etapa de compilação 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)),
);

Os quadrados externo e interno compartilham um traçado composto. fillRule: 'evenodd' deixa o quadrado interno aberto, mostrando o retângulo claro por baixo. Não há uma área branca cobrindo o centro. Isso torna a abertura uma verificação útil ao substituir o exemplo por um logo que contenha espaços internos de letras ou recortes.

As coordenadas SVG abrangem 100 unidades em cada direção, enquanto sua viewport de inserção é de 144 por 144. viewBox descreve o sistema de coordenadas do desenho; width e height descrevem a viewport exibida. Mantenha essa distinção ao ajustar o tamanho de um logo. A tabela oficial de propriedades de Svg documenta esses controles e preserveAspectRatio.

Inspecione o PDF salvo e também sua prévia

Nosso teste produziu uma página A4 com o anel quadrado verde-petróleo perto do canto superior esquerdo. Renderizamos esse arquivo com Poppler e verificamos visualmente que o fundo claro aparecia pela abertura. O comando pdfimages -list logo.pdf do Poppler não informou nenhuma imagem incorporada neste documento isolado.

Esse resultado é deliberadamente restrito. Ele descreve este exemplo composto apenas de traçados. Não estabelece que um documento com fotos, imagens SVG incorporadas ou efeitos incompatíveis seja inteiramente vetorial.

Se o Poppler estiver disponível em sua máquina, estes comandos fornecem duas verificações diferentes:

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

O segundo comando cria uma prévia raster para inspeção visual; ele não transforma o PDF original em bitmap. Confira a abertura, os cantos, as cores e o posicionamento nessa prévia, depois abra o PDF salvo no visualizador usado pelo destinatário. Uma prévia aparentemente nítida, sozinha, não comprova que o documento original contém traçados: um bitmap grande também pode parecer nítido.

Para uma inspeção mais forte, examine as instruções de desenho e os objetos referenciados no PDF ao redor do logo. Relatórios complexos podem conter objetos aninhados, portanto comece com um documento de logo isolado antes de diagnosticar o relatório inteiro. O guia de SVG no PDFKit explica um fluxo separado de importação SVG e suas verificações do PDF salvo.

Transfira sua arte um recurso por vez

Substitua o valor d do exemplo pelos dados do seu próprio traçado, preservando o preenchimento, a regra de preenchimento, o contorno e a transformação associados. Copiar apenas a forma de um traçado, descartando sua pintura, pode mudar o resultado mesmo quando os próprios dados do traçado são válidos.

Para uma pequena marca estática, coloque as cores diretamente nas formas compatíveis. Um logo que depende da folha de estilo de uma página web precisa dessas dependências resolvidas antes de se tornar um componente de documento autossuficiente. Guarde o SVG de origem ao lado do código de renderização para comparar revisões futuras com a arte aprovada.

A visão geral oficial de SVG lista as primitivas disponíveis. Trate-a como uma lista de compatibilidade, não como o conjunto completo de recursos SVG do navegador. Teste letras, recortes e gradientes na versão instalada antes de adicioná-los ao relatório de produção.

Se o SVG contém um PNG incorporado, adaptar seu contêiner não reconstrói a geometria ausente. O guia de raster incorporado mostra como distinguir traçados de um bitmap armazenado dentro de um arquivo SVG.

Quando o logo começa como PNG ou JPG

Se existe um original SVG, AI ou outro original vetorial editável, peça esse arquivo primeiro. Se apenas pixels restaram, o vetorizador de logos do PerfectVector pode preparar um candidato SVG antes do trabalho no React-pdf. Compare seus contornos, pequenas aberturas e áreas separadas de cor com a origem antes de adaptar suas formas compatíveis ao componente PDF.

A vetorização não corrige a integração do renderizador, não cria um componente React nem garante suporte a todos os recursos SVG. Mantenha as letras que exigem geometria exata da marca sob revisão manual. O guia de vetorização de logos ajuda a escolher entre traçar, redigitar e redesenhar.

Para uma origem apenas raster, o resultado útil é um candidato vetorial inspecionado seguido de um PDF verificado. Para uma origem vetorial existente, prossiga diretamente para as verificações de componentes e posicionamento. Mais orientações de preparação da origem estão disponíveis no blog.

Perguntas frequentes

Posso passar um arquivo SVG para Image no React-pdf? As entradas documentadas de Image são PNG e JPG. Use as primitivas Svg do renderizador para o fluxo baseado em traçados deste guia e confira sua versão instalada antes de depender de outro comportamento de entrada.

Preciso converter cada SVG manualmente? Não. O pacote oficial @react-pdf/svg analisa strings SVG em árvores de nós primitivos. Revise seus elementos compatíveis e avisos, depois conecte e teste essa saída no fluxo de renderização. O exemplo com componentes explícitos aqui evita uma etapa extra de parser.

Por que o centro do meu logo fica preenchido? Confira o traçado composto e sua regra de preenchimento. O emblema de teste usa evenodd para manter aberto o quadrado interno. Preserve a geometria original e as regras de pintura antes de mudar a arte.

Uma prévia PDF nítida prova que o logo é vetorial? Não. Inspecione o conteúdo e os objetos de imagem do PDF salvo, além de sua aparência. O exemplo isolado deste guia não tinha imagens incorporadas; esse resultado não se aplica automaticamente a outro logo.

Fontes

1. React-pdf — Componente Svg — Define a viewport, as dimensões, o viewBox e os controles de proporção.
2. React-pdf — Componente Image — Documenta as formas de entrada PNG e JPG para inserção de bitmaps.
3. React-pdf — Primitivas SVG — Lista os componentes SVG compatíveis com o renderizador.
4. React-pdf — Parser SVG — Documenta a árvore de nós primitivos, a conversão de atributos e os avisos de elementos incompatíveis.

Só tem um logo PNG ou JPG? Prepare um candidato SVG com o PerfectVector, compare seus contornos e aberturas com a origem, adapte as formas compatíveis e inspecione o PDF salvo.