HTML'i CSS ile biçimlendirme

Bir bakışta

Bu tarifte, Hypertext Markup Language (HTML) içeriğine Cascading Style Sheets (CSS) uygulanır. Satır içi style öznitelikleri ve bir <style> bloğu kullanılır. Ayrıca bir özelliğe güvenmeden önce desteğinin doğrulanmış olduğunu nasıl teyit edeceğinizi de öğrenirsiniz.

Kurulum

composer require nextpdf/core:^3

Bu sürüm kısıtını nextpdf/core paketi için kullanın. Örnek, PHP 8.4 üzerinde çalışır.

Kavramsal genel bakış

HTML motoru, stilleri CSS basamaklaması üzerinden çözümler. Birden çok kural aynı öğeyi hedeflediğinde hangi stilin geçerli olacağına basamaklama karar verir. Motor, önce giriş <style> bloğunu, ardından satır içi style özniteliklerini okur. İkisini de öğelerle eşleştirir ve sonucu basamaklama sırasına göre hesaplar. Destek matrisi, CSS Cascading and Inheritance modülünü Verified olarak derecelendirir; bu, basamaklama ve kalıtım davranışının özel bir fikstür paketi tarafından kapsandığı anlamına gelir.

Metin sunum özellikleri (örneğin text-align, text-indent ve letter-spacing), World Wide Web Consortium (W3C) CSS Text modülü özellik tablosunda tanımlanır (W3C CSS Text Level 3). Yazı tipi seçimi, CSS Fonts modeline dayanır. font kısaltması, font-style, font-variant, font-weight, font-size ve font-family özelliklerini birlikte ayarlar (W3C CSS Fonts Level 3).

Destek, W3C modülü temelinde izlenir ve doğruluk denetiminden geçirilir. Bir özellik uygulanmış olsa da ona özel bir modül fikstüründen yoksun olabilir; bu durumda “Verified” değil, “Claimed” olarak derecelendirilir. “Claimed” değerini azami çaba olarak değerlendirin ve görsel sonucu kendi içeriğiniz için doğrulayın. “Verified” değerini, başarılı bir fikstür paketiyle desteklenmiş olarak değerlendirin.

API yüzeyi

Biçimlendirmeyi, writeHtml(string $html): static metoduna ilettiğiniz HTML aracılığıyla denetlersiniz (NextPDF\Core\Concerns\HasTextOutput). CSS için ayrı bir application programming interface (API) sunulmaz; basamaklama dahili olarak çalışır. Tam PHPDoc tablosu, kaynaktan üretilir.

Kod örneği — hızlı başlangıç

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->addPage();

$doc->writeHtml(
    '<style>.lead { color: #1E3A8A; text-align: center; }</style>'
    . '<p class="lead">Styled with a style block.</p>'
);

$doc->save(__DIR__ . '/out.pdf');

Kod örneği — üretim

Bu bağımsız örnek, çalışma ortamında çalıştırılabilir. Bir <style> bloğunu, sınıf seçicilerini, satır içi stilleri ve font ailesi ile kalınlık yolunu sınar.

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('CSS Styling');
$doc->addPage();

