Tuân thủ PDF/UA-2: cấu trúc được gắn thẻ do NextPDF phát ra cho ISO 14289-2

Tổng quan nhanh

Tuyên bố ranh giới. NextPDF phát ra cấu trúc được gắn thẻ hỗ trợ việc tạo tài liệu dễ tiếp cận; thư viện không khẳng định việc tuân thủ PDF/UA-2 — trình kiểm tra mới quyết định điều đó.

PDF/UA-2 là ISO 14289-2:2024, một hồ sơ khả năng tiếp cận được xây dựng trên Portable Document Format (PDF) 2.0 có gắn thẻ. NextPDF Core phát ra cây cấu trúc, nội dung được đánh dấu, ngôn ngữ của catalog và cấu trúc, cùng dấu hiệu pdfuaid thông qua Document::enableTaggedPdf(). Thư viện tạo ra cấu trúc dễ tiếp cận; trình kiểm tra PDF/UA, chẳng hạn như verapdf --flavour ua2, quyết định việc tuân thủ. ISO 14289-2 §8.1 định nghĩa việc tuân thủ là các yêu cầu về định dạng tệp mà tài liệu phải đáp ứng, do trình kiểm tra đánh giá, chứ không phải là tuyên bố mà bên tạo lập công bố.

Cài đặt

composer require nextpdf/core:^3

Gắn thẻ PDF/UA-2 là một khả năng của Core (security.tagged_pdf). Bạn không cần gói Premium để phát ra chính cấu trúc được gắn thẻ.

Tổng quan về khái niệm

Document::enableTaggedPdf(string $lang = 'en', ?ConformancePolicy $policy = null) thiết lập ConformanceMode::PdfUa2 và nối TaggedContentEmitter vào luồng phát. Chế độ này là nguồn quyết định duy nhất về việc tài liệu có được gắn thẻ theo đặc tả hay không; sau đó trình ghi đáp ứng các nghĩa vụ về cấu trúc mà ISO 14289-2 áp đặt:

Nội dung thực được gắn thẻ — §8.2.2: mọi phần nội dung thực, không phải vật phẩm phụ, đều được đưa vào cấu trúc logic, còn các vật phẩm phụ được đánh dấu là vật phẩm phụ. Cơ chế này dựa trên cấu trúc PDF được gắn thẻ của ISO 32000-2 §14.7 (StructTreeRoot, các phần tử cấu trúc, MCID).
Ngôn ngữ tự nhiên được khai báo — §8.4.4: tài liệu và các phần chuyển ngôn ngữ đều mang một Lang. Với ConformancePolicy::strictUa2(), thẻ BCP-47 không hợp lệ sẽ bị từ chối ngay tại ranh giới API theo cơ chế thất bại sớm, thay vì bị âm thầm bỏ qua tại thời điểm ghi.
Hình có nội dung thay thế — §8.5.1: mọi phần tử cấu trúc Figure đều có một mô tả thay thế.
Bảng liên kết ô tiêu đề và dữ liệu — §8.2.5.26: sự liên kết giữa ô header/data của bảng được thể hiện trong cấu trúc.

NextPDF phát ra các cấu trúc này. Thư viện không chạy quá trình đánh giá tuân thủ theo §8.1; đó là vai trò của trình kiểm tra, và tiêu chuẩn dành riêng vai trò đó cho trình kiểm tra.

Bề mặt API

Phương thức	Tác động
`enableTaggedPdf(string $lang = 'en', ?ConformancePolicy $policy = null): static`	Thiết lập `ConformanceMode::PdfUa2`, nối `TaggedContentEmitter`, xác thực `$lang` theo chính sách. Ném `InvalidConfigException` khi chính sách bắt buộc xác thực Lang và `$lang` không hợp lệ.
`beginTag()/endTag()`	Cấu trúc thủ công cho nội dung không phải HTML; các kiểu vùng chứa trở thành phần tử nhóm, các kiểu lá nhận MCID.
`ConformanceMode::requiresPdfUa2PageTabs(): bool`	True đối với `PdfUa2` — điều khiển việc bắt buộc `/Tabs /S` cho trang.

Mã ví dụ — bắt đầu nhanh

<?php

declare(strict_types=1);

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

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

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

$doc = Document::createStandalone();
$doc->enableTaggedPdf('en', ConformancePolicy::strictUa2()); // fail-fast Lang
$doc->setTitle('Accessible report 2026');
$doc->writeHtml('<h1>Quarterly report</h1><p>Body text.</p>'
    . '<img src="chart.png" alt="Revenue rose 12% quarter on quarter">');
$doc->save($out);

echo "Wrote {$out} — validate: verapdf --flavour ua2 {$out}\n";

Mã ví dụ — triển khai sản xuất

Cổng kiểm soát sản xuất chạy verapdf --flavour ua2 out.pdf và cho bản dựng thất bại khi trình kiểm tra báo cáo vi phạm. Kiểm thử tích hợp tests/Integration/Accessibility/VeraPdfUa2GoldenTest.php xác nhận rằng fixture vàng HTML→PDF-được-gắn-thẻ vượt qua kiểm tra veraPDF UA-2 (được bỏ qua khi không có veraPDF). Phán quyết của trình kiểm tra là cổng kiểm soát; đầu ra của bộ phát là đầu vào cho cổng đó.

