SVG no jsPDF: mantenha os traçados do logo em um PDF criado no navegador

Para inserir traçados de um logo SVG em um PDF gerado no navegador com jsPDF, carregue svg2pdf.js, passe um elemento SVG para await doc.svg(...) e salve o documento. Escolha addSvgAsImage somente quando uma imagem raster for aceitável. Sua entrada SVG não significa que o PDF resultante contém traçados SVG.

O exemplo de uso de svg2pdf.js documenta a chamada assíncrona baseada em elemento. A implementação do módulo SVG do jsPDF mostra a outra opção: renderizar em um canvas, codificar um JPEG e adicionar essa imagem ao PDF.

Para um logo em uma fatura, ingresso ou relatório, mantenha o SVG original como mestre editável. Este guia testa um emblema simples de duas cores, define seu posicionamento em pontos de PDF e confere os objetos salvos. Ele não pressupõe que todos os recursos de SVG serão preservados na conversão.

Escolha a saída de que você precisa

A terceira opção é útil quando você precisa de um PDF do logo já preparado, em vez de um documento montado em JavaScript. Para fluxos de documentos fora do navegador, o guia de SVG no LaTeX explica um processo separado de exportação e inclusão. Para um fluxo de documentos em Node, o exemplo de SVG no PDFKit distingue a inserção de um documento completo da interpretação de um único traçado.

Quando a entrega for uma apresentação de slides, use o guia de imagem SVG no PptxGenJS. Ele confere a proporção do logo, a mídia do PPTX exportado e sua aparência no aplicativo de apresentação, em vez de aplicar configurações de exportação PDF a outro formato de documento.

Execute primeiro um pequeno exemplo com versões fixadas

O exemplo foi executado em um navegador com jsPDF 4.2.1 e svg2pdf.js 2.8.1. Essas são as versões testadas, não uma promessa sobre lançamentos futuros. O pacote se chama svg2pdf.js, incluindo o sufixo; pacotes com nomes semelhantes podem atender a outros fluxos.

Em um pequeno projeto para navegador com um empacotador JavaScript, instale:

npm install jspdf@4.2.1 svg2pdf.js@2.8.1

Use este emblema original como entrada. Seu anel tem uma abertura real pela regra de preenchimento par-ímpar. O segundo traçado é um pico arredondado. Não há fontes, arquivos vinculados, filtros nem imagens raster incorporadas.

import { jsPDF } from 'jspdf';
import 'svg2pdf.js';
 
const svgText = `<svg xmlns="http://www.w3.org/2000/svg"
  width="240" height="160" viewBox="0 0 240 160">
  <path fill="#174d64" fill-rule="evenodd"
    d="M20 80 C20 15 120 15 120 80 C120 145 20 145 20 80 Z
       M48 80 C48 111 92 111 92 80 C92 49 48 49 48 80 Z"/>
  <path fill="#e66d45"
    d="M130 120 L170 35 Q178 20 188 35 L225 120 Z"/>
</svg>`;
 
async function makeVectorPdf() {
  const svg = new DOMParser()
    .parseFromString(svgText, 'image/svg+xml')
    .documentElement;
  const doc = new jsPDF({
    unit: 'pt',
    format: [300, 220],
    orientation: 'landscape'
  });
  await doc.svg(svg, { x: 30, y: 30, width: 240, height: 160 });
  return doc;
}
 
const doc = await makeVectorPdf();
doc.save('logo-vector.pdf');

Execute isso no navegador, não diretamente em um script Node.js. As notas de uso e escopo da biblioteca exigem um DOM de navegador funcional e descrevem suporte limitado a SVG. Em um aplicativo com renderização no servidor, coloque esse trabalho no manipulador de exportação do lado do cliente.

A string aqui é uma arte fixa e confiável. Se seu aplicativo aceita uploads arbitrários de SVG, interpretar XML, por si só, não é sanitização. Siga as orientações da biblioteca para sanitizar SVGs fornecidos por usuários e isolar sua execução antes de criar um fluxo de upload.

Defina o posicionamento separadamente do viewBox

Neste exemplo, unit: 'pt' faz as medidas do PDF serem em pontos. A página tem 300 por 220 pontos; a área de visualização da arte começa a 30 pontos da esquerda e do topo e ocupa 240 por 160 pontos. A documentação do construtor do jsPDF descreve as opções de unidade, formato e orientação do documento.

O viewBox="0 0 240 160" do SVG descreve suas coordenadas internas. Ele não é um tamanho de página PDF. Manter a largura e a altura de destino na mesma proporção 3:2 facilita conferir o ajuste pretendido. Para reduzir a arte inserida à metade, use width: 120, height: 80; as coordenadas dos traçados de origem podem permanecer iguais.

Dê ao SVG exportado dimensões explícitas e um viewBox adequado antes de investigar sua posição no PDF. Uma borda vazia inesperadamente grande pode pertencer à tela do SVG. Mover x e y move toda a área de visualização SVG, incluindo esse espaço vazio.