$html = <<<'HTML'
<style>
    h1        { color: #1E3A8A; }
    .lead     { color: #D97706; font-size: 14px; }
    .callout  { background-color: #EFF6FF; padding: 8px; border: 1px solid #BFDBFE; }
    .centered { text-align: center; }
</style>

<h1>Styling HTML with CSS</h1>

<p class="lead">This paragraph is styled through a class selector in a
style block.</p>

<p class="callout">This paragraph has a background, padding, and a border
from a class selector.</p>

<p class="centered" style="font-weight: bold;">Centered, with an inline
override for weight.</p>

<p style="color: #6B7280; font-size: 9px;">Inline style only.</p>
HTML;

$doc->writeHtml($html);

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT');
$doc->save($out !== false ? $out : __DIR__ . '/style-with-css.pdf');

echo "Wrote style-with-css.pdf\n";

Beklenen standart çıktı (STDOUT):

Wrote style-with-css.pdf

Uç durumlar ve tuzaklar

Basamaklama sırası. Basamaklamada, eşit özgüllüğe sahip satır içi bir style, bir <style> bloğu seçicisine üstün gelir. Beklenmedik bir renk görürseniz, önce satır içi bir geçersiz kılma olup olmadığını denetleyin.
Claimed - Verified karşılaştırması. text-align, text-indent ve color, matriste “Claimed” olarak derecelendirilir. Bunlar uygulanmıştır, ancak özel modül fikstürleri yoktur. İşlenirler, ancak üretim onayından önce görsel çıktıyı doğrulamanız gerekir.
Saklanan ağaç yok. Architecture Decision Record (ADR-001)‘de açıklanan akış motoru hiçbir belge ağacı tutmaz; bu nedenle, sonraki bir kardeş öğenin önceki bir öğeyi yeniden biçimlendirdiği bir seçiciyi uygulayamaz. Sonuç olarak, sıradan bağımsız seçiciler kısıtlanmıştır.
Desteklenmeyen özellik. Desteklenmeyen bir özellik hata olarak bildirilmez; yok sayılır. Bu özelliğe güvenmeden önce matrisi denetleyin.
Renk uzayları. Lab, LCH ve OKLab değerleri ayrıştırılır, ancak bu işlevler için Portable Document Format (PDF)‘de renk uzayı sadakati iddia edilmez (matris: CSS Color 4 için “Claimed”).

Performans

Basamaklama çözümlemesi tek geçişte gerçekleşir. Maliyet, belirteç sayısına göre doğrusal kalır: O(n). Bütçe değeri wall_ms: 1500, peak_mb: 96 şeklindedir. Bir <style> bloğu, kural sayısıyla orantılı tek seferlik bir seçici ayrıştırma maliyeti ekler.

CSS destek matrisi alıntısı (yalnızca Verified satırları)

Bu alıntı, yalnızca Verified satırlarını, doğruluk denetiminden geçmiş CSS destek matrisinden gösterir.

W3C modülü	Düzey	Durum	Kanıt
CSS Cascading and Inheritance (`css_cascade_3`)	3	Verified	`src/Html/Cascade/`, `tests/Unit/Html/Cascade/`
CSS Cascading (`css_cascade_4`)	4	Verified	`Cascade/Layer/` + revert/layer testleri
CSS Cascading (`css_cascade_5`)	5	Verified	`AtRule/Layer/` + `Cascade/Layer/` paketleri
CSS Fonts (`css_fonts_3`)	3	Verified	`src/Html/Font/`, `tests/Unit/Font/` + FontResolver testleri
CSS Fonts (`css_fonts_4`)	4	Verified	`src/Html/FontFace/`, `tests/Unit/Html/FontFace/`

text-align, text-indent, color ve background-color, matriste “Claimed” değerindedir. Tablo, bunları Verified satırlarının dışında bilinçli olarak bırakır.

Tek geçişli akış kısıtlamaları (ADR-001)

Basamaklama, Document Object Model (DOM) bulunmayan, akışla aktarılan bir belirteç listesi üzerinde çalışır; bu nedenle seçiciler, belge sırası bağlamına göre çözümlenir. Tam ağaç seçici durumları ADR-006 uyarınca kısıtlanmıştır. Yalnızca belge sırasına ve üst öğe bağlamına dayanan CSS yazın.

Katman sözleşmeleri (ADR-010)

CSS ayrıştırma, basamaklama katmanına aittir ve yerleşim dağıtımı, ham $css[...] değerlerini doğrudan okumamalıdır. Genel yüzey HTML girişidir. Hesaplanmış stilleri basamaklamadan sonra enjekte etmenin desteklenen bir yolu yoktur.

Büyük belgeler için bellek bütçesi

Basamaklama, bir düğüm ağacını değil, etkin kural kümesini ve ekleme ile çıkarma stil yığınını tutar. Kapsayıcı kapsamındaki bağlamlar, ADR-020 bütçesine uyar (bağlam başına 5,000 düğüm, 50 MB etkin üst sınır). Büyük stil sayfaları, kural kümesi belleğini doğrusal olarak büyütür; bu nedenle seçici sayılarını sınırlı tutun.

Güvenlik notları

Güvenilmeyen HTML içindeki CSS kod çalıştıramaz, ancak yerleşimi ve background-image gibi kaynak referanslarını etkileyebilir. Varsayılan dış kaynak ilkesi, rastgele uzak URL’leri getirmez. Kullanıcı girişinden oluşturduğunuz tüm HTML ve CSS’yi işlemeden önce temizleyin.

Uygunluk

Beyan	Spesifikasyon	Madde	reference_id
Metin özellikleri (text-align, text-indent, letter-spacing), CSS Text özellik tablosunda tanımlanır.	W3C CSS Text Level 3	css_text_3#x1.x24
font kısaltması; font-style, font-variant, font-weight, font-size ve font-family özelliklerini ayarlar.	W3C CSS Fonts Level 3	css_fonts_3#x2.x6.x7.p2

Bu tarif, NextPDF’in desteklenen bir CSS alt kümesini nasıl uyguladığını gösterir; tam CSS desteği iddia etmez. Modül bazında doğrulanmış durum için CSS destek matrisine bakın.

Ticari bağlam

Uygulanamaz.