ส่งออกโครงสร้างทรี PDF/UA-2 ที่มีแท็กจากเนื้อหาเชิงความหมาย

ภาพรวมโดยสังเขป

สูตรนี้สร้างไฟล์ Portable Document Format/Universal Accessibility 2 (PDF/UA-2) ที่มีแท็ก โดยตั้งเป้าไปที่ International Organization for Standardization (ISO) 14289-2 NextPDF ส่งออกโครงสร้างทรีเชิงตรรกะ ลำดับเนื้อหาแบบมาร์ก ภาษาของแคตาล็อก และเมทาดาทาสำหรับระบุตัวตนระดับเอกสาร โครงสร้างนี้รองรับการเขียนเนื้อหาที่เข้าถึงได้ แต่ตัวตรวจสอบอิสระเป็นผู้ตัดสินความสอดคล้อง สูตรนี้อ้างอิงตาม examples/31-pdfua2-tagged.php

การติดตั้ง

composer require nextpdf/core:^3

วางตัวตรวจสอบ PDF/UA-2 ไว้ใน PATH สำหรับการยืนยัน สูตรนี้ใช้ veraPDF พร้อมฟเลเวอร์ ua2 การส่งออกโครงสร้างที่มีแท็กไม่จำเป็นต้องใช้แพ็กเกจ Pro หรือ Enterprise

ภาพรวมเชิงแนวคิด

PDF ที่มีแท็กจัดเก็บ โครงสร้างทรีเชิงตรรกะ คู่ขนานไว้ควบคู่กับสตรีมเนื้อหาเชิงภาพ เทคโนโลยีช่วยเหลืออ่านจากทรีแทนการอ่านจากเค้าโครงพิกเซล โครงสร้างจึงเป็นตัวกำหนดลำดับการอ่านที่เปิดเผยออกมา ISO 14289-2 กำหนดข้อกำหนดสี่ข้อในส่วนนี้ เนื้อหาจริง (ที่ไม่ใช่อาร์ติแฟกต์) ต้องเข้าถึงได้ผ่านทรีนี้ (§8.2.2) องค์ประกอบโครงสร้างต้องซ้อนกันตามลำดับที่กำหนดไว้ (§8.2.3) ทุกองค์ประกอบต้องเชื่อมโยงกับเนมสเปซโครงสร้างที่รู้จัก ไม่ว่าจะโดยตรงหรือผ่านการแมประหว่างบทบาท (§8.2.4) ภาษาธรรมชาติของเนื้อหาต้องประกาศไว้ที่ระดับเอกสาร และระบุให้ละเอียดขึ้นในระดับองค์ประกอบโครงสร้างเมื่อมีความแตกต่าง (§8.4.4)

NextPDF สร้างแบบจำลองนี้ด้วย ConformanceMode แบบมีชนิดข้อมูล enableTaggedPdf() ตั้งค่า ConformanceMode::PdfUa2 ซึ่ง (a) ทำให้ไปป์ไลน์ Hypertext Markup Language (HTML) เชื่อมต่อ TaggedContentEmitter ระหว่างสร้างพาร์เซอร์ (b) ตั้งค่าแฟล็ก MarkInfoMarked ของแคตาล็อกที่ส่งสัญญาณว่าเป็น PDF ที่มีแท็ก (ISO 32000-2 §14.7) และ (c) บันทึกภาษา Best Current Practice 47 (BCP-47) สำหรับรายการ Lang ของแคตาล็อก ตัวเขียนยังส่งออกรายการ Tabs รายหน้า เพื่อให้ลำดับแท็บเป็นไปตามลำดับโครงสร้าง (ISO 32000-2 §14.8)

ค่าคงที่เชิงโครงสร้างแบบเข้มงวดของ UA-2 ใช้กับ ConformanceMode::PdfUa2 เท่านั้น โดยการออกแบบ การสร้าง ConformancePolicy แบบเข้มงวดสำหรับโหมดอื่นใดจะโยน InvalidConfigException

พื้นผิว API

พื้นผิวของ application programming interface (API) อ้างอิงจาก PHPDoc โดยใช้จุดเริ่มต้นหลักเหล่านี้:

