XSL-FO page-number 对象（手把手讲解）

💡一则或许对你有用的小广告

欢迎加入小哈的星球 ，你将获得：专属的项目实战(已更新的所有项目都能学习) / 1v1 提问 / Java 学习路线 / 学习打卡 / 每月赠书 / 社群讨论

• 新开坑项目:《Spring AI 项目实战》 正在持续爆肝中，基于 Spring AI + Spring Boot 3.x + JDK 21...， 点击查看 ;
• 《从零手撸：仿小红书（微服务架构）》 已完结，基于 Spring Cloud Alibaba + Spring Boot 3.x + JDK 17...，点击查看项目介绍 ;演示链接： http://116.62.199.48:7070 ;
• 《从零手撸：前后端分离博客项目（全栈开发）》 2 期已完结，演示链接： http://116.62.199.48/ ;

截止目前， 星球 内专栏累计输出 100w+ 字，讲解图 4013+ 张，还在持续爆肝中.. 后续还会上新更多项目，目标是将 Java 领域典型的项目都整一波，如秒杀系统, 在线商城, IM 即时通讯，权限管理，Spring Cloud Alibaba 微服务等等，已有 3700+ 小伙伴加入学习 ，欢迎点击围观

前言

在文档自动化生成和排版领域，XSL-FO page-number 对象是控制文档页码显示的核心工具之一。无论是书籍、报告还是复杂的PDF文档，精准的页码管理直接影响最终输出的可读性和专业性。对于编程初学者和中级开发者来说，理解这一对象的原理与用法，能够显著提升文档生成系统的开发效率。本文将以循序渐进的方式，结合代码示例和实际场景，解析XSL-FO page-number 对象的运作逻辑与最佳实践。

基础概念：什么是 XSL-FO 和 page-number 对象？

XSL-FO 的定位

XSL-FO（Extensible Stylesheet Language Formatting Objects）是一种基于XML的标记语言，用于定义文档的版面布局。它类似于CSS，但更专注于复杂的排版需求，例如分栏、页眉页脚、跨页表格等。page-number 对象则是XSL-FO中用于动态插入当前页码的元素。

类比说明：
可以把XSL-FO想象成一个“文档设计师”，它负责规划文档的每一部分如何呈现。而page-number 对象就像设计师手中的“页码生成器”，根据文档的结构自动计算并插入页码。

page-number 对象的核心功能

• 动态页码显示：根据文档的实际内容长度，自动计算并显示当前页码。
• 格式可定制：支持数字格式（如阿拉伯数字、罗马数字）、起始值、奇偶页不同格式等。
• 位置灵活控制：可嵌入到页眉、页脚、页边距等任意位置。

使用场景与代码示例

场景1：基础页码生成

在最常见的场景中，开发者需要在文档页脚显示简单的阿拉伯数字页码。

代码示例：

<fo:page-sequence master-reference="simple-page-master">  
  <fo:static-content flow-name="xsl.footer">  
    <fo:block text-align="center">  
      Page <fo:page-number/> of <fo:page-number-citation ref-id="end"/>  
    </fo:block>  
  </fo:static-content>  
  <!-- 文档内容 -->  
  <fo:flow flow-name="xsl.body">  
    <fo:block id="end">End of content</fo:block>  
  </fo:flow>  
</fo:page-sequence>  

解析：

• <fo:page-number/> 插入当前页码。
• <fo:page-number-citation ref-id="end"/> 通过引用文档末尾的ID，动态显示总页数。
• 这种写法实现了“当前页/总页数”的常见格式。

场景2：奇偶页不同页码

书籍常采用“奇数页页码在右，偶数页在左”的设计。XSL-FO可通过条件判断实现这一需求。

代码示例：