Trường hợp đặc biệt & lưu ý

Bật trước. Gọi enableTaggedPdf() sau writeHtml() sẽ không gắn thẻ hồi tố cho nội dung đã được ghi.
Ngôn ngữ nghiêm ngặt. Truyền ConformancePolicy::strictUa2() để từ chối thẻ BCP-47 không hợp lệ ngay tại ranh giới API thay vì chỉ thất bại ở bước xác thực veraPDF về sau.
Bật lại vẫn giữ bất biến. Việc gọi phương thức này hai lần sẽ cập nhật ngôn ngữ mà không xây dựng lại một cây cấu trúc đã có dữ liệu.
Tài liệu được gắn thẻ rỗng. Một tài liệu được gắn thẻ rỗng không công bố PDF/UA-2 (EmptyTaggedPdfDoesNotAdvertisePdfUa2Test): dấu hiệu này không được phát ra cho tài liệu không có nội dung thực, nên tệp không khẳng định quá mức.

Hiệu năng

Việc phát cây cấu trúc tỉ lệ thuận với số lượng phần tử. Ngân sách là thời gian thực tế ≤ 1.500 ms và mức đỉnh bộ nhớ ≤ 64 MB cho một báo cáo điển hình.

Lưu ý về bảo mật

Gắn thẻ cho khả năng tiếp cận mang tính cấu trúc, không phải là một biện pháp kiểm soát bảo mật. Theo thiết kế, cơ chế này phơi bày cấu trúc logic của tài liệu cho công nghệ hỗ trợ. Cây thẻ không cung cấp thuộc tính bảo mật nào về tính bí mật thông tin.

Ánh xạ PDF/UA-2

Nghĩa vụ PDF/UA-2	Điều khoản ISO 14289-2	Cách phát của NextPDF
Nội dung thực được gắn thẻ trong cấu trúc logic	§8.2.2	`TaggedContentEmitter` + `StructureTree`
Ngôn ngữ của tài liệu/cấu trúc được khai báo	§8.4.4	catalog `/Lang`, được xác thực qua `Bcp47Validator`
Mô tả thay thế cho hình	§8.5.1	`alt` → `/Alt` trên phần tử Figure
Liên kết header/data của bảng	§8.2.5.26	Cấu trúc TR/TH/TD từ các bảng HTML

Thẻ → tham chiếu chéo ISO 32000-2 §14.9

PDF/UA-2 được xây dựng trên mô hình PDF được gắn thẻ của ISO 32000-2. Các phần tử cấu trúc mà NextPDF phát ra được phân giải dựa trên cấu trúc logic ISO 32000-2 §14.7 (StructTreeRoot, các phần tử cấu trúc, MCID) — chunk — và không gian tên cấu trúc chuẩn được định nghĩa cho PDF 2.0. Ánh xạ vai trò gắn các phần tử HTML (h1, p, table) với các kiểu cấu trúc chuẩn để trình kiểm tra UA-2 có thể nhận diện chúng.

Ánh xạ WCAG 2.2

Cấu trúc được gắn thẻ là nền tảng kỹ thuật cho các tiêu chí thành công của Web Content Accessibility Guidelines (WCAG) 2.2 — 1.1.1 (nội dung thay thế cho nội dung phi văn bản, qua §8.5.1 Figure /Alt), 1.3.1 (thông tin và mối quan hệ, qua cây cấu trúc), và 1.3.2 (trình tự có ý nghĩa, qua thứ tự đọc). Việc phát ra cấu trúc là cần thiết nhưng chưa đủ để tuân thủ WCAG; đánh giá khả năng tiếp cận, chứ không phải thư viện, đưa ra quyết định đó.

Hành vi trong chế độ FIPS

Việc phát PDF/UA-2 không thực hiện thao tác mật mã nào. Chế độ Federal Information Processing Standards (FIPS) không ảnh hưởng đến luồng xử lý cấu trúc được gắn thẻ.

Tuân thủ

Tuyên bố	Đặc tả	Điều khoản
Phiên bản PDF/UA được xác định bằng không gian tên lược đồ `pdfuaid` (Bảng 1).	ISO 14289-2	§5
Việc tuân thủ PDF/UA-2 đặt ra các yêu cầu về định dạng tệp mà tài liệu phải đáp ứng (trình kiểm tra đánh giá việc tuân thủ; bên tạo lập không công bố điều đó).	ISO 14289-2	§8.1
Nội dung thực phải được gắn thẻ trong cấu trúc logic.	ISO 14289-2	§8.2.2
Ngôn ngữ tự nhiên của tài liệu phải được khai báo.	ISO 14289-2	§8.4.4
Các phần tử Figure phải có một mô tả thay thế.	ISO 14289-2	§8.5.1
Cấu trúc bảng phải liên kết các ô tiêu đề và ô dữ liệu.	ISO 14289-2	§8.2.5.26
Cấu trúc dễ tiếp cận được xây dựng trên cấu trúc logic PDF được gắn thẻ của ISO 32000-2.	ISO 32000-2	§14.7.2

Các trích dẫn là con trỏ clause-id và reference_id đến kho ngữ liệu xác minh. Không có văn bản tiêu chuẩn nào được tái tạo.