XSL-FO 输出（保姆级教程）

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

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

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

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

前言

在数字化时代，数据的呈现方式直接影响用户体验和业务效率。无论是生成销售报告、打印合同，还是输出技术文档，开发者常常需要将结构化的数据转化为美观、可打印的格式化文件。XSL-FO 输出（XSL Formatting Objects）正是解决这一需求的利器。它通过 XML 语言定义文档布局规则，结合 XSLT 转换技术，将原始数据转化为 PDF、PostScript 等格式，被广泛应用于企业级报表生成、出版物排版等领域。

本文将从零开始讲解 XSL-FO 的核心概念、工作流程，并通过实际案例演示如何用代码实现输出。无论你是刚接触 XML 的编程新手，还是希望深入掌握格式化技术的开发者，都能通过本文掌握这一工具的实用技能。

核心概念：理解 XSL-FO 的基础

1. XML、XSLT 与 XSL-FO 的关系

XSL-FO 是 XML 样式表语言（XSL）的一部分，与 XSLT（XSL Transformations）共同构成完整的文档处理流程：

• XML：存储原始数据（如订单信息、用户数据）。
• XSLT：将 XML 数据转换为 XSL-FO 格式的中间文件。
• XSL-FO：定义文档的布局规则（如字体、边距、表格样式）。

可以将这一流程比喻为“厨师做菜”：

• XML 是食材（原材料），XSLT 是菜谱（转换规则），XSL-FO 是摆盘设计（格式化规范），最终生成的 PDF 就是成品菜肴。

2. XSL-FO 的核心元素

XSL-FO 文档由一系列“对象”（Objects）构成，每个对象对应文档中的一个元素。以下是最常用的几个对象：

• <fo:root>：文档根元素，包含布局主机制。
• <fo:layout-master-set>：定义页面模板（如页眉、页脚）。
• <fo:page-sequence>：表示一组连续的页面。
• <fo:flow>：放置文本、表格等主要内容。

示例结构：

<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
  <fo:layout-master-set>
    <fo:simple-page-master master-name="default-page">
      <!-- 定义页面尺寸、边距等 -->
    </fo:simple-page-master>
  </fo:layout-master-set>
  <fo:page-sequence master-reference="default-page">
    <fo:flow flow-name="xsl-region-body">
      <!-- 文本内容 -->
    </fo:flow>
  </fo:page-sequence>
</fo:root>

工作流程：从 XML 到 PDF 的转换

1. 步骤分解

1. 准备 XML 数据：将原始数据整理为 XML 格式。例如，一个订单的 XML 可能如下：

   <order>
     <customer>张三</customer>
     <items>
       <item>
         <name>笔记本电脑</name>
         <price>5999</price>
       </item>
     </items>
   </order>
   

2. 编写 XSLT 转换文件：将 XML 数据映射到 XSL-FO 的结构中。例如，提取订单中的客户信息和商品列表。
3. 生成 XSL-FO 文件：通过 XSLT 处理器（如 Saxon）将 XML 和 XSLT 合并，输出 XSL-FO 格式的中间文件。
4. 渲染为 PDF：使用 XSL-FO 处理器（如 Apache FOP）将 XSL-FO 文件转换为最终的 PDF。

2. 工具选择与配置

• 处理器推荐：
  • Apache FOP：开源工具，支持 XSL-FO 1.1 标准，适合 Java 环境。
  • Antenna House：商业工具，支持更高级的排版功能，适合复杂文档需求。
• 开发环境搭建：
  以 Apache FOP 为例，需在项目中引入其依赖库，并通过 Java API 或命令行执行转换：

  fop -xml input.xml -xsl transform.xsl -pdf output.pdf
  

实战案例：生成订单 PDF

案例背景

假设我们需要为电商平台生成一份包含客户信息、商品列表和总计的订单 PDF。

1. XML 数据准备

订单数据保存为 order.xml：

<?xml version="1.0" encoding="UTF-8"?>
<order id="ORD-12345">
  <customer>
    <name>李四</name>
    <email>li@example.com</email>
  </customer>
  <items>
    <item>
      <product_id>ITM-001</product_id>
      <name>无线耳机</name>
      <price>299</price>
      <quantity>2</quantity>
    </item>
    <item>
      <product_id>ITM-002</product_id>
      <name>蓝牙音箱</name>
      <price>499</price>
      <quantity>1</quantity>
    </item>
  </items>
  <total>1097</total>
</order>

2. 编写 XSLT 转换文件