Inspecione os dois PDFs salvos

Para comparação, a mesma execução no navegador também criou esta versão rasterizada deliberadamente:

const raster = new jsPDF({
  unit: 'pt',
  format: [300, 220],
  orientation: 'landscape'
});
await raster.addSvgAsImage(svgText, 30, 30, 240, 160);
raster.save('logo-raster.pdf');

O teste usou a dependência canvg instalada pelo jsPDF, 3.0.11, nessa opção. Os dois PDFs foram salvos, reabertos e renderizados na mesma escala. A inspeção de desenhos e imagens do PyMuPDF informou:

O fluxo de conteúdo do arquivo vetorial continha comandos de curva e um preenchimento par-ímpar para o anel. O arquivo raster inseriu um objeto de imagem. Essas contagens descrevem este pequeno exemplo de teste; um SVG mais complexo pode produzir objetos diferentes ou conter seu próprio conteúdo raster.

O retângulo preto é um resultado observado dessa exportação raster, incluindo a abertura antes transparente do anel. JPEG não preserva transparência alfa; não suponha que as regiões transparentes de um SVG serão mantidas nessa opção. Confira o fundo de que você realmente precisa, especialmente quando o logo ficará sobre um painel colorido do documento.

Aplicar zoom, por si só, não é evidência suficiente. Todo visualizador de PDF acaba desenhando pixels na sua tela. Inspecione os objetos do PDF e compare a aparência salva com o mestre SVG. Um comando como pdfimages -list logo-raster.pdf, do Poppler, pode listar imagens incorporadas. Uma lista vazia de imagens, sozinha, não comprova que as formas pretendidas foram exportadas corretamente: a página pode estar em branco. Confira também seu conteúdo de desenho e sua aparência.

Corrija a parte da exportação que falhou

Um SVG pode já envolver um bitmap. Passar esse arquivo por um exportador capaz de lidar com vetores não vetoriza seus pixels em contornos editáveis. Use o guia de inspeção de raster incorporado antes de alterar as configurações do PDF.

Este teste não abrange layout de texto, filtros, imagens externas nem CSS arbitrário. O svg2pdf.js limita explicitamente seu escopo a um subconjunto de SVG. Para letras, siga suas instruções de configuração de fontes antes da conversão ou prepare contornos no arquivo original do desenho quando essa escolha for adequada. Mantenha um mestre com texto editável se mudanças futuras na redação forem importantes.

Prepare o arquivo original do logo com o PerfectVector

Se o logo já é uma arte vetorial limpa, use esse arquivo original. Se resta apenas um PNG ou JPG, o PerfectVector pode ajudar a recuperar formas editáveis antes da etapa de PDF. Vetorize o logo e inspecione seu contorno externo, pequenas aberturas e cores separadas em um editor SVG. O guia de preparação de logos aborda essa inspeção em mais detalhes.

O PerfectVector prepara a arte raster para esse fluxo; ele não adiciona suporte a SVG ao jsPDF nem corrige recursos incompatíveis de um exportador. Compare os traçados recuperados com sua imagem original, simplifique ou redesenhe detalhes que precisem disso e execute novamente a verificação do PDF. Preserve uma fotografia como imagem quando a vetorização implicar perder os detalhes de que você precisa. O guia mais amplo de vetorização de imagens explica essa escolha de imagem original.

Perguntas frequentes

addSvgAsImage mantém meu SVG como traçados vetoriais? Não. A implementação testada do jsPDF 4.2.1 renderiza o SVG por meio de um canvas e incorpora um JPEG. Use svg2pdf.js com doc.svg quando precisar converter sua geometria compatível em conteúdo de desenho do PDF.

doc.svg aceita um nome de arquivo SVG? A API demonstrada recebe um elemento DOM SVG. Carregue e interprete primeiro um arquivo confiável ou selecione um elemento SVG existente; depois, passe esse elemento para doc.svg e aguarde o resultado.

Todos os SVGs terão a mesma aparência no PDF? Não. O svg2pdf.js oferece suporte a uma parte limitada de SVG. Teste sua arte real, incluindo fontes, imagens, efeitos, dimensões e fundos, e reabra o PDF salvo antes de usá-lo.

Fontes

1. yWorks — uso e escopo do svg2pdf.js — API de elemento SVG, conversão assíncrona, configuração de fontes, requisitos do navegador e limitações de escopo compatível.
2. jsPDF — módulo SVG na versão 4.2.1 — Implementação com canvas e JPEG usada por addSvgAsImage.
3. jsPDF — referência do construtor — Unidades do documento PDF, formato da página e opções de orientação.
4. PyMuPDF — inspeção de páginas — Métodos de inspeção de desenhos e imagens usados para examinar os arquivos de teste salvos.

Você só tem um logo raster? Prepare um SVG editável a partir do seu logo, confira seus contornos e aberturas, exporte-o com a opção de PDF escolhida e inspecione os objetos e o fundo salvos.