PDFKit SVG: inserisci un logo senza rasterizzarlo

Per inserire un logo SVG completo in un PDF generato con Node, usa svg-to-pdfkit con PDFKit e passa il markup SVG a SVGtoPDF(doc, svg, x, y, options). Il metodo integrato doc.path() di PDFKit accetta dati di tracciato SVG, come il valore dell'attributo d di un tracciato. Non importa il documento SVG circostante, le altre forme o i suoi stili.

La distinzione conta per un logo con più colori e un'apertura al centro. Copiare un solo tracciato può lasciare indietro parte della grafica. Trasformare l'intero logo in PNG conserva un rendering raster, ma rinuncia all'output PDF composto da tracciati che cercavi.

Questa guida usa un emblema originale, uno script Node completo e l'ispezione del PDF salvato. Se hai già un logo vettoriale modificabile, mantienilo come sorgente. Il recupero raster viene prima di questo passaggio di importazione.

Scegli tra inserimento dell'SVG completo e singolo tracciato

La documentazione vettoriale di PDFKit descrive il parser dei tracciati e i metodi di disegno che lo accompagnano. La libreria separata SVG-to-PDFKit gestisce il markup SVG completo.

La documentazione delle immagini PDFKit elenca PNG e JPEG per doc.image(). Non considerare quella chiamata un importatore SVG completo.

Per esempio, questo è un uso valido dell'API dei tracciati:

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

Disegna il triangolo del nostro emblema alle coordinate del tracciato. Non recupera l'anello o la barra verde petrolio da un'altra parte del file sorgente. Usa il metodo con documento completo riportato sotto quando quei pezzi devono rimanere insieme.

Se il PDF viene assemblato nel browser con jsPDF, segui la procedura SVG separata per jsPDF. Per un documento basato su componenti React, usa la procedura per loghi SVG in React-pdf. Per documenti Python, confronta i controlli di importazione e dimensionamento ReportLab con il posizionamento diretto SVG in fpdf2.

Esegui un piccolo esempio con pacchetti a versione fissata

Abbiamo eseguito questo esempio con PDFKit 0.20.2 e SVG-to-PDFKit 0.1.8. Queste versioni identificano la coppia di dipendenze verificata; controlla il tuo output dopo aver aggiornato uno dei due pacchetti.

In un nuovo progetto Node, installa:

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

Salva questo codice come logo.svg. L'anello e la sua apertura condividono un tracciato con fill-rule="evenodd"; il triangolo dorato e la barra verde petrolio sono forme separate. Il file non contiene caratteri, immagini o effetti.

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

Salva il codice seguente come place-logo.cjs nella stessa directory, poi esegui 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 flusso. Chiamare doc.end() finalizza il documento; lo script attende poi che il flusso di output termini prima di concludersi. La documentazione introduttiva spiega il modello a flussi e le dimensioni delle pagine in punti PDF, con 72 punti per pollice.

Qui le due aree di visualizzazione per il posizionamento misurano 180 × 90 pt e 90 × 45 pt, ovvero 2.5 × 1.25 pollici e 1.25 × 0.625 pollici. Entrambe corrispondono al rapporto 2:1 del viewBox sorgente. Le forme disegnate hanno margini all'interno di quel viewBox, quindi i loro limiti visibili sono più piccoli dell'area di visualizzazione. Misura separatamente la tela e la grafica disegnata quando allinei un logo con testo vicino.

L'importatore documenta width e height come area di visualizzazione iniziale. L'opzione preserveAspectRatio controlla l'adattamento al suo interno. Questo esempio usa proporzioni corrispondenti e dimensioni esplicite per evitare di dipendere da un valore predefinito grande quanto la pagina. Non usare assumePt come soluzione generale per un logo inaspettatamente piccolo; controlla prima dimensioni sorgente, viewBox e area di visualizzazione di destinazione.

Ispeziona il PDF, poi il suo aspetto

Il nostro logo.pdf minimo aveva una pagina di 800 × 450 pt. Con pypdf 6.10.0, abbiamo trovato 24 operazioni di curva cubica, due operazioni di riempimento pari-dispari e zero immagini nella pagina. Le risorse della pagina non contenevano caratteri o XObject. L'importatore non ha emesso avvisi per questo esempio.

Questi risultati sostengono una conclusione circoscritta: questo emblema originale, privo di immagini, è stato disegnato con geometria PDF nelle versioni verificate. Non dimostrano che SVG arbitrari diventino PDF interamente vettoriali. Un logo contenente una fotografia incorporata richiede comunque un'ispezione separata.

Abbiamo anche renderizzato con Poppler una versione con etichette. Usa lo stesso SVG e due dimensioni dell'area di visualizzazione, con i posizionamenti spostati in pannelli di confronto. Lo sfondo chiaro dei pannelli rimane visibile attraverso entrambi gli anelli, e il triangolo e la barra sottile rimangono separati dall'anello.

La sola nitidezza all'ingrandimento è una prova debole: anche una bitmap sufficientemente grande può apparire nitida. Viceversa, trovare un'operazione di curva da qualche parte in una relazione non dice nulla su un'eventuale rasterizzazione del logo. Isola la grafica in un piccolo PDF di prova prima di ispezionare un documento che contiene anche foto e grafici.

