无障碍(PDF/UA)
★ Pro — Commercial License Required
PDF/UA 无障碍功能需要 Pro 包。
TCPDF-Next Pro 提供完整的 PDF/UA(ISO 14289-2)支持,让生成的 PDF 文件能被屏幕阅读器与辅助技术正确解读,服务视障及其他身心障碍用户。
核心类
| 类 | 说明 |
|---|---|
StructureTreeManager | 自动构建文件结构树 |
RoleMap | 自定义标签名称到标准结构类型的映射 |
启用标记式 PDF
php
use Yeeefang\TcpdfNext\Core\Document;
$pdf = Document::create()
->setTaggedPdf(true)
->setLanguage('zh-CN');启用后,StructureTreeManager 会自动追踪所有结构标签,在输出时构建完整的结构树。
结构元素
使用 openTag 和 closeTag 标记文件内容的语义结构:
php
$pdf->openTag('H1')
->cell(0, 10, '2026 年度报告', newLine: true)
->closeTag('H1')
->openTag('P')
->multiCell(0, 6, '本报告概述公司年度运营成果与财务状况...')
->closeTag('P');支持的结构元素
| 元素 | 用途 | PDF/UA 要求 |
|---|---|---|
Document | 根结构元素 | 必须 |
Part | 文件主要区块 | 可选 |
Sect | 区段 | 可选 |
H1 -- H6 | 标题层级 | 必须按层级使用 |
P | 段落 | 文字内容必须标记 |
Table | 表格 | 必须包含 TH/TD |
TR | 表格行 | 必须在 Table 内 |
TH | 表头单元格 | 数据表必须有表头 |
TD | 数据单元格 | 必须在 TR 内 |
L | 列表 | 必须包含 LI |
LI | 列表项 | 必须在 L 内 |
Figure | 图片与图表 | 必须有替代文字 |
Link | 超链接 | 必须有链接文字 |
Span | 行内内容 | 用于语言标记 |
RoleMap 角色映射
将自定义标签名称映射到标准 PDF 结构类型,提高代码的语义可读性:
php
$pdf->setRoleMap([
'invoice-header' => 'H1',
'line-item' => 'TR',
'item-desc' => 'TD',
'item-amount' => 'TD',
'summary' => 'P',
'company-logo' => 'Figure',
]);
// 使用自定义标签
$pdf->openTag('invoice-header')
->cell(0, 10, '发票明细', newLine: true)
->closeTag('invoice-header');替代文字
所有非装饰性图片都必须提供替代文字,让屏幕阅读器能描述图片内容:
php
$pdf->image(
'/path/to/revenue-chart.png',
x: 10, y: 50, width: 100, height: 80,
alt: '营收图表:第一季 120 万、第二季 135 万、第三季 142 万、第四季 158 万'
);装饰性图片应标记为装饰元素(artifact),使其不出现在结构树中:
php
$pdf->artifact(function ($pdf) {
$pdf->image('/path/to/decorative-border.png', x: 0, y: 0, width: 210);
});语言标记
文件必须设置主要语言,并可对个别内容区块标记不同语言:
php
$pdf->setLanguage('zh-CN'); // 文件主要语言
// 对特定段落标记不同语言
$pdf->openTag('P', ['lang' => 'en-US'])
->multiCell(0, 6, 'This section is in English.')
->closeTag('P');
$pdf->openTag('P', ['lang' => 'ja-JP'])
->multiCell(0, 6, 'このセクションは日本語です。')
->closeTag('P');表格无障碍
数据表格必须有正确的表头结构,让屏幕阅读器能建立单元格与表头的关联:
php
$pdf->openTag('Table')
->openTag('TR')
->openTag('TH')->cell(40, 8, '品名')->closeTag('TH')
->openTag('TH')->cell(30, 8, '数量')->closeTag('TH')
->openTag('TH')->cell(30, 8, '金额')->closeTag('TH')
->closeTag('TR')
->openTag('TR')
->openTag('TD')->cell(40, 8, 'Widget A')->closeTag('TD')
->openTag('TD')->cell(30, 8, '100')->closeTag('TD')
->openTag('TD')->cell(30, 8, 'NT$ 5,000')->closeTag('TD')
->closeTag('TR')
->closeTag('Table');结合 PDF/A-4 与 PDF/UA
建立同时符合归档与无障碍标准的文件:
php
use Yeeefang\TcpdfNext\Pro\Archive\PdfAManager;
use Yeeefang\TcpdfNext\Pro\Archive\PdfAVersion;
$pdf = Document::create()
->setTaggedPdf(true)
->setLanguage('zh-CN');
$manager = new PdfAManager($pdf);
$manager->enable(PdfAVersion::A4);
$manager->setOutputIntent(/* ... */);
// 文件同时符合 PDF/A-4 与 PDF/UA-2
$pdf->addPage()
->openTag('H1')
->font('Helvetica', size: 18)
->cell(0, 10, '无障碍归档文件', newLine: true)
->closeTag('H1')
->save('/output/pdfa4-pdfua.pdf');下一步
- PDF/A-4 归档 — 归档合规的完整配置。
- PAdES 数字签名 — 为无障碍文件加入数字签名。
- 授权 — Pro 包的商业授权条款。