Gambar SVG WeasyPrint: Perbaiki Logo Hilang dalam PDF

WeasyPrint dapat menempatkan SVG dalam PDF melalui elemen image HTML. Jika logo hilang ketika Anda memberikan HTML sebagai string, periksa URL gambar terlebih dahulu: path relatif memerlukan base URL. Setelah file dimuat, tetapkan ukuran cetaknya melalui CSS dan periksa PDF yang disimpan. Referensi API WeasyPrint saat ini mendokumentasikan kebutuhan base_url ini.

Contoh di bawah mereproduksi kasus gambar hilang tersebut memakai logo asli berbentuk bingkai. Contoh ini juga memeriksa bahwa PDF yang diperbaiki berisi geometri gambar vektor pada ukuran yang diminta. Jika Anda sudah memiliki SVG, mulai dengan file tersebut. Vektorisasi hanya relevan dalam alur ini ketika karya sumber berupa piksel.

Reproduksi SVG yang hilang dengan dokumen kecil

Kami menguji dengan Python 3.13.9 dan WeasyPrint 70.0. Gunakan lingkungan proyek dan instal versi tetap:

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

WeasyPrint juga membutuhkan pustaka native, termasuk Pango. Ikuti petunjuk instalasi untuk sistem operasi Anda jika impor atau perintah versi gagal. Pustaka native yang hilang adalah masalah berbeda dari logo yang hilang.

Buat struktur folder ini:

example/
  render.py
  assets/
    logo.svg

Simpan karya demonstrasi asli ini sebagai assets/logo.svg. Bukaan di tengah memberikan bagian yang lebih berguna untuk diperiksa daripada persegi panjang solid. Ini adalah geometri yang dibuat manual, bukan hasil konversi 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>

Masukkan kode berikut ke 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")

Jalankan python render.py. Dalam PDF pertama kami, bingkai tidak ada dan teks alternatif gambar muncul. Log berisi:

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

PDF kedua menampilkan bingkai hijau kebiruan dengan bukaan tetap utuh. Kedua pemanggilan menghasilkan file, sehingga keberadaan PDF saja bukan pemeriksaan keberhasilan yang berguna.

Berikan folder awal yang tetap untuk path relatif

assets/logo.svg mengidentifikasi file relatif terhadap sesuatu yang lain. base_url pada pemanggilan kedua menyediakan lokasi awal itu. root.as_uri() membuat URI file absolut; garis miring penutup menjadikannya basis direktori. Logo tetap berada dalam folder assets yang sama dan isi SVG tidak berubah.

Memakai Path(__file__) juga menjaga contoh mengacu ke folder skrip ketika Anda menjalankannya dari direktori kerja lain. Dalam notebook, gunakan folder proyek eksplisit sebagai gantinya, karena __file__ biasanya tidak tersedia.

Ada pengujian kontrol lain yang berguna. Simpan HTML sebagai invoice.html di samping render.py dan muat file itu sendiri:

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

WeasyPrint dapat memperoleh basis dari nama file atau URL masukan. Pengujian berbasis file kami menghasilkan bingkai yang sama seperti kasus basis eksplisit. String HTML tidak memiliki nama file terkait untuk membuat inferensi tersebut. Mode masukan ini beserta aturan resolusi basisnya didokumentasikan dalam konstruktor HTML.

Untuk gambar yang dihosting di balik login, URL yang benar mungkin masih belum cukup. Dokumentasi URL fetcher menyatakan bahwa klien HTTP default tidak menyediakan cookie atau autentikasi. Gunakan pengaturan pengambilan sumber daya yang disetujui aplikasi Anda dan uji dalam lingkungan yang menghasilkan PDF. Jangan menganggap logo yang terlihat di browser saat Anda login dapat diakses oleh proses PDF.

Tetapkan ukuran gambar terpisah dari ukuran halaman PDF

Contoh memakai @page untuk lembar A4 dan margin, sedangkan .logo menetapkan lebar gambar 60 mm. Rasio sumber 2:1 membuat tingginya 30 mm dengan height: auto. Dalam PDF tersimpan kami, bingkai berukuran 60 × 30 mm dan dimulai 20 mm dari tepi atas serta kiri halaman.

Di sini gambar memenuhi seluruh viewBox. Logo Anda mungkin memiliki ruang kosong di dalam persegi panjang itu, sehingga kotak gambar 60 mm dapat berisi tanda yang tampak lebih sempit. Periksa kanvas SVG sebelum mengompensasi dengan lebar CSS lebih besar secara sembarang. Panduan ukuran impor SVG menjelaskan perbedaan ini lebih rinci.