Per il tuo logo, controlla entrambi gli aspetti:

1. Ispeziona il contenuto delle pagine e gli oggetti referenziati del PDF con uno strumento di ispezione PDF. Cerca istruzioni di disegno nel punto in cui viene disegnato il logo e tieni conto degli eventuali oggetti immagine. PDF più complessi possono collocare contenuto all'interno di Form XObject, quindi un conteggio al livello principale non è sempre sufficiente.
2. Apri il PDF salvato nel visualizzatore previsto e confrontalo con il sorgente. Controlla foro, colori separati, ritaglio, margini e dettagli fini alle dimensioni effettive di consegna.

Mantieni l'SVG originale accanto al codice di generazione PDF. Se il sorgente racchiude soltanto pixel, usa la diagnosi delle immagini incorporate prima di presumere che l'estensione SVG dimostri qualcosa sulla sua geometria.

Mantieni caratteri ed effetti nella procedura verificata

SVG-to-PDFKit elenca filtri e foreignObject tra le funzionalità non supportate. Documenta anche i requisiti di registrazione dei caratteri e delle callback. Usa attributi di presentazione SVG espliciti per un piccolo logo elaborato sul server ed esamina gli avvisi insieme al risultato renderizzato. Il CSS calcolato dal browser è un'opzione separata per un elemento SVG fornito; non equivale a passare markup a questo script Node. Consulta la documentazione su funzionalità e caratteri della libreria.

Il nostro emblema evita deliberatamente il testo. Per scritte reali, fornisci e verifica i caratteri previsti oppure conserva le scritte approvate convertite in tracciati nell'originale vettoriale. La documentazione sui caratteri PDFKit descrive incorporamento e registrazione dei caratteri. Il testo del documento e i contorni del logo hanno esigenze di modifica diverse; ricalcare uno screenshot delle scritte non identificherà il carattere originale.

Se un simbolo del marchio dipende da un effetto che questo importatore non può riprodurre, ricostruisci l'effetto come geometria adeguata oppure scegli un'altra procedura di esportazione e verificala. Anche l'inserimento raster è una scelta valida quando l'aspetto conta più della conservazione dei tracciati. Non descriverla come un'esportazione che conserva i vettori.

L'esempio usa colori RGB. La sola conservazione dei tracciati non dimostra che siano soddisfatti i requisiti di colore, PDF/X o prestampa di uno stampatore. Confermali con il destinatario; la guida ai formati dei loghi aiuta a distinguere un originale modificabile da un file da consegnare.

Recupera un logo solo raster prima dell'inserimento

Se il logo originale esiste soltanto come PNG o JPG, il vettorializzatore di loghi di PerfectVector può preparare un candidato SVG prima del passaggio PDFKit. Confronta contorni, piccole aperture e regioni di colore separate con il sorgente, poi sottoponi quel candidato agli stessi controlli di posizionamento e del PDF.

Usa il vettoriale originale ogni volta che è disponibile. Per scritte danneggiate o geometria esatta del marchio, riscrivi o ridisegna la parte interessata in un editor. La guida alla vettorializzazione dei loghi spiega questa decisione sul sorgente. PerfectVector prepara i tracciati grafici; PDFKit e il suo importatore gestiscono il posizionamento nel documento. L'emblema di prova di questo articolo è grafica vettoriale scritta a mano, non un risultato misurato di conversione.

FAQ

PDFKit può importare un SVG completo con doc.path()? No. Il metodo path legge dati di tracciato SVG. Usa SVG-to-PDFKit per il documento completo in questa procedura oppure disegna e applica gli stili a ogni forma da solo.

SVG-to-PDFKit garantisce un PDF senza immagini raster? No. L'emblema verificato, privo di immagini, ha prodotto operazioni di disegno e zero immagini nella pagina. Ispeziona il tuo input e il PDF esportato, soprattutto quando l'SVG contiene immagini incorporate o funzionalità esterne all'insieme supportato dall'importatore.

Perché il logo visibile è più piccolo dei valori width e height? Queste opzioni definiscono l'area di visualizzazione dell'importazione. Lo spazio vuoto nel viewBox sorgente rimane parte della disposizione, e l'adattamento delle proporzioni può lasciare spazio aggiuntivo. Controlla i limiti della grafica prima di cambiare le dimensioni richieste nel PDF.

Fonti

1. PDFKit — Grafica vettoriale — Documenta l'analisi dei dati dei tracciati SVG, le operazioni di riempimento e tratto e lo stato grafico.
2. SVG-to-PDFKit — Utilizzo e limiti — Definisce inserimento dell'SVG completo, opzioni dell'area di visualizzazione, avvisi, caratteri e funzionalità supportate.
3. PDFKit — Immagini — Elenca i formati bitmap accettati dall'API delle immagini.
4. PDFKit — Introduzione — Spiega flussi del documento, finalizzazione e dimensioni delle pagine in punti PDF.
5. PDFKit — Caratteri — Descrive l'incorporamento e la registrazione dei caratteri con nome.

Se il logo del documento parte da un'immagine raster, prepara un candidato SVG con PerfectVector, ispeziona aperture e contorni, poi inseriscilo alle dimensioni PDF richieste e controlla il file salvato.