Skip to content

无障碍(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 会自动追踪所有结构标签,在输出时构建完整的结构树。

结构元素

使用 openTagcloseTag 标记文件内容的语义结构:

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');

下一步

以 LGPL-3.0-or-later 许可证发布。