SVG in WeasyPrint: correggere i loghi assenti nei PDF

WeasyPrint può inserire un SVG in un PDF attraverso un elemento immagine HTML. Se il logo scompare quando passi l'HTML come stringa, controlla prima l'URL dell'immagine: un percorso relativo richiede un URL base. Una volta caricato il file, imposta le dimensioni di stampa in CSS ed esamina il PDF salvato. L'attuale documentazione API di WeasyPrint documenta questo requisito di base_url.

L'esempio qui sotto riproduce il caso dell'immagine assente con un logo originale a forma di cornice. Verifica anche che il PDF corretto contenga geometria vettoriale alle dimensioni richieste. Se hai già un SVG, parti da quel file. La vettorializzazione entra in questo procedimento soltanto quando la grafica sorgente esiste come pixel.

Riproduci l'SVG assente con un piccolo documento

Abbiamo testato con Python 3.13.9 e WeasyPrint 70.0. Usa un ambiente di progetto e installa la versione fissata:

python -m pip install "weasyprint==70.0"
python -m weasyprint --info

WeasyPrint richiede anche librerie native, tra cui Pango. Segui le sue istruzioni di installazione per sistema operativo se l'importazione o il comando della versione non riesce. Una libreria nativa assente è un problema diverso da un logo assente.

Crea questa struttura di cartelle:

example/
  render.py
  assets/
    logo.svg

Salva questa grafica dimostrativa originale come assets/logo.svg. L'apertura centrale offre qualcosa di più utile da esaminare rispetto a un rettangolo pieno. È geometria scritta a mano, non una conversione PerfectVector.

<svg xmlns="http://www.w3.org/2000/svg"
     width="120" height="60" viewBox="0 0 120 60">
  <path fill="#087f8c" fill-rule="evenodd"
        d="M0 0H120V60H0Z M20 15V45H100V15Z"/>
</svg>

Inserisci quanto segue in render.py:

from pathlib import Path
import logging
from weasyprint import HTML
 
logging.basicConfig(level=logging.WARNING)
root = Path(__file__).resolve().parent
 
html = """<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <style>
    @page { size: A4; margin: 20mm; }
    body { margin: 0; }
    .logo { display: block; width: 60mm; height: auto; }
  </style>
</head>
<body>
  <img class="logo" src="assets/logo.svg" alt="Frame logo">
</body>
</html>
"""
 
HTML(string=html).write_pdf(root / "missing-base.pdf")
 
HTML(
    string=html,
    base_url=root.as_uri() + "/",
).write_pdf(root / "resolved.pdf")

Esegui python render.py. Nel nostro primo PDF la cornice era assente e compariva il testo alternativo dell'immagine. Il log conteneva:

Relative URI reference without a base URI: assets/logo.svg

Il secondo PDF mostrava la cornice verde petrolio con l'apertura intatta. Entrambe le chiamate hanno prodotto un file, quindi l'esistenza di un PDF da sola non era un controllo utile della riuscita.

Dai ai percorsi relativi una cartella iniziale stabile

assets/logo.svg identifica un file rispetto a qualcos'altro. Il base_url nella seconda chiamata fornisce quel punto di partenza. root.as_uri() crea un URI file assoluto; la barra finale lo rende una base di directory. Il logo resta nella stessa cartella assets e il contenuto SVG non cambia.

L'uso di Path(__file__) mantiene inoltre l'esempio legato alla cartella dello script quando lo avvii da un'altra directory di lavoro. In un notebook usa invece una cartella di progetto esplicita, perché __file__ normalmente non è disponibile.

Esiste un altro test di controllo utile. Salva l'HTML come invoice.html accanto a render.py e carica direttamente il file:

HTML(filename=str(root / "invoice.html")).write_pdf(
    root / "from-file.pdf"
)

WeasyPrint può ricavare una base dal nome o dall'URL del file in ingresso. Il nostro test basato su file ha prodotto la stessa cornice del caso con base esplicita. Una stringa HTML non ha un nome di file corrispondente da cui dedurla. Queste modalità di ingresso e le loro regole di risoluzione della base sono documentate nel costruttore HTML.

Per un'immagine protetta da autenticazione, un URL corretto può comunque non bastare. La documentazione del recupero degli URL dice che il client HTTP predefinito non fornisce cookie né autenticazione. Usa il sistema di recupero delle risorse approvato dalla tua applicazione e testalo nell'ambiente che genera il PDF. Non supporre che un logo visibile nel browser con accesso effettuato sia accessibile al processo PDF.

Imposta separatamente dimensioni dell'immagine e della pagina PDF

L'esempio usa @page per il foglio A4 e i margini, mentre .logo imposta l'immagine a 60 mm di larghezza. Le proporzioni sorgente 2:1 la rendono alta 30 mm con height: auto. Nel PDF salvato la cornice misurava 60 × 30 mm e iniziava a 20 mm dai bordi superiore e sinistro della pagina.

