Loghi SVG in React-pdf: renderizzare tracciati nel PDF

Per un piccolo logo SVG in @react-pdf/renderer, costruisci la grafica con i suoi componenti Svg, Path e gli altri supportati. Assegna all'Svg esterno dimensioni esplicite e conserva il viewBox della sorgente. La documentazione di Image del renderer elenca ingressi PNG e JPG; racchiudere un URL SVG in Image non è il percorso vettoriale descritto qui.

Questa guida usa un esempio Node completo con un emblema quadrato e un'apertura al centro. Abbiamo renderizzato il PDF con dipendenze a versione fissata ed esaminato il risultato. L'esempio isola tre aspetti facili da confondere: la grafica sorgente, l'albero dei componenti e le dimensioni di inserimento nel PDF.

Controlla quale pacchetto React PDF stai usando

Questo articolo genera documenti con @react-pdf/renderer. Il pacchetto separato chiamato react-pdf visualizza PDF esistenti. Controlla l'importazione nel tuo file prima di copiare una soluzione da un risultato di ricerca.

All'interno di un Document del renderer, usa componenti esportati da quel renderer. Gli elementi minuscoli svg e path del browser appartengono a un altro ambiente di rendering. La documentazione ufficiale del componente SVG definisce Svg come contenitore del viewport e mostra al suo interno forme React-pdf importate.

La documentazione di Image descrive gli ingressi bitmap. Un ripiego PNG può essere utile quando un aspetto complesso conta più della conservazione della geometria vettoriale. Cambia il file consegnato, quindi conserva separatamente l'originale vettoriale.

Esiste anche un pacchetto ufficiale @react-pdf/svg. Il suo README documenta parseSvg(), che restituisce un albero di nodi primitivi e converte i nomi degli attributi in camelCase. Dice che gli elementi non supportati vengono saltati con un avviso. È il contratto di un parser, non la promessa che ogni SVG del browser venga renderizzato in modo identico. L'esempio qui sotto usa componenti espliciti per mantenere geometria e aspetto facili da esaminare.

Renderizza un logo minimo prima di importare il tuo

Abbiamo eseguito questo esempio con @react-pdf/renderer 4.9.0, React 19.2.4 e Node 22.19.0. Queste versioni identificano la configurazione testata; non garantiscono il comportamento di un diverso albero di dipendenze.

In una nuova directory, installa i due pacchetti di esecuzione:

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

Salva questo codice come logo.mjs, poi esegui node logo.mjs. Usa React.createElement così Node può eseguirlo senza un passaggio di compilazione 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)),
);

I quadrati esterno e interno condividono un unico tracciato composto. fillRule: 'evenodd' lascia aperto il quadrato interno, mostrando il rettangolo chiaro sottostante. Nessuna zona bianca copre il centro. Questo rende l'apertura un controllo utile quando sostituisci il campione con un logo contenente spazi interni o ritagli.

Le coordinate SVG coprono 100 unità in ciascuna direzione, mentre il viewport inserito misura 144 per 144. viewBox descrive il sistema di coordinate del disegno; width e height descrivono il viewport visualizzato. Mantieni questa distinzione quando regoli le dimensioni di un logo. La tabella ufficiale delle proprietà Svg documenta questi controlli e preserveAspectRatio.

Esamina il PDF salvato oltre alla sua anteprima

Il nostro test ha prodotto una pagina A4 con l'anello quadrato verde petrolio vicino all'angolo superiore sinistro. Abbiamo renderizzato quel file con Poppler e controllato visivamente che lo sfondo chiaro fosse visibile attraverso l'apertura. pdfimages -list logo.pdf di Poppler non ha segnalato immagini incorporate in questo documento isolato.

Quel risultato è volutamente circoscritto. Descrive questo campione composto soltanto da tracciati. Non dimostra che un documento con fotografie, immagini SVG incorporate o effetti non supportati sia interamente vettoriale.

Se Poppler è disponibile sul tuo computer, questi comandi offrono due controlli diversi:

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

Il secondo comando crea un'anteprima raster per l'ispezione visiva; non trasforma il PDF originale in una bitmap. Controlla apertura, angoli, colori e posizione in quell'anteprima, poi apri il PDF salvato nel visualizzatore usato dal destinatario. Un'anteprima dall'aspetto nitido da sola non dimostra che il documento originale contenga tracciati: anche una bitmap grande può apparire nitida.

