如何使用PDFBox提取PDF表单域的制表位（Tab）顺序信息

PDF的制表位顺序（tab order）并不直接存储在单个PDField对象中，而是由AcroForm的全局配置或字段布局规则决定。以下是基于PDFBox的可行实现步骤：

1. 优先读取自定义制表位顺序（CO数组） #

如果PDF的AcroForm定义了自定义制表位顺序，相关信息会存储在CO（Cursor Order）数组中，这是最准确的顺序来源：

PDAcroForm acroForm = document.getDocumentCatalog().getAcroForm();
if (acroForm == null) {
    // 无表单域，直接返回
    return;
}

List<PDField> orderedFields = new ArrayList<>();
COSArray coArray = acroForm.getCOSObject().getCOSArray(COSName.CO);

if (coArray != null) {
    // 遍历CO数组，按自定义顺序获取字段
    for (COSBase cosBase : coArray) {
        if (cosBase instanceof COSObject) {
            COSObject cosObj = (COSObject) cosBase;
            PDField field = acroForm.getFieldFromCOSObject(cosObj.getObject());
            if (field != null) {
                orderedFields.add(field);
            }
        }
    }
}

2. 处理默认/布局驱动的制表位顺序 #

如果没有自定义CO数组，需要根据PDF指定的制表位规则排序，常见规则有三种：

按行排序（Row） #

从左到右、从上到下遍历字段（PDF坐标原点在左下角，所以y坐标越大越靠上）：

else {
    String tabOrder = acroForm.getCOSObject().getString(COSName.TAB_ORDER);
    List<PDField> allFields = getAllTerminalFields(acroForm); // 递归获取所有终端字段（含子字段）
    
    if ("Row".equals(tabOrder)) {
        orderedFields = allFields.stream()
            .sorted((f1, f2) -> {
                PDRectangle r1 = getFieldFirstWidgetRect(f1);
                PDRectangle r2 = getFieldFirstWidgetRect(f2);
                // 先按y降序（上方字段优先），再按x升序（左到右）
                int yCompare = Double.compare(r2.getUpperRightY(), r1.getUpperRightY());
                return yCompare != 0 ? yCompare : Double.compare(r1.getLowerLeftX(), r2.getLowerLeftX());
            })
            .collect(Collectors.toList());
    }

按列排序（Column） #

从上到下、从左到右遍历字段：

else if ("Column".equals(tabOrder)) {
        orderedFields = allFields.stream()
            .sorted((f1, f2) -> {
                PDRectangle r1 = getFieldFirstWidgetRect(f1);
                PDRectangle r2 = getFieldFirstWidgetRect(f2);
                // 先按x升序（左列优先），再按y降序（从上到下）
                int xCompare = Double.compare(r1.getLowerLeftX(), r2.getLowerLeftX());
                return xCompare != 0 ? xCompare : Double.compare(r2.getUpperRightY(), r1.getUpperRightY());
            })
            .collect(Collectors.toList());
    }

按Widget创建顺序（Widget，默认规则） #

按表单部件（Widget）在页面中的创建顺序排序，需要遍历页面注释获取：

else { // 默认Widget顺序
        for (PDPage page : document.getPages()) {
            for (PDAnnotation annot : page.getAnnotations()) {
                if (annot instanceof PDAnnotationWidget) {
                    PDField field = ((PDAnnotationWidget) annot).getField();
                    if (field != null && !orderedFields.contains(field)) {
                        orderedFields.add(field);
                    }
                }
            }
        }
    }
}

辅助工具方法 #

需要两个辅助方法处理嵌套字段和获取字段位置：

// 递归获取所有终端字段（排除字段组，只保留可交互的表单域）
private static List<PDField> getAllTerminalFields(PDAcroForm acroForm) {
    List<PDField> terminalFields = new ArrayList<>();
    for (PDField field : acroForm.getFields()) {
        if (field instanceof PDTerminalField) {
            terminalFields.add(field);
        } else {
            terminalFields.addAll(getAllTerminalFields((PDNonTerminalField) field));
        }
    }
    return terminalFields;
}

private static List<PDField> getAllTerminalFields(PDNonTerminalField groupField) {
    List<PDField> terminalFields = new ArrayList<>();
    for (PDField child : groupField.getChildren()) {
        if (child instanceof PDTerminalField) {
            terminalFields.add(child);
        } else {
            terminalFields.addAll(getAllTerminalFields((PDNonTerminalField) child));
        }
    }
    return terminalFields;
}

// 获取字段第一个Widget的位置矩形
private static PDRectangle getFieldFirstWidgetRect(PDField field) {
    if (field instanceof PDTerminalField) {
        List<PDAnnotationWidget> widgets = ((PDTerminalField) field).getWidgets();
        if (!widgets.isEmpty()) {
            return widgets.get(0).getRectangle();
        }
    }
    return new PDRectangle(0, 0, 0, 0);
}

最后映射到HTML tabindex #

遍历排序后的orderedFields，为每个字段设置递增的tabindex值即可：

int tabindex = 1;
for (PDField field : orderedFields) {
    String fieldName = field.getFullyQualifiedName();
    // 这里将fieldName和tabindex映射到HTML表单元素
    System.out.printf("字段[%s]的tabindex为%d%n", fieldName, tabindex++);
}

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