birt 升级至 4.9.0 后，若报表中需在第一页使用「firstmasterpage」、从第二页起统一应用「secondmasterpage」，必须显式为布局容器指定 masterpage 属性并触发页切换——仅声明 master-page 定义或为表格设置属性不足以自动生效。
birt 升级至 4.9.0 后，若报表中需在第一页使用「firstmasterpage」、从第二页起统一应用「secondmasterpage」，必须显式为布局容器指定 masterpage 属性并触发页切换——仅声明 master-page 定义或为表格设置属性不足以自动生效。
在 BIRT 2.5.x 中，主页面（Master Page）行为存在兼容性缺陷，例如首页主页面错误地重复应用于全部页面；而自 BIRT 3.7.1 起，该问题已修复，新版引擎严格遵循“masterPage 属性变更即触发分页并切换模板”的语义逻辑。因此，关键不在于 master-page 的定义是否完整，而在于是否在恰当的布局节点上主动切换 masterPage。
✅ 正确实现方式：通过 <grid> 或 <stack> 显式控制分页与主页面切换
推荐采用 <grid> 容器作为逻辑分隔单元，确保首页内容与后续内容物理隔离，并强制触发页跳转：
<body>
<!-- 第一页：绑定 FirstMasterPage -->
<grid id="firstPageGrid">
<property name="masterPage">FirstMasterPage</property>
<grid-item>
<table name="myTableFirst" id="173">
<!-- 表格内容 -->
</table>
</grid-item>
</grid>
<!-- 强制分页后，启用 SecondMasterPage -->
<grid id="secondPageGrid">
<property name="masterPage">SecondMasterPage</property>
<grid-item>
<table name="myTable" id="217">
<property name="repeatHeader">true</property>
<property name="pageBreakInterval">40</property>
<!-- 其他列定义 -->
</table>
</grid-item>
</grid>
</body>? 原理说明：BIRT 渲染引擎会在 masterPage 属性值发生变化时，自动插入一个隐式分页（page break），从而确保新 master page 从下一页开始生效。直接将 masterPage 属性设在 <table> 上无效，因为表格本身不是“页面上下文切换点”——只有 <grid>、<stack>、<list> 等顶级布局容器才具备该能力。
⚠️ 常见误区与避坑提示
- ❌ 错误做法：仅在 <table> 上设置 masterPage 属性（如原代码中 myTableFirst 和 myTable 的写法），BIRT 不会据此切换页面模板；
- ❌ 忽略首容器显式声明：即使第一个 <grid> 未显式写 masterPage，BIRT 会回退使用默认 master page，导致后续切换失效；
- ❌ 混淆 pageBreakBefore/After 与 masterPage 逻辑：pageBreakAfter="always" 仅控制分页位置，不改变主页面上下文；真正驱动模板切换的是容器级 masterPage 属性变更；
- ✅ 验证技巧：预览时右键 → “View Report Design Source”，检查生成的 PDF/HTML 是否在第二页起 header 文字变为 “Landscape”，且方向为横向（需确认 SecondMasterPage 的 orientation="landscape" 在导出格式中被正确渲染）。
?️ 补充建议：增强可维护性
- 使用 <label> 或 <text> 组件在页眉中动态显示页码（如 <value-of>pageNumber</value-of>），便于调试分页逻辑；
- 若需更精细控制（如奇偶页不同 header），可结合 <simple-master-page> 的 evenPage/oddPage 属性，但本场景中无需启用；
- 务必确认所用 BIRT 运行时版本与设计器版本一致（如 org.eclipse.birt.runtime_4.9.0-20220315），避免因 OSGi 插件兼容性引发静默渲染异常。
升级至 BIRT 4.9.0 后，主页面切换已完全可控且符合预期。核心要诀只有一条：把 masterPage 属性设在布局容器（非数据组件）上，并利用属性变更触发自动分页——这是 BIRT 报表引擎设计的底层契约，也是跨版本迁移中最易忽视却最关键的实践规范。
