BI Publisher PDF模板重复字段ITEM_CD无法循环渲染问题

问题背景 #

使用BI Publisher开发PDF模板报表时，已完成以下配置：

• 配置重复区域起始标记BODY_START
• 配置重复区域结束标记BODY_END
• 配置待重复展示字段ITEM_CD
• 模板左上角添加文档重复元素（document repeat element）标签
• 数据模型校验通过，对应数据集存在2行及以上有效数据
  但最终渲染报表时，ITEM_CD字段仅展示第一行数据，无法按数据行数重复输出。

按优先级排查步骤 #

• 第一步：校验循环标签的路径与格式匹配
  这是90%同类问题的根因：

  1. 核对BODY_START标签内的循环表达式：必须和ITEM_CD所属的直接父分组节点名完全一致，大小写、拼写不能有偏差，不能包含多余空格。例如数据结构中ITEM_CD属于G_ITEM分组，BODY_START的内容必须为<?for-each:G_ITEM?>，不能写根节点路径，也不能写错分组名。
  2. 核对BODY_END标签内容：必须严格为<?end for-each?>，不能有额外字符；位置必须放在待重复内容区域的最末端，和BODY_START处于同一页面层级，不能嵌套在其他表单域内、不能跨文本框放置。
  3. 核对ITEM_CD的字段表达式：如果BODY_START已经声明了循环分组，区域内的字段直接写<?ITEM_CD?>即可，不要写从根节点开始的全路径，否则会固定取第一行数据。

• 第二步：校验PDF表单域属性

  1. 确认BODY_START、BODY_END、ITEM_CD三个表单域的类型均为普通文本域，不能是按钮、签名、条形码等其他域类型。
  2. 域属性不要勾选“只读”“锁定”选项，文本大小不要设置为固定磅值，避免内容溢出被自动隐藏，看起来像是没有重复渲染。
  3. 重复区域内不要放置交互式表单元素（比如可输入文本框、复选框），会打断BI Publisher的循环解析逻辑。

• 第三步：校验文档重复元素标签配置

  1. 左上角的文档重复元素标签，必须正确绑定到BODY_START对应的循环分组，标签位置不能和BODY_START表单域重叠，否则会导致循环标记识别失败。
  2. 先关闭标签的“跨页自动分页”选项，测试单页内循环是否正常，确认循环逻辑生效后再调整分页规则，避免分页配置干扰循环解析。

• 第四步：校验模板缓存与保存格式问题

  1. 编辑PDF模板必须使用Adobe Acrobat官方工具，保存时不要选择“优化PDF”“压缩文档”“减小文件大小”选项，这类操作会破坏BI Publisher依赖的表单域元数据，导致标签无法识别。
  2. 先使用本地BI Publisher Desktop插件加载样本数据预览模板：如果本地预览正常、服务端渲染异常，清空BI Publisher服务端的模板缓存，重新上传模板发布即可；如果本地预览也无法重复，回到前三个步骤重新核对配置。

快速定位技巧 #

在重复区域内新增一个临时测试域，填入表达式<?position()?>后预览：

• 如果预览时序号一直显示1，说明循环标签没有被识别，重点排查BODY_START/BODY_END的配置
• 如果预览时序号正常递增，说明循环逻辑已生效，问题出在ITEM_CD字段本身的路径或属性配置上

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