创建 transform.xsl，将 XML 数据映射到 XSL-FO 结构：

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:fo="http://www.w3.org/1999/XSL/Format">

  <!-- 定义页面模板 -->
  <xsl:template match="/">
    <fo:root>
      <fo:layout-master-set>
        <fo:simple-page-master master-name="order-page">
          <fo:region-body margin="2cm"/>
          <fo:region-before extent="3cm"/>
          <fo:region-after extent="1.5cm"/>
        </fo:simple-page-master>
      </fo:layout-master-set>

      <fo:page-sequence master-reference="order-page">
        <fo:static-content flow-name="xsl-region-before">
          <fo:block text-align="center" font-size="14pt">
            订单详情
          </fo:block>
        </fo:static-content>

        <fo:flow flow-name="xsl-region-body">
          <fo:block font-size="12pt" space-before="12pt">
            <fo:inline font-weight="bold">客户姓名：</fo:inline>
            <xsl:value-of select="/order/customer/name"/>
          </fo:block>

          <!-- 表格展示商品列表 -->
          <fo:table table-layout="fixed" width="100%">
            <fo:table-column column-width="proportional-column-width(1)"/>
            <fo:table-column column-width="proportional-column-width(2)"/>
            <fo:table-column column-width="proportional-column-width(1)"/>
            <fo:table-column column-width="proportional-column-width(1)"/>

            <fo:table-header>
              <fo:table-row background-color="#f0f0f0">
                <fo:table-cell>
                  <fo:block>商品ID</fo:block>
                </fo:table-cell>
                <fo:table-cell>
                  <fo:block>名称</fo:block>
                </fo:table-cell>
                <fo:table-cell>
                  <fo:block>单价</fo:block>
                </fo:table-cell>
                <fo:table-cell>
                  <fo:block>数量</fo:block>
                </fo:table-cell>
              </fo:table-row>
            </fo:table-header>

            <fo:table-body>
              <xsl:for-each select="/order/items/item">
                <fo:table-row>
                  <fo:table-cell>
                    <fo:block><xsl:value-of select="product_id"/></fo:block>
                  </fo:table-cell>
                  <fo:table-cell>
                    <fo:block><xsl:value-of select="name"/></fo:block>
                  </fo:table-cell>
                  <fo:table-cell>
                    <fo:block><xsl:value-of select="price"/></fo:block>
                  </fo:table-cell>
                  <fo:table-cell>
                    <fo:block><xsl:value-of select="quantity"/></fo:block>
                  </fo:table-cell>
                </fo:table-row>
              </xsl:for-each>
            </fo:table-body>
          </fo:table>

          <fo:block space-before="24pt" font-weight="bold">
            总计：¥<xsl:value-of select="/order/total"/>
          </fo:block>
        </fo:flow>
      </fo:page-sequence>
    </fo:root>
  </xsl:template>
</xsl:stylesheet>

3. 执行转换并验证结果

使用 Apache FOP 命令行工具生成 PDF：

fop -xml order.xml -xsl transform.xsl -pdf order.pdf

最终输出的 PDF 将包含：

• 标题栏“订单详情”
• 客户信息
• 商品表格（ID、名称、单价、数量）
• 底部总计金额

常见问题与解决方案

1. 表格内容溢出页面

现象：表格列宽设置不当，导致内容被截断或换行异常。
解决方案：

• 使用 proportional-column-width 动态分配列宽，例如：

  <fo:table-column column-width="proportional-column-width(2)"/>
  

• 调整 <fo:table> 的 width="100%" 以适配页面。

2. 图片插入失败

原因：图片路径或格式不支持（如需绝对路径或特定文件类型）。
解决方案：

• 使用 <fo:external-graphic> 标签，并确保图片路径正确：

  <fo:block>
    <fo:external-graphic src="url('logo.png')" content-height="2cm"/>
  </fo:block>
  

• 将图片放在与 XSL-FO 文件相同的目录中，或使用绝对路径。

3. 多页文档分页问题

现象：长文本或表格跨页时布局混乱。
解决方案：

• 在 <fo:flow> 中添加分页控制：

  <fo:block break-before="page">新页面内容</fo:block>
  

• 使用 <fo:page-sequence> 的 format 属性自定义页码格式（如“1, 2, 3”）。

结论

XSL-FO 输出技术为开发者提供了强大的文档格式化能力，尤其在需要生成标准化、可打印文件的场景中不可或缺。通过本文的案例演示，读者可以掌握从 XML 数据到 PDF 的完整流程，并通过调整 XSL-FO 的样式参数实现复杂排版需求。

对于初学者，建议从简单模板开始实践，逐步尝试表格、图片、分页等高级功能；中级开发者则可深入研究 Apache FOP 的配置参数或探索 Antenna House 等工具的高级特性。随着对 XSL-FO 的熟练掌握，你将能够高效应对各类文档生成任务，为业务系统提供更专业的输出支持。

通过本文的讲解，希望读者能对 XSL-FO 输出 有清晰的认知，并在实际项目中灵活运用这一技术。