iText7 pdfhtml转换生成PDF的页眉无法被屏幕阅读器识别问题

iText7 pdfHTML模块默认会将通过position: running配置注入到页边距区域的页眉、页脚内容标记为PDF Artifact（装饰性非内容元素），不会纳入无障碍标签树，因此屏幕阅读器无法识别。

• 第一步：给页眉添加无障碍语义属性
  给页眉容器补充ARIA语义标记，明确其页眉角色，同时优化冗余标签避免读屏识别错误，修改后的HTML代码如下：

<html>
<head>
    <link rel="stylesheet" href="{...}pdf/css/style.css" type="text/css" />
    <style>
        #header {
            position: running(header);
        }
        @page {
            margin-top: 100px;
            @top-left {
                content: element(header);
            }
        }
    </style>
</head>
<body>
<!-- 补充role和语义描述 -->
<div id="header" role="doc-pageheader" aria-roledescription="页眉">
    <!-- 布局用table加presentation角色避免读屏识别为数据表格 -->
    <table width="100%" role="presentation">
        <!-- 用行高替代空tr减少冗余标签 -->
        <tr style="height: 20px;">
            <td><span class="...">{...}</span></td>
            <td rowspan="2" class="... ..."><span><img src="{...}pdf/images/..." alt="填写图片实际含义说明" /></span></td>
        </tr>
        <tr>
            <td><span class="...">{...}</span></td>
        </tr>
    </table>
</div>
<!-- 其余文档内容 -->
...
</body>
</html>

• 第二步：修改iText7转换配置，关闭running元素的无障碍排除规则
  初始化转换参数时，明确将running元素纳入无障碍标签树，以Java代码为例：

// 初始化转换配置
ConverterProperties properties = new ConverterProperties();
properties.setBaseUri("你的静态资源根路径");
// 关键配置：禁止将running元素排除在标签树之外
properties.setTaggingWorkerFactory(new DefaultTaggingWorkerFactory(false));
// 3.x以下旧版本pdfHTML可改用配置：properties.putProperty(HtmlConverterProperty.IGNORE_RUNNING_ELEMENTS_IN_TAGGING, false);

// 转换时传入配置即可
HtmlConverter.convertToPdf(htmlContent, new FileOutputStream("输出PDF路径.pdf"), properties);

C#版本对应配置为：

ConverterProperties properties = new ConverterProperties();
properties.SetBaseUri("你的静态资源根路径");
properties.SetTaggingWorkerFactory(new DefaultTaggingWorkerFactory(false));
HtmlConverter.ConvertToPdf(htmlContent, new FileStream("输出PDF路径.pdf", FileMode.Create), properties);

• 第三步：补充必要的PDF无障碍元数据
  转换时额外配置文档基础元数据，进一步符合无障碍检测要求：

PdfDocument pdfDoc = new PdfDocument(new PdfWriter("输出PDF路径.pdf"));
pdfDoc.setTagged();
pdfDoc.getCatalog().setLang(new PdfString("zh-CN"));
pdfDoc.getDocumentInfo().setTitle("你的文档实际标题");

如果页眉内容每页完全重复，可根据检测要求补充aria-label="页眉，内容为XXX，每页重复显示"属性，避免屏幕阅读器每页重复播报相同内容时产生冗余。

内容的提问来源于stack exchange，提问作者Falco