Qui il disegno occupa tutto il viewBox. Il tuo logo può avere spazio vuoto all'interno di quel rettangolo, quindi un riquadro immagine di 60 mm può contenere un marchio visibilmente più stretto. Controlla la tela SVG prima di compensare con una larghezza CSS arbitrariamente maggiore. La guida alle dimensioni di importazione SVG spiega questa distinzione più nel dettaglio.

Mantieni write_pdf() al valore predefinito zoom=1 quando controlli le dimensioni fisiche. La documentazione sull'uscita PDF di WeasyPrint avverte che cambiare zoom ridimensiona anche le unità CSS fisiche e i formati pagina con nome.

Esamina contenuto e aspetto del PDF

L'attuale documentazione dei formati WeasyPrint dice che le immagini SVG vengono renderizzate come vettori nell'uscita PDF. Questo non significa che ogni file con estensione .svg sia interamente vettoriale: un SVG può contenere una bitmap incorporata. Controllalo con la diagnosi delle immagini incorporate quando il risultato appare ancora pixelato.

Per questo semplice campione abbiamo esaminato i PDF salvati con PyMuPDF 1.26.7:

Questi risultati riguardano la cornice fornita, non ogni funzione SVG. Un solo tracciato composto non significa neppure una sola forma visibile: il suo sottotracciato interno definisce l'apertura.

Per esaminare il tuo resolved.pdf, installa pymupdf==1.26.7 ed esegui:

import pymupdf
 
with pymupdf.open("resolved.pdf") as document:
    page = document[0]
    print("Drawing records:", len(page.get_drawings()))
    print("Embedded images:", len(page.get_images()))
    for drawing in page.get_drawings():
        box = drawing["rect"]
        print("Bounds in mm:", box.width * 25.4 / 72,
              box.height * 25.4 / 72)

La documentazione della pagina di PyMuPDF descrive i metodi di ispezione di disegni e immagini. Questi conteggi sono strumenti diagnostici, non una certificazione di fedeltà. Apri anche il PDF: controlla l'apertura, i colori, le proporzioni e le eventuali scritte alle dimensioni effettive di consegna. Esamina la grafica complessa funzione per funzione e ripeti i controlli quando aggiorni il renderer.

Quando preparare prima un nuovo SVG

Quando l'unico logo disponibile è un PNG o JPG, il vettorializzatore di loghi di PerfectVector può preparare un candidato SVG prima dell'inserimento nel documento HTML. Esamina contorni, piccole aperture e scritte in un editor, poi testa l'SVG attraverso lo stesso processo WeasyPrint. La guida alla vettorializzazione delle immagini spiega cosa cambia quando i pixel diventano tracciati.

Conserva un SVG originale modificabile quando esiste. Correggine il riferimento al file o l'impaginazione anziché ricalcarlo di nuovo. Le fotografie possono restare immagini raster e le scritte esatte di un marchio possono richiedere il font originale o un ridisegno manuale. La vettorializzazione non corregge file assenti sul server, autenticazione o funzioni di rendering non supportate.

Se devi soltanto convertire un SVG nella propria pagina PDF, il procedimento di esportazione CairoSVG descrive quel lavoro più circoscritto. WeasyPrint è adatto al documento HTML, in cui la grafica condivide la pagina con altri contenuti.

FAQ

Perché WeasyPrint crea un PDF senza il mio logo SVG? Un errore di caricamento dell'immagine può lasciare renderizzabile il resto del documento. Controlla il log delle risorse e l'URL dell'immagine. Nel test fornito, una stringa HTML con un percorso immagine relativo richiedeva un URL base esplicito.

Devo prima convertire l'SVG in PNG? No. WeasyPrint accetta immagini SVG. Mantieni come SVG la grafica vettoriale supportata quando è l'uscita desiderata e controlla il PDF salvato. Un'esportazione raster è un'alternativa quando scegli deliberatamente l'aspetto rispetto alla geometria vettoriale.

base_url cambia le dimensioni di stampa del logo? No. Fornisce la base per risolvere gli URL relativi delle risorse. Imposta le dimensioni di inserimento dell'immagine con CSS e controlla separatamente dimensioni e viewBox dell'SVG.

Fonti

1. Documentazione API di WeasyPrint — Documenta ingressi HTML, URL base, uscita SVG e comportamento dello zoom PDF.
2. Primi passi con WeasyPrint — Descrive installazione e recupero delle risorse, compresi i limiti di autenticazione.
3. Documentazione Page di PyMuPDF — Documenta i metodi di ispezione di disegni e immagini incorporate usati nell'esempio.

Hai soltanto un logo raster? Prepara un SVG con PerfectVector, esamina forme e scritte, poi inseriscilo nell'HTML e verifica aspetto e dimensioni fisiche nel PDF salvato.