Pertahankan write_pdf() pada default zoom=1 saat memeriksa dimensi fisik. Referensi keluaran PDF WeasyPrint memperingatkan bahwa mengubah zoom juga menskalakan satuan CSS fisik dan ukuran halaman bernama.

Periksa isi dan tampilan PDF

Dokumentasi format WeasyPrint saat ini menyatakan bahwa gambar SVG dirender sebagai vektor dalam keluaran PDF. Ini tidak berarti setiap file berakhiran .svg seluruhnya merupakan karya vektor: SVG dapat berisi bitmap tertanam. Periksa menggunakan diagnosis gambar tertanam ketika hasil masih terlihat berpiksel.

Untuk contoh sederhana ini, kami memeriksa PDF tersimpan dengan PyMuPDF 1.26.7:

Hasil ini berlaku untuk bingkai yang disediakan, bukan setiap fitur SVG. Satu path majemuk juga tidak berarti satu bentuk terlihat: subpath dalamnya menentukan bukaan.

Untuk memeriksa resolved.pdf Anda, instal pymupdf==1.26.7 dan jalankan:

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)

Referensi page PyMuPDF mendokumentasikan metode pemeriksaan gambar vektor dan image. Jumlah ini merupakan diagnostik, bukan sertifikat kesetiaan visual. Buka juga PDF-nya: periksa bukaan, warna, proporsi, dan tulisan pada ukuran penyerahan sebenarnya. Periksa karya kompleks fitur demi fitur dan jalankan ulang pemeriksaan ketika meningkatkan versi renderer.

Kapan perlu menyiapkan SVG baru terlebih dahulu

Ketika logo yang tersedia hanya PNG atau JPG, vektorisasi logo PerfectVector dapat menyiapkan kandidat SVG sebelum Anda menempatkannya dalam dokumen HTML. Periksa kontur, bukaan kecil, dan tulisan di editor, lalu uji SVG melalui pipeline WeasyPrint yang sama. Panduan vektorisasi gambar menjelaskan perubahan ketika piksel menjadi path.

Pertahankan SVG asli yang bisa diedit jika tersedia. Perbaiki referensi file atau tata letaknya alih-alih men-trace ulang. Foto dapat tetap berupa gambar raster, dan tulisan merek yang persis mungkin memerlukan font asli atau gambar ulang manual. Vektorisasi tidak memperbaiki file server yang hilang, autentikasi, atau fitur rendering yang tidak didukung.

Jika Anda hanya perlu mengonversi SVG menjadi halaman PDF tersendiri, alur ekspor CairoSVG membahas pekerjaan yang lebih kecil itu. WeasyPrint sesuai untuk kasus dokumen HTML, ketika karya berbagi halaman dengan konten lain.

FAQ

Mengapa WeasyPrint membuat PDF tanpa logo SVG saya? Kegagalan pemuatan gambar dapat membiarkan bagian dokumen lainnya tetap dapat dirender. Periksa log sumber daya dan URL gambar. Dalam pengujian yang disediakan, string HTML dengan path gambar relatif memerlukan base URL eksplisit.

Apakah saya perlu mengonversi SVG ke PNG terlebih dahulu? Tidak. WeasyPrint menerima gambar SVG. Pertahankan karya vektor yang didukung sebagai SVG ketika itulah keluaran yang diinginkan, dan periksa PDF tersimpan. Ekspor raster adalah alternatif ketika Anda sengaja mengutamakan tampilan daripada geometri vektor.

Apakah base_url mengubah ukuran cetak logo? Tidak. Atribut ini menyediakan basis untuk meresolusikan URL sumber daya relatif. Tetapkan ukuran penempatan gambar dengan CSS dan periksa dimensi serta viewBox SVG secara terpisah.

Sources

1. Referensi API WeasyPrint — Mendokumentasikan masukan HTML, base URL, keluaran SVG, dan perilaku zoom PDF.
2. WeasyPrint First Steps — Membahas instalasi dan pengambilan sumber daya, termasuk batasan autentikasi.
3. Referensi Page PyMuPDF — Mendokumentasikan metode pemeriksaan gambar vektor dan gambar tertanam yang digunakan dalam contoh.

Hanya punya logo raster? Siapkan SVG dengan PerfectVector, periksa bentuk dan tulisannya, lalu tempatkan dalam HTML Anda dan verifikasi tampilan serta ukuran fisiknya dalam PDF tersimpan.