标记式 PDF（Accessibility）

Accessibility 模块（StructureTreeManager、RoleMap、TaggedContentManager）负责生成标记式 PDF 输出，让屏幕阅读器与辅助技术能正确解读文件结构。启用后，所有内容都会被包裹在描述语义角色的结构元素中。

快速参考

方法	说明
setTaggedPdf()	启用或停用标记式 PDF 模式
setLanguage()	设置文件主要语言（BCP 47）
openTag()	打开一个标记结构元素
closeTag()	关闭一个标记结构元素
image(..., alt:)	添加带替代文字的图片

启用标记式 PDF

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->setTaggedPdf(true)
    ->setLanguage('zh-TW')
    ->addPage()
    ->setFont('Helvetica', '', 12);

调用 setTaggedPdf(true) 后，StructureTreeManager 会延迟初始化，并在 PDF Catalog 中写入 MarkInfo 字典（Marked = true）。

结构元素

TCPDF-Next 支持完整的 PDF 2.0 标准标签集：

类别	标签
分组	Document, Part, Sect, Div, BlockQuote, Caption, NonStruct
标题	H1, H2, H3, H4, H5, H6
段落	P, Span
列表	L, LI, Lbl, LBody
表格	Table, TR, TH, TD, THead, TBody, TFoot
行内	Link, Em, Strong, Code
插图	Figure, Formula, Form

基本标记

$pdf->openTag('H1')
    ->cell(0, 10, '2026 年度报告', newLine: true)
    ->closeTag('H1')
    ->openTag('P')
    ->multiCell(0, 6, '本文件展示标记式 PDF 输出，以符合无障碍合规要求。')
    ->closeTag('P')
    ->save('tagged-basic.pdf');

标签必须正确嵌套。StructureTreeManager 会验证嵌套结构，若不匹配会抛出异常。

标记式表格

$pdf->openTag('Table')
    ->openTag('TR')
    ->openTag('TH')->cell(50, 8, '季度')->closeTag('TH')
    ->openTag('TH')->cell(50, 8, '营收')->closeTag('TH')
    ->closeTag('TR')
    ->openTag('TR')
    ->openTag('TD')->cell(50, 8, 'Q1')->closeTag('TD')
    ->openTag('TD')->cell(50, 8, '$1,200,000')->closeTag('TD')
    ->closeTag('TR')
    ->closeTag('Table');

图片替代文字

打开标签时可传入 Alt、ActualText、Lang、Title 等属性：

$pdf->openTag('Figure', ['Alt' => '公司商标', 'ActualText' => 'Acme Corp Logo'])
    ->image('/path/to/logo.png', 10, 50, 40, 40)
    ->closeTag('Figure');

image() 方法也接受 alt 参数作为简写 — $pdf->image('chart.png', 10, 80, 120, 60, alt: '营收图表') 会自动将图片包裹在 Figure 标签中。

角色映射

RoleMap 将自定义标签名称映射到标准 PDF 结构类型，让你能使用领域特定名称同时维持 PDF/UA 兼容性：

$pdf->openTag('Invoice', ['roleMap' => 'Sect'])
    ->openTag('LineItem', ['roleMap' => 'P'])
    ->cell(0, 8, 'Widget x 10 — $500.00', newLine: true)
    ->closeTag('LineItem')
    ->closeTag('Invoice');

角色映射会写入结构树根节点，让验证工具能将自定义标签解析为标准等效类型。若需处理多语言内容，可在元素层级覆盖语言：->openTag('P', ['Lang' => 'en-US'])。

PDF/UA 合规需求

要生成完全符合 PDF/UA 规范的文件，请确保：

1. 启用标记式 PDF — setTaggedPdf(true)
2. 设置文件语言 — setLanguage('zh-TW')
3. 所有内容都已标记 — 结构元素外不可有未标记的内容
4. 所有图片都有替代文字 — 通过 alt: 参数或 Figure 标签的 Alt 属性
5. 表格使用 TH 标记表头 — 表头单元格必须与数据单元格区分
6. 字体已嵌入 — TCPDF-Next 默认嵌入所有字体

与 PDF/A-4 的整合

标记式 PDF 与 PDF/A-4 完全兼容。同时启用即可生成兼具存档与无障碍特性的文件：

$pdf = Document::create()
    ->setTaggedPdf(true)
    ->setPdfA(true)
    ->setLanguage('zh-TW')
    ->setTitle('无障碍存档文件')
    ->addPage()
    ->setFont('Helvetica', '', 12)
    ->openTag('H1')
    ->cell(0, 10, 'PDF/A-4 + PDF/UA 文件', newLine: true)
    ->closeTag('H1')
    ->save('accessible-archival.pdf');