WeasyPrint SVG: PDF'deki eksik logoları düzeltin

WeasyPrint, bir HTML görsel öğesi aracılığıyla PDF'ye SVG yerleştirebilir. HTML'yi bir dize olarak verdiğinizde logo kayboluyorsa önce görsel URL'sini kontrol edin: göreli bir yolun temel URL'ye ihtiyacı vardır. Dosya yüklendikten sonra baskı boyutunu CSS ile ayarlayın ve kaydedilen PDF'yi inceleyin. Güncel WeasyPrint API başvurusu, bu base_url gereksinimini açıklar.

Aşağıdaki örnek, özgün bir çerçeve biçimli logo ile bu eksik görsel durumunu yeniden oluşturur. Ayrıca düzeltilen PDF'nin istenen boyutta vektörel çizim geometrisi içerdiğini kontrol eder. Elinizde zaten bir SVG varsa o dosyayla başlayın. Vektörleştirme, yalnızca kaynak çizim piksel olarak mevcut olduğunda bu iş akışına girer.

Küçük bir belgeyle eksik SVG sorununu yeniden oluşturun

Python 3.13.9 ve WeasyPrint 70.0 ile test ettik. Bir proje ortamı kullanın ve sabitlenen sürümü yükleyin:

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

WeasyPrint, Pango dahil yerel sistem kütüphanelerine de ihtiyaç duyar. İçe aktarma veya sürüm komutu başarısız olursa işletim sistemine göre kurulum talimatlarını izleyin. Eksik bir yerel kütüphane, eksik logodan farklı bir sorundur.

Şu klasör yapısını oluşturun:

example/
  render.py
  assets/
    logo.svg

Bu özgün örnek çizimi assets/logo.svg olarak kaydedin. Ortadaki açıklık, incelemeniz için içi dolu bir dikdörtgenden daha yararlı bir ayrıntı sunar. Bu, elle yazılmış geometridir; PerfectVector dönüşümü değildir.

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

Aşağıdakileri render.py içine koyun:

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

python render.py komutunu çalıştırın. İlk PDF'mizde çerçeve yoktu ve görselin alternatif metni görünüyordu. Günlükte şu mesaj vardı:

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

İkinci PDF, mavi-yeşil çerçeveyi açıklığı korunmuş şekilde gösterdi. Her iki çağrı da bir dosya ürettiğinden, PDF'nin mevcut olması tek başına yararlı bir başarı kontrolü değildi.

Göreli yollara sabit bir başlangıç klasörü verin

assets/logo.svg, başka bir konuma göre bir dosyayı tanımlar. İkinci çağrıdaki base_url, bu başlangıç konumunu sağlar. root.as_uri() mutlak bir dosya URI'si oluşturur; sondaki eğik çizgi, bunun bir dizin temeli olduğunu belirtir. Logo aynı assets klasöründe kalır ve SVG içeriği değişmez.

Path(__file__) kullanmak, örneği başka bir çalışma dizininden başlattığınızda da betiğin klasörüne bağlı tutar. Bir notebook'ta bunun yerine açıkça belirtilmiş bir proje klasörü kullanın; çünkü __file__ normalde mevcut değildir.

Bir başka yararlı kontrol testi de vardır. HTML'yi render.py dosyasının yanına invoice.html olarak kaydedin ve doğrudan dosyayı yükleyin:

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

WeasyPrint, girdi dosya adından veya URL'sinden bir temel türetebilir. Dosya tabanlı testimiz, temelin açıkça verildiği durumla aynı çerçeveyi üretti. HTML dizesinin bu çıkarım için kullanılabilecek bir dosya adı yoktur. Bu girdi biçimleri ve temel çözümleme kuralları HTML oluşturucusunda açıklanır.

Oturum açmayı gerektiren bir yerde barındırılan görsel için doğru URL yine de yeterli olmayabilir. URL fetcher belgeleri, varsayılan HTTP istemcisinin çerez veya kimlik doğrulama sağlamadığını belirtir. Uygulamanızın onaylı kaynak alma düzenini kullanın ve PDF'yi üreten ortamda test edin. Oturum açtığınız tarayıcıda görünen bir logonun PDF süreci tarafından erişilebilir olduğunu varsaymayın.

Görsel boyutunu PDF sayfa boyutundan ayrı ayarlayın

Örnekte A4 sayfası ve kenar boşlukları için @page kullanılırken .logo, görsel genişliğini 60 mm olarak ayarlar. Kaynağın 2:1 oranı, height: auto ile yüksekliği 30 mm yapar. Kaydedilen PDF'mizde çerçeve 60 × 30 mm ölçüsündeydi ve sayfanın üst ve sol kenarlarından 20 mm uzakta başlıyordu.

Burada çizim, viewBox alanının tamamını doldurur. Logonuz bu dikdörtgenin içinde boş alan içerebilir; dolayısıyla 60 mm'lik bir görsel kutusunda gözle görülür biçimde daha dar bir işaret bulunabilir. Rastgele daha büyük bir CSS genişliğiyle telafi etmeden önce SVG tuvalini kontrol edin. SVG içe aktarma boyutu rehberi, bu ayrımı daha ayrıntılı açıklar.

