SVG en PDFKit: coloca un logotipo vectorial sin aplanarlo

Para colocar un logotipo SVG completo en un PDF generado con Node, utiliza svg-to-pdfkit con PDFKit y pasa el marcado SVG a SVGtoPDF(doc, svg, x, y, options). El método integrado doc.path() de PDFKit acepta datos de trazado SVG, como el valor del atributo d de un trazado. No importa el documento SVG que lo rodea, sus demás formas ni sus estilos.

La diferencia importa para un logotipo con varios colores y una abertura central. Copiar un trazado puede dejar fuera parte de la ilustración. Convertir todo el logotipo a PNG conserva una representación ráster, pero renuncia a la salida PDF basada en trazados que buscabas.

Esta guía utiliza un emblema original, un script completo de Node y una revisión del PDF guardado. Si ya tienes un logotipo vectorial editable, consérvalo como original. La recuperación desde ráster corresponde al paso anterior a esta importación.

Elige entre insertar un SVG completo o un único trazado

La documentación vectorial de PDFKit describe el analizador de trazados y los métodos de dibujo relacionados. La biblioteca independiente SVG-to-PDFKit gestiona el marcado SVG completo.

La documentación de imágenes de PDFKit incluye PNG y JPEG para doc.image(). No trates esa llamada como un importador completo de SVG.

Por ejemplo, este es un uso válido de la API de trazados:

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

Dibuja el triángulo de nuestro emblema en sus coordenadas de trazado. No recupera el anillo verde azulado ni la barra de otra parte del archivo original. Utiliza la vía de documento completo siguiente cuando esas piezas deban permanecer juntas.

Si montas el PDF en un navegador con jsPDF, sigue el flujo independiente de SVG con jsPDF. Para un documento de componentes React, utiliza el flujo de logotipos SVG con React-pdf. Para documentos Python, compara las comprobaciones de importación y tamaño de ReportLab con la colocación directa de SVG en fpdf2.

Ejecuta un ejemplo pequeño con paquetes de versión fija

Ejecutamos este ejemplo con PDFKit 0.20.2 y SVG-to-PDFKit 0.1.8. Esas versiones identifican el par de dependencias probado; revisa tu propia salida después de actualizar cualquiera de los paquetes.

En un proyecto nuevo de Node, instala:

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

Guarda esto como logo.svg. El anillo y su abertura comparten un trazado con fill-rule="evenodd"; el triángulo dorado y la barra verde azulada son formas separadas. El archivo no contiene fuentes, imágenes ni efectos.

<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>

Guarda lo siguiente como place-logo.cjs en el mismo directorio y ejecuta 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;
});

PDFKit produce un flujo de datos. Llamar a doc.end() finaliza el documento; después el script espera a que termine el flujo de salida antes de regresar. La documentación de primeros pasos explica el modelo de flujos y las dimensiones de página en puntos PDF, con 72 puntos por pulgada.

Aquí, las dos ventanas de colocación son 180 × 90 pt y 90 × 45 pt, o 2.5 × 1.25 pulgadas y 1.25 × 0.625 pulgadas. Ambas coinciden con la proporción 2:1 del viewBox original. Las formas dibujadas tienen márgenes dentro del viewBox, por lo que sus límites visibles son menores que la ventana. Mide por separado el lienzo y la ilustración pintada al alinear un logotipo con texto cercano.

El importador documenta width y height como la ventana inicial. Su opción preserveAspectRatio controla el ajuste dentro de ella. Este ejemplo utiliza proporciones coincidentes y dimensiones explícitas para no depender de un valor predeterminado del tamaño de página. No utilices assumePt como solución general para un logotipo inesperadamente pequeño; comprueba primero las dimensiones originales, el viewBox y la ventana de destino.

Revisa el PDF y después su apariencia

Nuestro logo.pdf mínimo tenía una página de 800 × 450 pt. Con pypdf 6.10.0, encontramos 24 operaciones de curvas cúbicas, dos operaciones de relleno par-impar y cero imágenes de página. Sus recursos de página no contenían fuentes ni XObjects. El importador no emitió advertencias para este ejemplo.

Estos resultados respaldan una conclusión limitada: este emblema original sin imágenes se dibujó mediante geometría PDF en las versiones probadas. No demuestran que cualquier SVG produzca un PDF completamente vectorial. Un logotipo con una fotografía incrustada todavía requiere una revisión independiente.

También renderizamos una versión etiquetada con Poppler. Utiliza el mismo SVG y dos tamaños de ventana, con las colocaciones desplazadas a paneles de comparación. El fondo pálido del panel sigue visible a través de ambos anillos, y el triángulo y la barra estrecha siguen separados del anillo.

La nitidez al ampliar es una prueba débil: un mapa de bits suficientemente grande también puede verse nítido. A la inversa, encontrar una operación de curva en algún lugar de un informe no dice nada sobre si su logotipo se rasterizó. Aísla la ilustración en un PDF de prueba pequeño antes de revisar un documento que también contenga fotos y gráficos.

