HTML tablosu yerleşimi

Bir bakışta

Başlıklar, hizalanmış hücreler, kenarlıklar ve bir alt bilgi satırı içeren bir Hypertext Markup Language (HTML) tablosu oluşturmak için bu tarifi kullanın. Cascading Style Sheets (CSS) destek matrisinde Table modülü Verified durumundadır. Bu tarif examples/09-html-table.php dosyasındaki örneği izler.

Kurulum

composer require nextpdf/core:^3

Bu komut nextpdf/core paketini kurar. Örnek, PHP 8.4 üzerinde çalışır.

Kavramsal genel bakış

HTML motoru, özel bir tablo iş hattı kullanır (src/Html/Table/). TableParser, satırları ve hücreleri kısa ömürlü bir arabellekte toplar; ardından NextPDF tabloyu yerleştirip boyar. Bu, ADR-001’deki saklanmayan Document Object Model (DOM) modelinden kabul edilmiş tek sapmadır. Arabellek kısa ömürlüdür ve kapsamı kendi kapsayıcısıyla sınırlıdır. Kalıcı bir DOM değildir.

Sütun genişlikleri, CSS Table modelini izler. NextPDF, tabloyu belirli bir kullanılan genişlikte yerleştirir; ardından sütun boyutlandırma algoritması her sütunun kullanılan genişliğini belirler (W3C CSS Table Level 3). table-layout: fixed ile, genişlik hesaplaması için hücre içeriği yok sayılır. Bunun yerine yerleşimi ilk satır ve açıkça belirtilen sütun genişlikleri belirler (W3C CSS Table Level 3).

CSS Table Level 3, matriste Verified olarak derecelendirilmiştir. Bu derecelendirmeyi dört kaynak destekler: src/Html/Table/, Table birim test paketi, TableParser testleri ve sentetik altın PDF’ler.

API yüzeyi

Tabloları writeHtml(string $html): static ile oluşturun (NextPDF\Core\Concerns\HasTextOutput). Motor, standart tablo işaretlemesini destekler. Desteklenen etiketler şunlardır: table, thead, tbody, tfoot, tr, th ve td. Desteklenen öznitelikler şunlardır: border, cellpadding, cellspacing, colspan ve hücre başına bir style. PHPDoc tablosunun tamamı 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(
    '<table border="1" cellpadding="5"><tr><th>SKU</th><th>Qty</th></tr>'
    . '<tr><td>NPD-CORE</td><td style="text-align: right;">1</td></tr></table>'
);

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

Kod örneği — üretim

Bu bağımsız örnek, test koşumunda çalıştırılabilir. examples/09-html-table.php dosyasını yansıtır; biçimlendirilmiş bir başlığı, dönüşümlü satır arka planlarını, hizalanmış sayısal sütunları ve bir alt bilgi toplamını gösterir.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('HTML Table');
$doc->addPage();

$html = <<<'HTML'
<h1 style="color: #1E3A8A;">Product Inventory Report</h1>

<table border="1" cellpadding="5" cellspacing="0" style="width: 100%;">
    <thead>
        <tr style="background-color: #1E3A8A; color: #FFFFFF;">
            <th style="width: 10%;">#</th>
            <th style="width: 45%;">Product</th>
            <th style="width: 20%; text-align: center;">SKU</th>
            <th style="width: 25%; text-align: right;">Price</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>1</td>
            <td>NextPDF Core License</td>
            <td style="text-align: center;">NPD-CORE</td>
            <td style="text-align: right;">$0.00</td>
        </tr>
        <tr style="background-color: #F8FAFC;">
            <td>2</td>
            <td>NextPDF Pro License</td>
            <td style="text-align: center;">NPD-PRO</td>
            <td style="text-align: right;">$299.00</td>
        </tr>
    </tbody>
    <tfoot>
        <tr style="background-color: #1E293B; color: #FFFFFF; font-weight: bold;">
            <td colspan="3" style="text-align: right;">Grand total:</td>
            <td style="text-align: right;">$299.00</td>
        </tr>
    </tfoot>
</table>
HTML;

$doc->writeHtml($html);

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT');
$doc->save($out !== false ? $out : __DIR__ . '/html-table-layout.pdf');

echo "Wrote html-table-layout.pdf\n";

Beklenen standart çıktı (STDOUT):

Wrote html-table-layout.pdf

Uç durumlar ve dikkat edilecek noktalar