Per un'ispezione più approfondita, esamina le istruzioni di disegno del PDF e gli oggetti referenziati intorno al logo. I report complessi possono contenere oggetti annidati, quindi parti da un documento con il solo logo prima di diagnosticare l'intero report. La guida SVG per PDFKit spiega un diverso procedimento di importazione SVG e i relativi controlli del PDF salvato.

Trasferisci la grafica una funzionalità alla volta

Sostituisci il valore d del campione con i tuoi dati di tracciato, poi conserva riempimento, regola di riempimento, contorno e trasformazione associati. Copiare soltanto la forma di un tracciato eliminandone l'aspetto può cambiare il risultato anche quando i dati del tracciato sono validi.

Per un piccolo marchio statico, imposta i colori direttamente sulle forme supportate. Un logo che dipende dal foglio di stile di una pagina web richiede che quelle dipendenze siano risolte prima di diventare un componente di documento autonomo. Tieni l'SVG sorgente accanto al codice di rendering, così le revisioni successive possono essere confrontate con la grafica approvata.

La panoramica SVG ufficiale elenca le primitive disponibili. Considerala una lista di supporto da verificare, non l'insieme completo delle funzioni SVG del browser. Testa scritte, ritaglio e gradienti nella versione installata prima di aggiungerli al report di produzione.

Se l'SVG contiene un PNG incorporato, convertire il suo contenitore non ricostruisce la geometria mancante. La guida al raster incorporato mostra come distinguere i tracciati da una bitmap memorizzata dentro un file SVG.

Quando il logo parte da un PNG o JPG

Se esiste un originale SVG, AI o un altro originale vettoriale modificabile, richiedilo prima. Se restano soltanto pixel, il vettorializzatore di loghi di PerfectVector può preparare un candidato SVG prima del lavoro in React-pdf. Confronta contorni, piccole aperture e aree di colore separate con la sorgente prima di adattare le forme supportate al tuo componente PDF.

La vettorializzazione non corregge l'integrazione del renderer, non crea un componente React e non garantisce supporto per ogni funzione SVG. Mantieni sotto controllo manuale le scritte che richiedono geometria esatta del marchio. La guida alla vettorializzazione dei loghi aiuta a scegliere tra ricalco, riscrittura del testo e ridisegno.

Per una sorgente soltanto raster, il risultato utile è un candidato vettoriale esaminato seguito da un PDF verificato. Per una sorgente vettoriale esistente, passa direttamente ai controlli dei componenti e delle dimensioni di inserimento. Altre indicazioni sulla preparazione della sorgente sono disponibili nel blog.

FAQ

Posso passare un file SVG a Image di React-pdf? Gli ingressi documentati di Image sono PNG e JPG. Usa le primitive Svg del renderer per il procedimento basato su tracciati di questa guida e controlla la versione installata prima di dipendere da altri comportamenti di ingresso.

Devo tradurre ogni SVG a mano? No. Il pacchetto ufficiale @react-pdf/svg analizza stringhe SVG in alberi di nodi primitivi. Esamina gli elementi supportati e gli avvisi, poi collega e testa quell'output nel tuo procedimento di rendering. L'esempio con componenti espliciti qui presente evita un passaggio aggiuntivo di parsing.

Perché il centro del mio logo si riempie? Controlla il tracciato composto e la sua regola di riempimento. L'emblema di test usa evenodd così il suo quadrato interno resta aperto. Conserva geometria e regole di disegno originali prima di cambiare la grafica.

Un'anteprima PDF nitida dimostra che il logo è vettoriale? No. Esamina contenuto e oggetti immagine del PDF salvato oltre al suo aspetto. Il campione isolato di questa guida non aveva immagini incorporate; quel risultato non si applica automaticamente a un altro logo.

Fonti

1. React-pdf — Componente Svg — Definisce viewport, dimensioni, viewBox e controlli delle proporzioni.
2. React-pdf — Componente Image — Documenta le forme di ingresso PNG e JPG per l'inserimento di bitmap.
3. React-pdf — Primitive SVG — Elenca i componenti SVG supportati dal renderer.
4. React-pdf — Parser SVG — Documenta l'albero di nodi primitivi, la conversione degli attributi e gli avvisi per elementi non supportati.

Hai soltanto un logo PNG o JPG? Prepara un candidato SVG con PerfectVector, confronta contorni e aperture con la sorgente, poi adatta le forme supportate ed esamina il PDF salvato.