SVG no PDFKit: insira um logo vetorial sem achatar

Para inserir um logo SVG completo em um PDF gerado com Node, use svg-to-pdfkit com PDFKit e passe a marcação SVG para SVGtoPDF(doc, svg, x, y, options). O doc.path() integrado do PDFKit aceita dados de traçado SVG, como o valor do atributo d de um path. Ele não importa o documento SVG ao redor, suas outras formas nem seus estilos.

A distinção importa para um logo com várias cores e uma abertura no centro. Copiar um traçado pode deixar parte da arte para trás. Transformar o logo inteiro em PNG preserva uma renderização raster, mas abre mão da saída PDF baseada em traçados que você buscava.

Este guia usa um emblema original, um script Node completo e inspeção do PDF salvo. Se você já tem um logo vetorial editável, mantenha-o como origem. A recuperação de raster vem antes desta etapa de importação.

Escolha inserção de SVG completo ou de um único traçado

A documentação vetorial do PDFKit descreve o parser de traçados e os métodos de desenho ao redor dele. A biblioteca separada SVG-to-PDFKit trata de marcação SVG completa.

A documentação de imagens do PDFKit lista PNG e JPEG para doc.image(). Não trate essa chamada como importador de SVG completo.

Por exemplo, este é um uso válido da API de traçados:

doc.save();
doc.fillColor('#eeaa42');
doc.path('M125 100L175 20L225 100Z').fill();
doc.restore();

Ele desenha o triângulo do nosso emblema nas coordenadas do traçado. Não recupera o anel verde-petróleo nem a barra de outra parte do arquivo de origem. Use o caminho de documento completo abaixo quando essas peças pertencem ao mesmo conjunto.

Se seu PDF é montado em um navegador com jsPDF, siga o fluxo separado de SVG no jsPDF. Para um documento de componentes React, use o fluxo de logo SVG no React-pdf. Para documentos Python, compare as verificações de importação e tamanho do ReportLab com a inserção direta de SVG no fpdf2.

Execute um pequeno exemplo com versões fixadas

Executamos este exemplo com PDFKit 0.20.2 e SVG-to-PDFKit 0.1.8. Essas versões identificam o par de dependências testado; confira sua própria saída após atualizar qualquer pacote.

Em um novo projeto Node, instale:

npm install --save-exact pdfkit@0.20.2 svg-to-pdfkit@0.1.8

Salve isto como logo.svg. O anel e sua abertura compartilham um traçado com fill-rule="evenodd"; o triângulo dourado e a barra verde-petróleo são formas separadas. O arquivo não contém fontes, imagens nem efeitos.

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 240 120">
  <path fill="#147d78" fill-rule="evenodd"
    d="M110 60A50 50 0 1 1 10 60A50 50 0 1 1 110 60Z
       M85 60A25 25 0 1 1 35 60A25 25 0 1 1 85 60Z"/>
  <path fill="#eeaa42" d="M125 100L175 20L225 100Z"/>
  <rect x="227" y="20" width="8" height="80" fill="#147d78"/>
</svg>

Salve o seguinte como place-logo.cjs no mesmo diretório e execute node place-logo.cjs:

const fs = require('node:fs');
const { finished } = require('node:stream/promises');
const PDFDocument = require('pdfkit');
const SVGtoPDF = require('svg-to-pdfkit');
 
async function main() {
  const svg = fs.readFileSync('logo.svg', 'utf8');
  const doc = new PDFDocument({ size: [800, 450], margin: 0 });
  const output = fs.createWriteStream('logo.pdf');
  doc.pipe(output);
  const warnings = [];
  SVGtoPDF(doc, svg, 72, 150, {
    width: 180, height: 90,
    preserveAspectRatio: 'xMinYMin meet',
    warningCallback: message => warnings.push(message),
  });
  SVGtoPDF(doc, svg, 432, 150, {
    width: 90, height: 45,
    preserveAspectRatio: 'xMinYMin meet',
    warningCallback: message => warnings.push(message),
  });
  doc.end();
  await finished(output);
  fs.writeFileSync('warnings.json', JSON.stringify(warnings, null, 2));
  if (warnings.length) process.stderr.write(warnings.join('\n') + '\n');
}
main().catch(error => {
  process.stderr.write(error.stack + '\n');
  process.exitCode = 1;
});

O PDFKit produz um fluxo. Chamar doc.end() finaliza o documento; o script então aguarda o fluxo de saída terminar antes de retornar. A documentação de primeiros passos explica o modelo de fluxo e as dimensões de página em pontos PDF, com 72 pontos por polegada.

Aqui, as duas viewports de inserção são 180 × 90 pt e 90 × 45 pt, ou 2.5 × 1.25 polegadas e 1.25 × 0.625 polegadas. Ambas correspondem à proporção 2:1 do viewBox de origem. As formas desenhadas têm margens dentro desse viewBox, portanto seus limites visíveis são menores que a viewport. Meça a área de desenho e a arte pintada separadamente ao alinhar um logo com texto próximo.

O importador documenta width e height como a viewport inicial. Sua opção preserveAspectRatio controla o ajuste dentro dela. Este exemplo usa proporções correspondentes e dimensões explícitas para evitar depender de um padrão do tamanho da página. Não use assumePt como correção geral para um logo inesperadamente pequeno; primeiro confira dimensões de origem, viewBox e viewport de destino.

Inspecione o PDF e depois sua aparência

Nosso logo.pdf mínimo tinha uma página de 800 × 450 pt. Com pypdf 6.10.0, encontramos 24 operações de curva cúbica, duas operações de preenchimento par-ímpar e zero imagens de página. Seus recursos de página não continham fontes nem XObjects. O importador não emitiu aviso para este exemplo.