Yüzde genişlikleri. Sütun width yüzdeleri, kullanılan tablo genişliğine göre çözümlenir. Sütun boyutlandırma algoritması, toplamı 100 etmeyen yüzdeleri normalleştirir. Kesin piksel genişlikleri varsaymayın.
colspan. Birden çok sütuna yayılan bir hücre, kapsadığı sütunlar arasında genişlik dağıtımına katılır. Çoğu sütuna yayılan bir alt bilgi toplamı, yaygın ve desteklenen bir kalıptır.
Kenarlık modeli. Bazı tablo fikstürlerinde, border-collapse varsayılan değeri CSS’in başlangıç değerinden farklıdır. Kenarlık işleme önemliyse bunu doğrudan ayarlayın.
Sayfa sonları boyunca rowspan. Birden çok satıra yayılan bir hücre, bir sayfa sınırını aşabilir ve rowspan sayfalayıcı bu durumda o hücreyi parçalara böler (ADR-007). Bölünemeyen çok uzun bir hücre, UnsplittableContentException oluşturabilir.
Boş hücreler. Boş bir <td> yine de ızgara yuvasını kaplar. Daraltılarak kaldırılmaz.

Performans

Tablo arabelleği kısa ömürlüdür ve kapsamı kendi kapsayıcısıyla sınırlıdır. Ayrıştırma maliyeti hücre sayısına göre doğrusaldır; buna ek olarak O(rows x cols) düzeyindeki sütun boyutlandırma geçişi gelir. Bütçe değeri wall_ms: 1500, peak_mb: 96 olarak tanımlıdır. Tek bir tabloyu, bağlam başına 5,000 düğüm olan ADR-020 düğüm sınırı içinde tutun.

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

Bu alıntı yalnızca Verified satırları içerir; bunlar doğruluğu denetlenmiş CSS destek matrisi kaynağından alınmıştır.

W3C modülü	Düzey	Durum	Kanıt
CSS Table (`css_tables_3`)	3	Verified	`src/Html/Table/`, `tests/Unit/Html/Table/` + TableParser testleri + altın PDF’ler
CSS Flexible Box Layout (`css_flexbox_1`)	1	Verified	`src/Html/Flex/`, `tests/Unit/Html/Flex/`
CSS Grid Layout (`css_grid_1`)	1	Verified	`src/Html/Grid/`, WPT derlemi
CSS Cascading and Inheritance (`css_cascade_3`)	3	Verified	`src/Html/Cascade/`

background-color, burada satırları şeritlendirmek için kullanılır ve matriste “Claimed” olarak derecelendirilmiştir. Phase 0 denetimine göre kapsamı tablo hücresidir. Tablo satırlarında işlenir, ancak Verified olarak listelenmez.

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

Tablo arabelleği, akış modeline belgelenmiş istisnadır. Kısa ömürlüdür ve sınırlıdır; genel bir DOM değildir. Tablonun, kendi dışındaki içerik için ağaç bağlamı sağlayacağına güvenmeyin.

Katman sözleşmeleri (ADR-010)

FormattingContextFactory::startTable(), CSS’i yerleşim katmanının sözleşmesi aracılığıyla okur. Gönderim yolunda ham $css[...] değerlerini ayrıştırmaz. Dışa açık yüzey writeHtml() olarak kalır.

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

Bir tablo biçimlendirme bağlamı, 50 MB etkin bellek tavanı içinde 5,000 düğüm ve 20 düzey derinlikle sınırlandırılır (ADR-020). Çok büyük bir tabloyu bölün veya sayfalara ayırın. Tek bir aşırı büyük bağlam olarak işlemeyin.

Güvenlik notları

Güvenilmeyen girdiden gelen tablo işaretlemesi, diğer HTML ile aynı öğe ve iç içe yerleştirme üst sınırlarına tabidir. Kullanıcının oluşturduğu tablo verilerini doğrulayın. İşleyici içeriği yürütmez ve varsayılan ilke kapsamında rastgele uzak kaynakları getirmez.

Uyumluluk

İfade	Belirtim	Madde	reference_id
Kullanılan sütun genişlikleri, kullanılan tablo genişliğinde tablo sütun boyutlandırma algoritması tarafından belirlenir.	W3C CSS Table Level 3	css_tables_3#x1.x4.x9.x3
Sabit modda, sütun genişliği hesaplaması için hücre içeriği yok sayılır.	W3C CSS Table Level 3	css_tables_3#x1.x4.x5.x1.p6

Bu tarif, NextPDF’in desteklenen HTML tablolarını nasıl işlediğini gösterir. CSS Table Level 3, destek matrisinde Verified durumundadır ve burada kullanılan diğer CSS modülleri de o matris tarafından derecelendirilir.

Ticari bağlam

Geçerli değil.