\NextPDF\Core\Document::createStandalone(): Document
Document::enableTaggedPdf(string $lang = 'en', ?ConformancePolicy $policy = null): static
Document::setLanguage(string $lang): static
\NextPDF\Conformance\ConformancePolicy::strictUa2(): self
\NextPDF\Conformance\ConformanceMode::PdfUa2 (โหมดที่ตั้งค่าโดย enableTaggedPdf())
Document::beginTag(string $type): static / Document::endTag(): static (การทำแท็กด้วยตนเองสำหรับเนื้อหาที่ไม่ใช่ HTML)

ตัวอย่างโค้ด — เริ่มต้นอย่างรวดเร็ว

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();

// Enable tagged mode BEFORE writeHtml(). The HTML pipeline detects the
// mode at parser construction time and wires the tagged-content emitter.
$doc->enableTaggedPdf(lang: 'en');

$doc->setTitle('Quarterly Accessibility Report');
$doc->setLanguage('en');
$doc->addPage();

$doc->writeHtml(<<<'HTML'
<h1>Quarterly Accessibility Report</h1>
<p>This document opts into tagged PDF so assistive technology can expose
a meaningful reading order.</p>
<ul>
  <li>Headings carry semantic roles.</li>
  <li>Lists keep their item structure.</li>
</ul>
HTML);

$doc->save(__DIR__ . '/output/31-pdfua2-tagged.pdf');

echo "Created: output/31-pdfua2-tagged.pdf\n";

ตัวอย่างโค้ด — การใช้งานจริง

โปรแกรมแบบครบในตัวนี้สามารถรันในฮาร์เนสได้ ในการใช้งานจริง ควรให้โปรแกรมล้มเหลวตั้งแต่เนิ่นๆเมื่อพบแท็กภาษาที่มีรูปแบบไม่ถูกต้อง แทนที่จะปล่อยให้พบปัญหาเมื่อใช้ตัวตรวจสอบภายนอก ส่ง ConformancePolicy::strictUa2() เพื่อปฏิเสธแท็ก BCP-47 ที่ไม่ถูกต้องตั้งแต่ขอบเขตของ API จากนั้นจึงควบคุมการบิลด์ด้วยคำตัดสินของตัวตรวจสอบ

<?php

declare(strict_types=1);

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

use NextPDF\Conformance\ConformancePolicy;
use NextPDF\Core\Document;
use NextPDF\Exception\InvalidConfigException;

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: (__DIR__ . '/accessible.pdf');

try {
    $doc = Document::createStandalone();

    // Strict UA-2: a malformed BCP 47 tag throws here, not silently at
    // write time. strictUa2() also forces the §8.4.4 Lang validation.
    $doc->enableTaggedPdf(lang: 'en-GB', policy: ConformancePolicy::strictUa2());

    $doc->setTitle('Accessible Annual Report 2026');
    $doc->setLanguage('en-GB');
    $doc->addPage();

    $doc->writeHtml(<<<'HTML'
<h1>Annual Report 2026</h1>
<p>Audited results for the financial year ending March 2026.</p>
<h2>Segment performance</h2>
<table>
  <tr><th>Segment</th><th>Revenue</th></tr>
  <tr><td>Cloud</td><td>42.1</td></tr>
  <tr><td>Services</td><td>18.7</td></tr>
</table>
HTML);

    $doc->save($out);
} catch (InvalidConfigException $e) {
    fwrite(STDERR, "Tagged PDF/UA-2 setup rejected: {$e->getMessage()}\n");
    exit(1);
}

// The gate is the checker, not the library.
$exitCode = 0;
$report = [];
exec('verapdf --flavour ua2 ' . escapeshellarg($out), $report, $exitCode);

if ($exitCode !== 0) {
    fwrite(STDERR, "veraPDF FAILED — output is not PDF/UA-2 conforming\n");
    fwrite(STDERR, implode("\n", $report) . "\n");
    exit(1);
}

echo "veraPDF PASS — accessible.pdf carries a conforming UA-2 structure\n";

บนโฮสต์ที่ verapdf --flavour ua2 รายงานว่าไฟล์สอดคล้อง เอาต์พุตมาตรฐาน (STDOUT) ที่คาดไว้คือ:

veraPDF PASS — accessible.pdf carries a conforming UA-2 structure

หาก enableTaggedPdf() ปฏิเสธแท็กภาษา โปรแกรมจะออกด้วยค่าที่ไม่ใช่ศูนย์หลังจาก Tagged PDF/UA-2 setup rejected: … ทางข้อผิดพลาดมาตรฐาน (STDERR) หากตัวตรวจสอบรายงานปัญหา โปรแกรมจะออกด้วยค่าที่ไม่ใช่ศูนย์หลังจาก veraPDF FAILED — output is not PDF/UA-2 conforming ตัวตรวจสอบเป็นผู้ให้คำตัดสิน: NextPDF ส่งออกโครงสร้าง แต่ไม่ได้ยืนยันความสอดคล้อง

