使用IText pdfHTML转多表头表格HTML为PDF时无障碍功能异常

问题根因 #

你当前使用<div>+CSS浮动模拟的表格不具备语义化属性，iText的pdfHTML组件在解析无障碍标签时，无法正确识别模拟表格的行列层级关系，只会按照DOM元素的块级顺序+CSS布局逻辑解析内容：所有浮动的表头元素会被统一归类到同一块级序列中，因此会出现所有表头优先读取、后续再读取内容的读序错误。

解决方案 #

方案1：替换为语义化表格（最优解） #

直接将模拟的div结构替换为标准HTML表格标签，pdfHTML会自动识别表格结构、匹配表头与单元格的对应关系，自动生成正确的无障碍读序。
改造后的HTML示例代码如下：

<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1">
<style>
table {
  width: 100%;
  border-collapse: collapse;
}
th, td {
  width: 33.33%;
  padding: 10px;
  height: 300px;
  text-align: left;
}
th {
  font-weight: bold;
  font-size: 1.5em;
}
</style>
</head>
<body>

<h2>第一个表格</h2>
<table>
  <tr>
    <th style="background-color:#aaa;">Column 1</th>
    <th style="background-color:#bbb;">Column 2</th>
    <th style="background-color:#ccc;">Column 3</th>
  </tr>
  <tr>
    <td style="background-color:#aaa;">Some text..</td>
    <td style="background-color:#bbb;">Some text..</td>
    <td style="background-color:#ccc;">Some text..</td>
  </tr>
</table>

<h2>第二个表格</h2>
<table>
  <tr>
    <th style="background-color:#aaa;">2nd table Column 1</th>
    <th style="background-color:#bbb;">2nd table Column 2</th>
    <th style="background-color:#ccc;">2nd table Column 3</th>
  </tr>
  <tr>
    <td style="background-color:#aaa;">Some text..</td>
    <td style="background-color:#bbb;">Some text..</td>
    <td style="background-color:#ccc;">Some text..</td>
  </tr>
</table>

</body>
</html>

方案2：给div结构添加ARIA无障碍角色（无需调整原HTML结构时使用） #

如果无法修改原有div表格的结构，给对应的div添加ARIA角色属性，辅助pdfHTML识别表格结构：

• 包裹整个表格的外层div添加role="table"
• 行div添加role="row"
• 表头元素添加role="columnheader"
• 内容单元格添加role="cell"
  同时需要给每个单元格添加aria-colindex属性标注列序号。

Java端转换配置 #

转换时必须正确配置pdfHTML的无障碍参数，保证标签生成逻辑正确，示例代码如下：

import com.itextpdf.html2pdf.ConverterProperties;
import com.itextpdf.html2pdf.HtmlConverter;
import com.itextpdf.kernel.pdf.PdfWriter;
import com.itextpdf.kernel.pdf.PdfDocument;
import com.itextpdf.kernel.pdf.PdfViewerPreferences;
import java.io.FileInputStream;
import java.io.FileOutputStream;
import java.io.IOException;

public class AccessiblePdfConvert {
    public static void main(String[] args) throws IOException {
        // 配置转换属性
        ConverterProperties properties = new ConverterProperties();
        // 开启打标签（无障碍PDF必须开启）
        properties.setTagged(true);
        // 开启ARIA属性识别
        properties.setImplicitFlush(false);
        
        PdfWriter writer = new PdfWriter("output.pdf");
        PdfDocument pdfDoc = new PdfDocument(writer);
        // 标记为无障碍PDF
        pdfDoc.setTagged();
        // 设置PDF/UA合规标识
        pdfDoc.getCatalog().setViewerPreferences(new PdfViewerPreferences().setDisplayDocTitle(true));
        pdfDoc.getDocumentInfo().setTitle("无障碍PDF");
        
        HtmlConverter.convertToPdf(new FileInputStream("input.html"), pdfDoc, properties);
        pdfDoc.close();
    }
}

完成上述配置后，生成的PDF就会按照表格的正确读序读取内容。

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