Para tu propio logotipo, realiza ambas comprobaciones:

1. Revisa el contenido de página y los objetos referenciados del PDF con una herramienta de inspección PDF. Busca instrucciones de dibujo donde se pinta el logotipo y ten en cuenta los objetos de imagen. Los PDF más complejos pueden colocar contenido dentro de Form XObjects, por lo que un recuento de nivel superior no siempre basta.
2. Abre el PDF guardado en el visor de destino y compáralo con el original. Comprueba la abertura, los colores separados, los recortes, los márgenes y los detalles finos al tamaño real de entrega.

Conserva el SVG original junto al código de generación del PDF. Si el original solo envuelve píxeles, utiliza el diagnóstico de imágenes incrustadas antes de suponer que la extensión SVG demuestra algo sobre su geometría.

Mantén las fuentes y los efectos dentro del flujo probado

SVG-to-PDFKit incluye los filtros y foreignObject entre sus funciones no compatibles. También documenta requisitos de registro de fuentes y callbacks. Utiliza atributos explícitos de presentación SVG para un logotipo pequeño del lado del servidor y revisa las advertencias junto con el resultado renderizado. El CSS calculado por el navegador es una opción aparte para un elemento SVG proporcionado; no equivale a pasar marcado a este script de Node. Consulta la documentación de funciones y fuentes de la biblioteca.

Nuestro emblema evita deliberadamente el texto. Para letras reales, proporciona y prueba las fuentes previstas o conserva las letras aprobadas como contornos en el vector maestro. La documentación de fuentes de PDFKit describe la incrustación y el registro de fuentes. El texto del documento y los contornos del logotipo tienen necesidades de edición distintas; trazar una captura de letras no identifica la fuente original.

Si una marca depende de un efecto que este importador no puede reproducir, reconstrúyelo como geometría adecuada o elige otro flujo de exportación y verifícalo. Insertar un ráster también es válido cuando la apariencia importa más que conservar trazados. No describas esa elección como una exportación que conserva vectores.

El ejemplo utiliza colores RGB. Conservar trazados no basta para cumplir los requisitos de color, PDF/X o preimpresión de una imprenta. Confírmalos con el destinatario; la guía de formatos de logotipos ayuda a distinguir un maestro editable de un archivo de entrega.

Recupera un logotipo solo ráster antes de insertarlo

Si el logotipo original solo existe como PNG o JPG, el vectorizador de logotipos de PerfectVector puede preparar un SVG candidato antes del paso de PDFKit. Compara sus contornos, aberturas pequeñas y regiones de color separadas con el original y somételo a las mismas comprobaciones de colocación y PDF.

Utiliza el vector original siempre que esté disponible. Para letras dañadas o geometría exacta de marca, vuelve a escribir o redibuja la parte afectada en un editor. La guía de vectorización de logotipos explica esa decisión sobre el original. PerfectVector prepara los trazados de la ilustración; PDFKit y su importador gestionan la colocación en el documento. El emblema de prueba de este artículo es una ilustración vectorial dibujada a mano, no un resultado medido de conversión.

Preguntas frecuentes

¿PDFKit puede importar un SVG completo con doc.path()? No. El método de trazado lee datos de trazado SVG. Utiliza SVG-to-PDFKit para el documento completo en este flujo, o dibuja y aplica estilo a cada forma por tu cuenta.

¿SVG-to-PDFKit garantiza un PDF sin imágenes ráster? No. El emblema probado sin imágenes produjo operaciones de dibujo y cero imágenes de página. Revisa tu propia entrada y el PDF exportado, especialmente si el SVG contiene imágenes incrustadas o funciones fuera del conjunto compatible del importador.

¿Por qué el logotipo visible es menor que mi ancho y altura? Esas opciones definen la ventana de importación. El espacio vacío del viewBox original sigue formando parte de la composición, y el ajuste de proporciones puede dejar espacio adicional. Comprueba los límites de la ilustración antes de cambiar el tamaño PDF solicitado.

Fuentes

1. PDFKit — Gráficos vectoriales — Documenta el análisis de datos de trazado SVG, las operaciones de pintado y el estado gráfico.
2. SVG-to-PDFKit — Uso y limitaciones — Define la inserción de SVG completo, opciones de ventana, advertencias, fuentes y funciones compatibles.
3. PDFKit — Imágenes — Enumera los formatos de mapa de bits admitidos por la API de imágenes.
4. PDFKit — Primeros pasos — Explica los flujos de documentos, la finalización y el tamaño de página en puntos PDF.
5. PDFKit — Fuentes — Describe la incrustación de fuentes y su registro con nombre.

Si el logotipo de tu documento parte de una imagen ráster, prepara un SVG candidato con PerfectVector, revisa sus aberturas y contornos, colócalo al tamaño PDF requerido y comprueba el archivo guardado.