กรณีขอบและจุดที่ต้องระวัง

ลำดับการเรียก การเรียก enableTaggedPdf() หลัง writeHtml() จะไม่ทำแท็กย้อนหลังให้กับเนื้อหาที่เขียนไปแล้ว จึงต้องเปิดใช้งานโหมดมีแท็กไว้ก่อน
เกตควบคุมภาษาแบบเข้มงวด หากไม่มีนโยบาย แท็ก BCP-47 ที่แยกวิเคราะห์ไม่ได้จะถูกตัดทิ้งอย่างเงียบๆ และจะปรากฏเมื่อถึงเวลาตรวจสอบเท่านั้น เมื่อใช้ ConformancePolicy::strictUa2() แท็กเดียวกันจะโยน InvalidConfigException ที่ขอบเขตของ enableTaggedPdf() (เส้นทางเข้มงวดของ ISO 14289-2 §8.4.4)
การเปิดใช้งานซ้ำแบบไม่เปลี่ยนผลลัพธ์ หากเรียก enableTaggedPdf() สองครั้ง NextPDF จะอัปเดตภาษาโดยไม่สร้างโครงสร้างทรีที่มีข้อมูลอยู่แล้วขึ้นใหม่
การทำแท็กด้วยตนเอง สำหรับเนื้อหาที่ไม่ใช่ HTML ให้ครอบรายการด้วย beginTag() / endTag() บทบาทแบบคอนเทนเนอร์ (Table, TR, L, LI) จะกลายเป็นองค์ประกอบจัดกลุ่มที่ไม่มีเนื้อหาแบบมาร์ก ส่วนบทบาทแบบใบ (P, H1–H6, TD) จะได้รับตัวระบุเนื้อหาแบบมาร์ก (MCID)
ความเฉพาะของโหมด ConformancePolicy แบบเข้มงวดใช้ได้กับ ConformanceMode::PdfUa2 เท่านั้น การรวมแฟล็ก UA-2 แบบเข้มงวดเข้ากับโหมด PDF/A จะโยน InvalidConfigException สามารถประกอบงานส่งมอบ PDF/A ที่มีแท็กได้โดยเปิดใช้งานโหมดมีแท็กและโปรไฟล์ PDF/A แยกกัน

ประสิทธิภาพ

โครงสร้างทรีจะเพิ่มทรีคู่ขนานหนึ่งชุดซึ่งประกอบด้วยดิกชันนารีน้ำหนักเบาและตัวดำเนินการ BDC/EMC ต่อช่วงข้อความ สำหรับรายงานทั่วไป โอเวอร์เฮดอยู่ที่ไม่กี่เปอร์เซ็นต์ของขนาดเอาต์พุต และยังอยู่ภายในงบประมาณ 2000 ms / 128 MB ได้โดยไม่ตึงตัว ใช้โปรไฟล์การทำซ้ำเชิงความหมาย เพราะงานส่งมอบที่มุ่งเน้นตัวตรวจสอบจะถูกเปรียบเทียบด้วยโครงสร้าง abstract syntax tree (AST) รวมกับเมทาดาทา ไม่ใช่ด้วยไบต์ดิบ โปรดดูส่วนความสอดคล้อง

หมายเหตุด้านความปลอดภัย

ถิ่นที่อยู่ของข้อมูลและการบรรเทา PII

โครงสร้างทรีเก็บข้อความเดียวกับเนื้อหาที่มองเห็นได้ หาก HTML ต้นทางมีข้อมูลส่วนบุคคล รวมถึงข้อมูลที่ระบุตัวบุคคลได้ (PII) ข้อมูลนั้นก็เข้าถึงได้ผ่านทรีและผ่านแอตทริบิวต์ ActualText/Alt ด้วยเช่นกัน ให้ใช้การลบข้อมูลเฉพาะส่วนและการลดข้อมูลให้น้อยที่สุดก่อนเขียนเนื้อหา เช่นเดียวกับที่ใช้กับเนื้อหาที่มองเห็นได้ การทำแท็กไม่เพิ่มเส้นทางการรั่วไหลของข้อมูลใหม่ แต่โดยการออกแบบจะทำให้ข้อความถูกสกัดออกได้ด้วยโปรแกรม

