如何为Jasper Reports添加自定义标签/ID并通过PDFBox解析？

以下是几种经过验证的可行方案，可直接在Jasper模板中配置，让PDFBox能准确识别自定义标签/ID：

方案1：使用Jasper原生PDF自定义属性 #

Jasper Reports支持给元素添加PDF级别的自定义属性，这些属性会被嵌入到PDF的结构元素字典中，可被PDFBox直接读取。

• 模板配置步骤：
  选中目标元素（如标题、表格），在属性面板中添加自定义属性，键名需以net.sf.jasperreports.export.pdf.custom.property.为前缀，比如：

  键：net.sf.jasperreports.export.pdf.custom.property.test-id
  值：report-header-001
  

• PDFBox解析代码：
  遍历PDF的标记内容树，获取对应元素的自定义属性：

  // 初始化文档
  PDDocument doc = PDDocument.load(new File("report.pdf"));
  PDMarkedContentExtractor extractor = new PDMarkedContentExtractor();
  List<PDMarkedContent> markedContents = extractor.extract(doc);
  
  // 遍历查找自定义ID
  for (PDMarkedContent mc : markedContents) {
      COSDictionary props = mc.getProperties();
      if (props != null && props.containsKey("test-id")) {
          String customId = props.getString("test-id");
          // 处理识别到的ID
          System.out.println("找到自定义ID：" + customId);
      }
  }
  doc.close();
  

方案2：复用PDF标记的Alt文本字段 #

如果不想配置复杂的自定义属性，可以直接把自定义ID嵌入到元素的Alt文本中，通过约定格式区分普通描述和标识。

• 模板配置步骤：
  给目标元素设置net.sf.jasperreports.export.pdf.tag.alt属性，格式可以是[test-id:order-table-002] 订单详情表，或者直接用ID作为Alt文本（如果不需要可读性）。

• PDFBox解析代码：
  读取元素的Alt文本并提取ID：

  for (PDMarkedContent mc : markedContents) {
      PDPropertyList props = mc.getProperties();
      if (props instanceof PDPropertyDictionary) {
          PDPropertyDictionary propDict = (PDPropertyDictionary) props;
          String altText = propDict.getAlt();
          if (altText != null && altText.startsWith("[test-id:")) {
              String customId = altText.substring(9, altText.indexOf("]"));
              System.out.println("提取到自定义ID：" + customId);
          }
      }
  }
  

方案3：扩展PDF结构元素属性 #

通过Jasper的PDF标记属性配置，直接给结构元素添加自定义字典条目，这种方式更灵活，适合需要多个自定义字段的场景。

• 模板配置步骤：
  给元素添加net.sf.jasperreports.export.pdf.tag.properties属性，值为自定义键值对，比如：

  customId=invoice-footer-003;module=payment
  

• PDFBox解析代码：
  从结构元素的属性字典中直接读取自定义键：

  PDStructTreeRoot structRoot = doc.getDocumentCatalog().getStructTreeRoot();
  if (structRoot != null) {
      // 递归遍历结构树
      traverseStructElements(structRoot.getChildren(), "");
  }
  
  // 递归遍历方法
  private static void traverseStructElements(List<PDStructElement> elements, String parentId) {
      for (PDStructElement elem : elements) {
          COSDictionary dict = elem.getCOSObject();
          if (dict.containsKey("customId")) {
              String customId = dict.getString("customId");
              System.out.println("找到结构元素ID：" + customId);
          }
          traverseStructElements(elem.getChildren(), elem.getRole());
      }
  }
  

方案4：嵌入隐藏文本标识 #

如果上述方案都无法满足需求，可以在目标元素旁添加一个隐藏文本框，用特定格式的内容作为标识，这种方式兼容性最好，不受Jasper版本限制。

• 模板配置步骤：

  1. 添加一个文本框，内容为[test-id:customer-info-004]
  2. 设置文本框的字体大小为0，或者字体颜色与背景色完全一致
  3. 在PDF导出属性中设置net.sf.jasperreports.export.pdf.tag.type=Artifact，避免影响文档结构

• PDFBox解析代码：
  遍历PDF中的所有文本，过滤出符合格式的隐藏标识：

  PDFTextStripper stripper = new PDFTextStripper();
  String fullText = stripper.getText(doc);
  Pattern pattern = Pattern.compile("\\[test-id:(.*?)\\]");
  Matcher matcher = pattern.matcher(fullText);
  while (matcher.find()) {
      String customId = matcher.group(1);
      System.out.println("找到隐藏标识ID：" + customId);
  }
  

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