Esses resultados sustentam uma conclusão restrita: este emblema original sem imagens foi desenhado com geometria PDF nas versões testadas. Eles não estabelecem que qualquer SVG se torne um PDF inteiramente vetorial. Um logo com fotografia incorporada ainda exige inspeção separada.

Também renderizamos uma versão com rótulos usando Poppler. Ela usa o mesmo SVG e dois tamanhos de viewport, com as inserções movidas para painéis de comparação. O fundo claro dos painéis permanece visível através dos dois anéis, e o triângulo e a barra estreita permanecem separados do anel.

Apenas um zoom nítido é evidência fraca: um bitmap grande o suficiente também pode parecer nítido. Da mesma forma, encontrar uma operação de curva em algum lugar de um relatório não diz se seu logo foi rasterizado. Isole a arte em um pequeno PDF de teste antes de inspecionar um documento que também contém fotos e gráficos.

Para seu próprio logo, confira ambos:

1. Inspecione o conteúdo de página do PDF e os objetos referenciados com uma ferramenta de inspeção PDF. Procure instruções de desenho onde o logo é pintado e considere quaisquer objetos de imagem. PDFs mais complexos podem colocar conteúdo dentro de Form XObjects, portanto uma contagem no nível superior nem sempre basta.
2. Abra o PDF salvo no visualizador pretendido e compare-o com a origem. Confira abertura, cores separadas, recorte, margens e detalhes finos no tamanho real de entrega.

Guarde o SVG original ao lado do código de geração PDF. Se a origem apenas envolver pixels, use o diagnóstico de imagens incorporadas antes de presumir que uma extensão SVG comprove algo sobre sua geometria.

Mantenha fontes e efeitos dentro do fluxo testado

O SVG-to-PDFKit lista filtros e foreignObject entre seus recursos incompatíveis. Ele também documenta requisitos de registro de fontes e callbacks. Use atributos de apresentação SVG explícitos para um pequeno logo no servidor e revise os avisos junto do resultado renderizado. CSS calculado pelo navegador é uma opção separada para um elemento SVG fornecido; não é o mesmo que passar marcação para este script Node. Veja a documentação de recursos e fontes da biblioteca.

Nosso emblema evita texto deliberadamente. Para letras reais, forneça e teste as fontes pretendidas ou mantenha letras aprovadas convertidas em contornos no original vetorial. A documentação de fontes do PDFKit descreve incorporação e registro de fontes. Texto de documento e contornos de logo têm necessidades diferentes de edição; traçar uma captura de letras não identifica a fonte original.

Se uma marca depender de um efeito que esse importador não reproduz, reconstrua o efeito como geometria adequada ou escolha outro fluxo de exportação e verifique-o. Uma inserção raster também é uma escolha válida quando a aparência importa mais do que manter traçados. Não descreva essa escolha como uma exportação que preserva vetores.

O exemplo usa cores RGB. Apenas preservar traçados não estabelece os requisitos de cor, PDF/X ou pré-impressão de uma gráfica. Confirme-os com o destinatário; o guia de formatos de logo ajuda a separar um original editável de um arquivo de entrega.

Recupere um logo apenas raster antes da inserção

Se o logo original existe apenas como PNG ou JPG, o vetorizador de logos do PerfectVector pode preparar um candidato SVG antes da etapa PDFKit. Compare contornos, pequenas aberturas e regiões separadas de cor com a origem e execute esse candidato pelas mesmas verificações de posicionamento e PDF.

Use o vetor original sempre que disponível. Para letras danificadas ou geometria exata de marca, redigite ou redesenhe a parte afetada em um editor. O guia de vetorização de logos explica essa decisão sobre a origem. O PerfectVector prepara traçados da arte; o PDFKit e seu importador tratam da inserção no documento. O emblema de teste deste artigo é arte vetorial criada manualmente, não um resultado medido de conversão.

Perguntas frequentes

O PDFKit pode importar um SVG completo com doc.path()? Não. O método path lê dados de traçado SVG. Use SVG-to-PDFKit para o documento completo neste fluxo, ou desenhe e estilize cada forma você mesmo.

SVG-to-PDFKit garante um PDF sem imagens raster? Não. O emblema testado sem imagens produziu operações de desenho e zero imagens de página. Inspecione sua própria entrada e PDF exportado, especialmente quando o SVG contiver imagens incorporadas ou recursos fora do conjunto compatível do importador.

Por que o logo visível é menor que minha largura e altura? Essas opções definem a viewport de importação. O espaço vazio dentro do viewBox de origem permanece parte do layout, e o ajuste da proporção pode deixar espaço adicional. Confira os limites da arte antes de mudar o tamanho PDF solicitado.

Fontes

1. PDFKit — Gráficos vetoriais — Documenta análise de dados de traçado SVG, operações de pintura e estado gráfico.
2. SVG-to-PDFKit — Uso e limitações — Define inserção de SVG completo, opções de viewport, avisos, fontes e recursos compatíveis.
3. PDFKit — Imagens — Lista os formatos bitmap aceitos pela API de imagens.
4. PDFKit — Primeiros passos — Explica fluxos de documento, finalização e tamanho de página em pontos PDF.
5. PDFKit — Fontes — Descreve incorporação de fontes e registro de fontes nomeadas.

Se o logo do seu documento começa como imagem raster, prepare um candidato SVG com o PerfectVector, inspecione suas aberturas e contornos, insira-o no tamanho PDF necessário e confira o arquivo salvo.