<fo:layout-master-set>  
  <fo:simple-page-master master-name="odd-page">  
    <!-- 奇数页布局 -->  
    <fo:region-body margin="1in"/>  
    <fo:region-footer margin-bottom="0.5in"/>  
  </fo:simple-page-master>  
  <fo:simple-page-master master-name="even-page">  
    <!-- 偶数页布局 -->  
    <fo:region-body margin="1in"/>  
    <fo:region-footer margin-bottom="0.5in"/>  
  </fo:simple-page-master>  
  <fo:page-sequence-master master-name="book-pages">  
    <fo:repeatable-page-master-alternatives>  
      <fo:conditional-page-master-reference odd-or-even="odd" master-reference="odd-page"/>  
      <fo:conditional-page-master-reference odd-or-even="even" master-reference="even-page"/>  
    </fo:repeatable-page-master-alternatives>  
  </fo:page-sequence-master>  
</fo:layout-master-set>  

在页脚内容中：

<fo:static-content flow-name="xsl.footer">  
  <fo:block text-align="right" margin-right="2cm">  
    <fo:page-number/>  
  </fo:block>  
</fo:static-content>  

关键点：

• 通过odd-or-even属性区分奇偶页。
• 在even-page布局中，可通过调整margin或text-align实现页码位置的左右切换。

进阶技巧：页码重置与条件逻辑

页码重置

在长文档中，章节或附录可能需要从新页开始并重置页码。例如，附录部分从“A-1”开始。

代码示例：

<fo:page-sequence master-reference="main" initial-page-number="1">  
  <!-- 主文档内容 -->  
</fo:page-sequence>  

<fo:page-sequence master-reference="appendix" initial-page-number="1" format="A-1">  
  <!-- 附录内容 -->  
</fo:page-sequence>  

参数说明：

• initial-page-number="1"：将当前page-sequence的起始页码设为1。
• format="A-1"：通过格式字符串指定页码前缀。

条件页码显示

某些场景下，首页可能不需要页码（如封面页）。可通过条件判断跳过特定页面的页码生成。

代码示例：

<fo:static-content flow-name="xsl.footer">  
  <fo:block>  
    <xsl:if test="not($is-first-page)">  
      <fo:page-number/>  
    </xsl:if>  
  </fo:block>  
</fo:static-content>  

逻辑控制：

• 通过XSLT参数$is-first-page判断是否为封面页。
• 使用xsl:if条件语句决定是否渲染页码。

常见问题与解决方案

问题1：页码未显示

可能原因：

• 未在page-sequence中定义static-content（如页眉/页脚）。
• fo:page-number的位置被其他元素覆盖。

解决方案：

<!-- 确保页脚区域存在 -->  
<fo:static-content flow-name="xsl.footer">  
  <fo:block text-align="center">Page <fo:page-number/></fo:block>  
</fo:static-content>  

问题2：页码格式错误

示例场景：希望页码为罗马数字（如“I, II, III”），但实际显示为阿拉伯数字。

修复代码：

<fo:page-number format="i"/>  

参数说明：

• format属性支持多种格式：
  • 1：阿拉伯数字
  • i：小写罗马数字
  • I：大写罗马数字
  • a：小写英文字母

性能优化与最佳实践

避免重复计算页码

在复杂文档中，频繁使用fo:page-number-citation引用总页数可能导致性能下降。建议：

1. 将总页数计算结果缓存到变量中。
2. 仅在必要时使用动态引用。

代码结构化建议

• 将页码样式定义为可复用的模板（Template）。
• 使用命名空间（如xmlns:my="http://example.com/my-namespace"）区分自定义逻辑。

结论

通过本文的讲解，开发者可以掌握XSL-FO page-number 对象的核心功能、常见场景及进阶技巧。无论是基础的页码显示，还是复杂的奇偶页切换、章节页码重置，XSL-FO均提供了灵活且强大的解决方案。建议读者在实际项目中逐步尝试，结合代码示例探索更多可能性。未来，随着文档自动化需求的增加，对XSL-FO的深入理解将成为开发者的一项重要技能。

延伸学习建议：

• 阅读XSL-FO官方文档，理解fo:page-number与其他对象（如fo:marker）的交互逻辑。
• 尝试使用开源工具（如Apache FOP）进行实战练习，观察不同配置的实际效果。