PrimeFaces 8升级至10后PanelGrid报缺少p:row错误的原因

升级PrimeFaces 8.0到10.0.0版本时触发的报错信息如下：

"PanelGrid "..." without a 'columns' attribute expects at least one <p:row> element."

异常抛出位置为PanelGridRenderer.java类的第207-210行，以下是该版本变更的目的、作用和问题根因：

版本变更的目的与作用 #

这个报错对应的校验规则是PrimeFaces 10.0版本新增的组件合规性校验，核心目的是解决8.0及更早版本中p:panelGrid容错逻辑带来的隐性问题：

• 旧版本中，只要p:panelGrid内有子内容，哪怕既没配置columns属性、也没有写<p:row>子标签，渲染器也会默认按单列模式强行渲染，不会抛出任何异常
• 这种静默容错会导致很多不规范写法被掩盖，开发者经常遇到表格排版错位、DOM结构破损的问题，很难快速定位到是组件属性漏写导致的
• 10.0版本直接移除了这个不合理的兜底逻辑，在渲染前增加前置校验，从渲染阶段就拦截不规范的组件用法，避免生成无效的页面结构。

报错触发的根本原因 #

异常对应PanelGridRenderer.java中207-210行的校验分支，只要同时满足以下两个条件就会触发报错：

1. 当前渲染的<p:panelGrid>标签上没有显式配置columns属性
2. 渲染器扫描该组件的直接子节点时，没有找到任何有效的<p:row>元素

之前在8.0版本下代码能正常运行，本质是旧版本的容错逻辑把代码里的不规范写法掩盖了，升级后校验规则收紧才把问题暴露出来。常见的不规范写法包括：

• 静态编写p:panelGrid时漏写了columns属性，旧版本默认按1列渲染没有触发问题
• 动态渲染场景下的条件判断逻辑有漏洞，特定分支下没有生成<p:row>子节点
• 把<p:row>标签嵌套在了其他容器组件（比如带渲染判断的<p:outputPanel>、<ui:fragment>）内部，导致p:panelGrid无法直接扫描到<p:row>子元素

修复方向 #

• 固定列数的常规表格，直接给p:panelGrid补上对应值的columns属性即可通过校验
• 自定义行结构的表格，确保<p:row>是p:panelGrid的直接子节点，不要被中间容器包裹
• 动态生成内容的场景，检查渲染条件分支，保证组件渲染时至少存在一个有效<p:row>，或者直接配置columns属性走自动列布局模式

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