Fiziksel ölçüleri kontrol ederken write_pdf() için varsayılan zoom=1 değerini koruyun. WeasyPrint'in PDF çıktı başvurusu, zoom değiştirildiğinde fiziksel CSS birimlerinin ve adlandırılmış sayfa boyutlarının da ölçeklendiğini belirtir.

PDF'nin içeriğini ve görünümünü inceleyin

Güncel WeasyPrint biçim belgeleri, SVG görsellerinin PDF çıktısında vektör olarak işlendiğini belirtir. Bu, .svg uzantılı her dosyanın tamamen vektörel çizim olduğu anlamına gelmez: SVG, gömülü bir raster görüntü içerebilir. Sonuç hâlâ pikselli görünüyorsa gömülü görsel teşhis rehberiyle bunu kontrol edin.

Bu basit test örneği için kaydedilen PDF'leri PyMuPDF 1.26.7 ile inceledik:

Bu sonuçlar, sunulan çerçeve için geçerlidir; her SVG özelliği için değil. Tek bir bileşik yol da tek bir görünür şekil anlamına gelmez: iç alt yolu açıklığı tanımlar.

resolved.pdf dosyanızı incelemek için pymupdf==1.26.7 paketini yükleyin ve şunu çalıştırın:

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)

PyMuPDF'nin page başvurusu, çizim ve görsel inceleme yöntemlerini açıklar. Bu sayılar teşhis içindir; aslına uygunluk sertifikası değildir. PDF'yi de açın: açıklığı, renkleri, oranları ve varsa yazıları gerçek teslim boyutunda kontrol edin. Karmaşık çizimleri özellik özellik inceleyin ve görüntü oluşturucuyu yükseltirken kontrolleri yeniden çalıştırın.

Önce ne zaman yeni bir SVG hazırlamalısınız?

Elinizdeki tek logo PNG veya JPG olduğunda, PerfectVector'ın logo vektörleştirme aracı, onu HTML belgesine yerleştirmeden önce bir SVG adayı hazırlayabilir. Konturları, küçük açıklıkları ve yazıları bir düzenleyicide inceleyin, ardından SVG'yi aynı WeasyPrint işleme hattında test edin. Görsel vektörleştirme rehberi, pikseller yollara dönüştüğünde nelerin değiştiğini açıklar.

Özgün, düzenlenebilir bir SVG varsa onu koruyun. Yeniden vektörleştirmek yerine dosya referansını veya yerleşimini düzeltin. Fotoğraflar raster görüntü olarak kalabilir; markanın yazılarını birebir korumak için özgün yazı tipi veya elle yeniden çizim gerekebilir. Vektörleştirme, eksik sunucu dosyalarını, kimlik doğrulamayı veya desteklenmeyen görüntü oluşturma özelliklerini düzeltmez.

Yalnızca bir SVG'yi kendi PDF sayfasına dönüştürmeniz gerekiyorsa CairoSVG dışa aktarma iş akışı, bu daha küçük işi ele alır. WeasyPrint, çizimin diğer içeriklerle aynı sayfayı paylaştığı HTML belgesi senaryosuna uygundur.

Sık sorulan sorular

WeasyPrint neden SVG logom olmadan PDF oluşturuyor? Bir görsel yükleme hatası, belgenin geri kalanının oluşturulmasını engellemeyebilir. Kaynak günlüğünü ve görsel URL'sini kontrol edin. Sunulan testte, göreli görsel yolu içeren HTML dizesi için açıkça bir temel URL verilmesi gerekiyordu.

Önce SVG'yi PNG'ye dönüştürmem gerekiyor mu? Hayır. WeasyPrint, SVG görsellerini kabul eder. Hedeflediğiniz çıktı buysa desteklenen vektörel çizimi SVG olarak koruyun ve kaydedilen PDF'yi kontrol edin. Vektör geometrisi yerine görünümü bilinçli olarak tercih ettiğinizde raster dışa aktarma bir alternatiftir.

base_url, logonun baskı boyutunu değiştirir mi? Hayır. Göreli kaynak URL'lerini çözümlemek için temel sağlar. Görselin yerleştirme boyutunu CSS ile ayarlayın; SVG'nin boyutlarını ve viewBox değerini ayrıca kontrol edin.

Kaynaklar

1. WeasyPrint API reference — HTML girdilerini, temel URL'leri, SVG çıktısını ve PDF yakınlaştırma davranışını açıklar.
2. WeasyPrint First Steps — Kimlik doğrulama sınırlamaları dahil kurulum ve kaynak almayı ele alır.
3. PyMuPDF Page reference — Örnekte kullanılan çizim ve gömülü görsel inceleme yöntemlerini açıklar.

Elinizde yalnızca raster logo mu var? PerfectVector ile bir SVG hazırlayın, şekillerini ve yazılarını inceleyin; ardından HTML'nize yerleştirin ve kaydedilen PDF'de görünümünü ve fiziksel boyutunu doğrulayın.