Membuat PDF bertanda (tagged) yang aksesibel dari HTML

Sekilas

Gunakan resep ini untuk membuat PDF bertanda dari HTML semantik. NextPDF menulis pohon struktur logis, bahasa pada katalog, dan penanda PDF/UA-2. Kesesuaian (conformance) tetap ditentukan oleh checker. Resep ini mengikuti examples/31-pdfua2-tagged.php.

Prasyarat

Pasang Core: composer require nextpdf/core:^3.
Gunakan validator PDF/UA untuk verifikasi. Contoh ini menggunakan veraPDF.

Resep

Buat dokumen.
Panggil enableTaggedPdf() dengan tag bahasa Best Current Practice (BCP) 47 sebelum writeHtml(). Pipeline HTML mendeteksi mode bertanda ketika membangun parser, lalu mengaitkan emitter konten bertanda.
Tetapkan metadata dokumen (judul, bahasa). Anda dapat memanggil setLanguage() dengan aman bersama enableTaggedPdf() karena operasinya idempoten.
Tulis HTML semantik. Parser memetakan setiap elemen blok ke elemen struktur: h1 ke H1, p ke P, ul/li ke L/LI, dan table ke Table/TR/TD.
Simpan, lalu validasi dengan checker PDF/UA.

Contoh lengkap

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();

// Step 2 — enable tagged mode BEFORE writeHtml(). The lang argument
// drives the catalog /Lang entry and the structure tree root language.
$doc->enableTaggedPdf(lang: 'en');

// Step 3 — metadata. setLanguage() restates intent; it is idempotent here.
$doc->setTitle('Accessible Report');
$doc->setLanguage('en');

$doc->addPage();

// Step 4 — semantic HTML. Each block element becomes a StructElem; text
// runs are wrapped in BDC/EMC operators with stable MCIDs.
$html = <<<'HTML'
<h1>Quarterly Accessibility Report</h1>
<p>This document opts into tagged PDF so assistive technology can expose
a meaningful reading order.</p>
<h2>Findings</h2>
<ul>
  <li>Headings carry semantic roles.</li>
  <li>Lists keep their item structure.</li>
</ul>
HTML;

$doc->writeHtml($html);

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

echo "Wrote accessible.pdf — validate with: verapdf --flavour ua2 accessible.pdf\n";

Keluaran yang diharapkan

Wrote accessible.pdf — validate with: verapdf --flavour ua2 accessible.pdf

Keluaran tersebut mencakup pohon struktur, /MarkInfo << /Marked true >>, entri katalog /Lang, dan penanda XMP pdfuaid:part. Jalankan checker untuk memastikan bahwa item ini ada dan konsisten secara internal.

Kasus tepi

Urutan pemanggilan. Memanggil enableTaggedPdf() setelah writeHtml() tidak akan menandai secara surut konten yang sudah ditulis. Aktifkan mode bertanda terlebih dahulu.
Tag bahasa. Gunakan ConformancePolicy::strictUa2() sebagai argumen kedua agar tag BCP 47 yang bentuknya tidak valid ditolak di batas API, bukan dibuang diam-diam saat penulisan.
Pengaktifan ulang yang idempoten. Jika Anda memanggil enableTaggedPdf() dua kali, NextPDF memperbarui bahasa tanpa membangun ulang pohon struktur yang telah Anda isi.
Penandaan manual. Untuk konten non-HTML, bungkus item dengan beginTag() / endTag(). Tipe kontainer (Table, TR, L, LI) menjadi elemen pengelompokan tanpa konten bertanda. Tipe daun (P, H1–H6, TD) mendapatkan MCID.
Dukungan bukanlah kesesuaian. NextPDF menghasilkan metadata struktural yang diperlukan oleh PDF/UA-2. NextPDF juga memunculkan peringatan paritas terdegradasi: untuk persetujuan produksi, validasi dengan oracle eksternal tetap menjadi tanggung jawab pemanggil. Jalankan checker sebelum Anda menyatakan sebuah berkas sesuai.

Kesesuaian

Pernyataan	Spesifikasi	Klausul	reference_id
Konten nyata memerlukan struktur logis.	ISO 14289-2	§8.2.2
Elemen struktur mengikuti susunan bersarang dan urutan baca yang ditentukan.	ISO 14289-2	§8.2.3

Resep ini menunjukkan cara menghasilkan struktur bertanda yang mendukung penyusunan konten aksesibel. Resep ini tidak menyatakan kesesuaian PDF/UA-2; hal itu ditentukan oleh checker.