เทเลเมทรีที่ปลอดภัยและการล้างข้อมูลในล็อก

สูตรนี้เขียนเฉพาะบรรทัดความคืบหน้าแบบคงที่ไปยัง STDOUT เท่านั้น โดยส่ง PDF ไปยังช่องทางเสริมของฮาร์เนส (NEXTPDF_COOKBOOK_OUTPUT) หรือพาธของผู้เรียก ข้อความของเอกสารจะไม่ถูกบันทึกลงล็อกเลย เก็บเอาต์พุตของตัวตรวจสอบซึ่งอาจสะท้อนชิ้นส่วนเนื้อหาออกมาไว้นอกล็อกที่ใช้ร่วมกัน

แบบจำลองภัยคุกคาม

PDF ที่มีแท็กไม่ใช่ขอบเขตความเชื่อถือ หากระบบผู้บริโภคเชื่อถือโครงสร้างทรีเพื่อการประมวลผลอัตโนมัติ ระบบนั้นยังต้องตรวจสอบไฟล์อยู่ดี เพราะผู้ผลิตที่ไม่ประสงค์ดีสามารถส่งออกทรีที่มีรูปแบบถูกต้องเชิงโครงสร้างแต่ชวนให้เข้าใจผิดได้ ให้ถือว่าโครงสร้างเป็นสิ่งอำนวยความสะดวกด้านการเข้าถึง ไม่ใช่สัญญาณบ่งชี้ความสมบูรณ์ของข้อมูลหรือความถูกต้องแท้จริง

พฤติกรรมในโหมด FIPS

สูตรนี้ไม่ดำเนินการเข้ารหัสลับใดๆ โหมด Federal Information Processing Standards (FIPS) ไม่เปลี่ยนพฤติกรรมของสูตรนี้ ไม่มีการลงลายเซ็นหรือการเข้ารหัสลับเข้ามาเกี่ยวข้อง

การแมป PDF/UA-2

ข้อกำหนด PDF/UA-2	สิ่งที่ NextPDF ปล่อยออกมา	ข้อ
เนื้อหาจริงอยู่ภายในโครงสร้างทรี	`StructTreeRoot` พร้อม `StructElem` ต่อบล็อกและเนื้อหาแบบมาร์กที่เชื่อมโยงด้วย MCID	ISO 14289-2 §8.2.2
การซ้อนและลำดับการอ่านที่กำหนดไว้	องค์ประกอบบล็อกที่แมปไปยังบทบาท grouping/leaf ตามลำดับของเอกสาร	ISO 14289-2 §8.2.3
เนมสเปซโครงสร้างที่รู้จัก	บทบาทในเนมสเปซ PDF 2.0 โดยแท็ก HTML จะถูกแมประหว่างบทบาทเมื่อจำเป็น	ISO 14289-2 §8.2.4
ภาษาของเอกสารและขององค์ประกอบ	แคตาล็อก `Lang` จากแท็ก BCP-47 และ `Lang` ต่อองค์ประกอบเมื่อแตกต่างกัน	ISO 14289-2 §8.4.4
เนื้อหาที่ไม่ใช่ข้อความมีข้อความทางเลือก	`Alt`/`ActualText` ที่เก็บไว้บนองค์ประกอบโครงสร้างแบบ figure/non-text	ISO 14289-2 §8.5.1
ความสัมพันธ์ของตาราง	`Table`/`TR`/`TH`/`TD` บทบาทพร้อมการเชื่อมโยงส่วนหัว	ISO 14289-2 §8.2.5.26
เมทาดาทาสำหรับระบุตัวตนของส่วน	การระบุตัวตนระดับเอกสารที่กำหนดไว้ในตอนบันทึก	ISO 14289-2 §Intro (`pdfua2#p17`)

การอ้างอิงข้ามแท็ก → ISO 32000-2 §14

PDF/UA-2 วางข้อกำหนดด้านการเข้าถึงไว้บนกลไก PDF ที่มีแท็กของ ISO 32000-2 NextPDF อาศัยการแมปนี้:

