Menata HTML dengan CSS

Sekilas

Resep ini menunjukkan cara menerapkan Cascading Style Sheets (CSS) pada konten Hypertext Markup Language (HTML). Resep ini menggunakan atribut style inline dan sebuah blok <style>. Anda juga akan mempelajari cara memastikan suatu properti sudah terverifikasi sebelum mengandalkannya.

Pemasangan

composer require nextpdf/core:^3

Gunakan batasan versi ini untuk paket nextpdf/core. Contoh ini berjalan pada PHP 8.4.

Tinjauan konseptual

Mesin HTML menentukan gaya akhir melalui cascade CSS. Cascade menentukan gaya mana yang menang ketika beberapa aturan menargetkan elemen yang sama. Mesin lebih dahulu membaca blok <style> dari masukan, lalu atribut style inline. Mesin mencocokkan keduanya dengan elemen dan menghitung hasil akhirnya sesuai urutan cascade. Matriks dukungan memberi status Verified pada modul CSS Cascading and Inheritance, yang berarti rangkaian fixture khusus mencakup perilaku cascade dan pewarisan.

Properti penyajian teks seperti text-align, text-indent, dan letter-spacing didefinisikan dalam tabel properti modul CSS Text dari World Wide Web Consortium (W3C) (W3C CSS Text Level 3). Pemilihan fon menggunakan model CSS Fonts. Singkatan font menetapkan font-style, font-variant, font-weight, font-size, dan font-family secara bersamaan (W3C CSS Fonts Level 3).

Dukungan dilacak per modul W3C dan diaudit untuk kebenarannya. Suatu properti bisa saja sudah diimplementasikan, tetapi tetap belum memiliki fixture modul khusus; dalam kondisi itu, properti tersebut dinilai “Claimed”, bukan “Verified”. Perlakukan “Claimed” sebagai upaya terbaik, dan validasi hasil visualnya untuk konten Anda. Perlakukan “Verified” sebagai dukungan yang dibuktikan oleh rangkaian fixture yang lolos.

Permukaan API

Anda mengendalikan penataan melalui HTML yang Anda berikan ke writeHtml(string $html): static (NextPDF\Core\Concerns\HasTextOutput). Tidak ada API terpisah untuk CSS; cascade berjalan secara internal. Tabel PHPDoc lengkap dihasilkan dari kode sumber.

Contoh kode — Mulai cepat

<?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');

Contoh kode — Produksi

Contoh mandiri ini dapat dijalankan di dalam harness. Contoh ini mencakup sebuah blok <style>, selektor kelas, gaya inline, serta jalur pemrosesan keluarga dan ketebalan font.

<?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";

Keluaran standar (STDOUT) yang diharapkan:

Wrote style-with-css.pdf

Kasus khusus & jebakan

Urutan cascade. Dalam cascade, atribut style inline menang atas selektor blok <style> dengan spesifisitas yang sama. Jika Anda melihat warna yang tidak terduga, periksa terlebih dahulu apakah ada penggantian inline.
Claimed vs Verified. text-align, text-indent, dan color dinilai “Claimed” dalam matriks. Properti-properti tersebut sudah diimplementasikan, tetapi tidak memiliki fixture modul khusus. Properti ini dirender, tetapi Anda sebaiknya memvalidasi keluaran visualnya sebelum persetujuan akhir produksi.
Tanpa pohon yang dipertahankan. Mesin streaming, yang dijelaskan dalam Architecture Decision Record (ADR-001), tidak menyimpan pohon dokumen, sehingga tidak dapat menerapkan selektor ketika saudara yang muncul belakangan menata ulang elemen sebelumnya. Akibatnya, selektor yang bergantung pada elemen yang muncul belakangan menjadi terbatas.
Properti yang tidak didukung. Properti yang tidak didukung akan diabaikan, bukan menghasilkan kesalahan. Periksa matriks sebelum Anda mengandalkannya.
Ruang warna. Nilai Lab, LCH, dan OKLab dapat di-parse, tetapi ketepatan ruang warna Portable Document Format (PDF) untuk fungsi-fungsi tersebut tidak dijamin (matriks: “Claimed” untuk CSS Color 4).

Kinerja

Penyelesaian cascade terjadi dalam satu lintasan. Biayanya tetap linear terhadap jumlah token, O(n). Anggarannya adalah wall_ms: 1500, peak_mb: 96. Sebuah blok <style> menambahkan biaya parse selektor satu kali yang sebanding dengan jumlah aturan.

Kutipan matriks dukungan CSS (hanya baris yang Verified)

Kutipan ini hanya menampilkan baris Verified dari matriks dukungan CSS yang telah diaudit kebenarannya.

Modul W3C	Level	Status	Bukti
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/` + uji revert/layer
CSS Cascading (`css_cascade_5`)	5	Verified	Rangkaian `AtRule/Layer/` + `Cascade/Layer/`
CSS Fonts (`css_fonts_3`)	3	Verified	`src/Html/Font/`, `tests/Unit/Font/` + uji FontResolver
CSS Fonts (`css_fonts_4`)	4	Verified	`src/Html/FontFace/`, `tests/Unit/Html/FontFace/`

text-align, text-indent, color, dan background-color dinilai “Claimed” dalam matriks. Tabel ini sengaja tidak memasukkannya ke baris berstatus Verified.

Batasan streaming satu lintasan (ADR-001)

Cascade berjalan di atas daftar token yang di-stream tanpa Document Object Model (DOM), sehingga selektor diselesaikan berdasarkan konteks urutan dokumen. Kasus selektor pohon penuh dibatasi sesuai ADR-006. Tulis CSS yang hanya bergantung pada urutan dokumen dan konteks leluhur.

Kontrak lapisan (ADR-010)

Parsing CSS termasuk dalam lapisan cascade, dan dispatch tata letak tidak boleh membaca nilai $css[...] mentah secara langsung. Permukaan publiknya adalah masukan HTML. Tidak ada cara yang didukung untuk menyuntikkan gaya terkomputasi dengan melewati cascade.

Anggaran memori untuk dokumen besar

Cascade menyimpan kumpulan aturan aktif serta tumpukan gaya push dan pop, bukan pohon node. Konteks yang berlingkup kontainer mematuhi anggaran ADR-020 (5,000 node per konteks, batas atas aktif 50 MB). Stylesheet besar membuat penggunaan memori kumpulan aturan bertambah secara linear, jadi batasi jumlah selektor.

Catatan keamanan

CSS dalam HTML yang tidak tepercaya tidak dapat menjalankan kode, tetapi dapat memengaruhi tata letak dan rujukan sumber daya, seperti background-image. Kebijakan sumber daya eksternal bawaan tidak mengambil URL jarak jauh secara sembarangan. Bersihkan setiap HTML dan CSS yang Anda susun dari masukan pengguna sebelum merendernya.

Kesesuaian

Pernyataan	Spec	Klausa	reference_id
Properti teks (text-align, text-indent, letter-spacing) didefinisikan oleh tabel properti CSS Text.	W3C CSS Text Level 3	css_text_3#x1.x24
Singkatan font menetapkan font-style, font-variant, font-weight, font-size, dan font-family.	W3C CSS Fonts Level 3	css_fonts_3#x2.x6.x7.p2

Resep ini menunjukkan cara NextPDF menerapkan subset CSS yang didukung; resep ini tidak menjamin dukungan CSS penuh. Untuk status terverifikasi per modul, lihat matriks dukungan CSS.

Konteks komersial

Tidak berlaku.