การส่งออกของ NextPDF	กลไกใน ISO 32000-2 §14	ข้อ
โครงสร้างทรีเชิงตรรกะ (`StructTreeRoot`)	โครงสร้างเชิงตรรกะของ PDF ที่มีแท็ก	§14.7 (`iso32000_2_sec14#x1.x38.p13`)
แคตาล็อก `MarkInfo << /Marked true >>`	เครื่องหมายบ่งชี้ PDF ที่มีแท็ก	§14.7 (`iso32000_2_sec14#x1.x40.p3`)
รายการ `Tabs` ต่อหน้าที่เป็นไปตามลำดับโครงสร้าง	การนำทางเชิงโครงสร้าง / ลำดับแท็บ	§14.8 (`iso32000_2_sec14#x1.x50`)

การแมป WCAG 2.2

PDF/UA-2 คือการแสดงออกในรูปแบบ PDF ของข้อกำหนดเชิงโครงสร้างที่ Web Content Accessibility Guidelines (WCAG) 2.2 ระบุไว้แบบไม่ขึ้นกับรูปแบบ ความสัมพันธ์ที่เกี่ยวข้องมีดังนี้:

เกณฑ์ความสำเร็จ WCAG 2.2	กลไก PDF/UA-2 ที่สูตรนี้สร้างขึ้น
1.3.1 ข้อมูลและความสัมพันธ์ (ระดับ A)	โครงสร้างทรีทำให้ส่วนหัว รายการ และความสัมพันธ์ของตารางสามารถระบุได้ด้วยโปรแกรม (`wcag_2_2#x2.x3.x3.x1.p3`)
1.3.2 ลำดับที่มีความหมาย (ระดับ A)	ลำดับโครงสร้างกำหนดลำดับการอ่านโดยไม่ขึ้นกับเค้าโครงเชิงภาพ
3.1.1 ภาษาของหน้า (ระดับ A)	รายการแคตาล็อก `Lang` จากแท็ก BCP-47
1.1.1 เนื้อหาที่ไม่ใช่ข้อความ (ระดับ A)	`Alt`/`ActualText` บนองค์ประกอบโครงสร้างที่ไม่ใช่ข้อความ (ISO 14289-2 §8.5.1)

การแมปนี้แสดงให้เห็นว่าโครงสร้างที่ส่งออกมารองรับเกณฑ์ WCAG 2.2 ในจุดใด การแมปนี้ไม่ใช่การกล่าวอ้างความสอดคล้องกับ WCAG ความสอดคล้องกับ WCAG ครอบคลุมประสบการณ์ของผู้ใช้ทั้งหมด และการประเมินด้านการเข้าถึงเป็นผู้ตัดสิน ไม่ใช่ผู้ผลิต

ความสอดคล้อง

ข้อความระบุ	มาตรฐาน	ข้อ
เนื้อหาจริงจำเป็นต้องมีโครงสร้างเชิงตรรกะ	ISO 14289-2	§8.2.2
องค์ประกอบโครงสร้างสอดคล้องกับการซ้อนและลำดับการอ่านที่กำหนดไว้	ISO 14289-2	§8.2.3
ทุกองค์ประกอบโครงสร้างเชื่อมโยงกับเนมสเปซที่รู้จัก ไม่ว่าจะโดยตรงหรือผ่านการแมประหว่างบทบาท	ISO 14289-2	§8.2.4
ภาษาธรรมชาติถูกประกาศไว้ที่ระดับเอกสารและระดับองค์ประกอบโครงสร้าง	ISO 14289-2	§8.4.4
เนื้อหาที่ไม่ใช่ข้อความมีข้อความทางเลือก	ISO 14289-2	§8.5.1
เซลล์ตารางมีความสัมพันธ์แบบ row/header/data	ISO 14289-2	§8.2.5.26
เครื่องหมายบ่งชี้ PDF ที่มีแท็กคือแฟล็ก `MarkInfoMarked` ของแคตาล็อก	ISO 32000-2	§14.7
ความสอดคล้องตัดสินเทียบกับส่วน ไม่ได้ยืนยันโดยผู้ผลิต	ISO 14289-2	§8.14.2

NextPDF ส่งออกโครงสร้างที่มีแท็กซึ่งรองรับการเขียนเนื้อหาที่เข้าถึงได้ การรองรับไม่ใช่ความสอดคล้อง สูตรนี้ไม่ได้ยืนยันความสอดคล้องกับ PDF/UA-2 ตัวตรวจสอบอิสระ เช่น veraPDF เป็นผู้ตัดสินเรื่องนั้น รันตัวตรวจสอบก่อนระบุว่าไฟล์สอดคล้อง