引言：XSL-FO 列表的重要性与应用场景
XSL-FO（Extensible Stylesheet Language Formatting Objects）是一种基于XML的页面描述语言，主要用于将XML文档转换为PDF、PostScript等格式的输出。在文档排版中，列表和编号是组织信息、增强可读性的核心元素。无论是技术手册中的步骤说明、法律文件中的条款枚举，还是学术论文中的多级目录，列表样式都扮演着关键角色。
然而，XSL-FO的列表处理并非直观易用。它依赖于
fo:list-block
、
fo:list-item
等元素的嵌套结构，与CSS的列表模型有显著差异。许多开发者面临自定义符号（如特殊图标或混合符号）和格式控制（如缩进、对齐）的难题，尤其在多级嵌套场景下，容易出现编号错乱或布局崩溃的问题。
本文将从基础语法入手，逐步深入到多级嵌套的实战技巧，并重点解决自定义符号与格式控制的难题。我们将结合详细的XML/XSL-FO代码示例，提供可直接复用的解决方案。通过本文，您将掌握如何高效构建复杂列表，确保输出文档的专业性和一致性。
1. XSL-FO 列表基础语法
XSL-FO的列表基于
fo:list-block
元素，它定义了一个列表容器。每个列表项由
fo:list-item
组成，而
fo:list-item-label
和
fo:list-item-body
分别处理标签（如编号或符号）和主体内容。这种结构允许精确控制标签的宽度、对齐和缩进。
1.1 核心元素概述
fo:list-block
：列表的根元素，支持属性如
provisional-distance-between-starts
（标签与主体间的距离）和
provisional-label-separation
（标签间的间距）。
fo:list-item
：单个列表项，包含标签和主体。
fo:list-item-label
：标签部分，通常放置编号或符号。
fo:list-item-body
：主体部分，放置文本内容。
1.2 简单有序列表示例
假设我们有一个简单的有序列表，使用阿拉伯数字编号。以下是一个基础的XSL-FO代码片段：
解释
：
provisional-distance-between-starts=”2em”
设置标签（如”1.“）与主体文本的起始距离为2em，确保对齐。
provisional-label-separation=”0.5em”
设置标签间的间距。
每个
fo:block
用于块级文本，确保换行和格式。
输出效果：标签右对齐，主体左对齐，形成标准的有序列表。
1.3 无序列表示例
对于无序列表，使用符号如圆点（•）。代码如下：
关键点
：
使用
font-family=”Symbol”
来显示特殊字符（如•），确保字体支持。
如果符号不显示，可使用Unicode编码：
（•的Unicode）。
这些基础语法是构建复杂列表的基石，但实际应用中，我们需要XSLT来动态生成编号和嵌套。
2. 编号样式：从静态到动态生成
静态编号适合简单场景，但动态生成更灵活，尤其在XSLT中使用
xsl:number
元素。XSL-FO本身不直接处理编号逻辑，而是依赖XSLT预处理。
2.1 使用 xsl:number 生成编号
xsl:number
可以根据上下文生成序列号，支持格式化如”1.1”、”A.“等。
示例：XSLT转换生成有序列表
假设XML源文件如下：
XSLT代码：
输出解释
：
position()
获取当前项的位置。
format=”1.”
生成”1.“、”2.“等格式。
结果：动态编号，适应任意数量的
。
2.2 高级编号格式
罗马数字
：
format=”i.”
生成 i., ii., iii.。
字母
：
format=”A.”
生成 A., B.。
嵌套编号
：见第3节。
自定义格式控制
：通过
font-weight
、
color
等属性美化标签。
2.3 常见问题与解决
编号重置
：在多列表中，使用
xsl:number
的
level=”any”
或
count
属性控制重置。
跳过编号
：使用
xsl:number
的
from
属性指定起始点。
3. 多级嵌套实战技巧
多级列表（如1.1、1.1.1）是文档排版的难点，需要递归模板和精确的缩进控制。XSL-FO通过嵌套
fo:list-block
实现，但需注意距离计算以避免重叠。
3.1 基础多级结构
嵌套列表通过在
fo:list-item-body
中放置另一个
fo:list-block
实现。
示例：二级列表
关键技巧
：
增加内层
provisional-distance-between-starts
（如2.5em）以提供额外缩进。
使用
margin-left
在
fo:block
中微调：
。
3.2 使用 XSLT 实现动态多级嵌套
对于复杂文档，使用递归模板处理树状结构。
XML源示例
：
：
输出与技巧
：
xsl:number level=”multiple”
生成多级编号如”1.1.“。
递归确保无限嵌套。
缩进控制：内层
provisional-distance-between-starts
递增（2em → 3em），并用
margin-left
微调。
实战提示：测试时使用FOP或Antenna House渲染，检查PDF输出的缩进一致性。如果编号重叠，增加
space-after
属性：
。
3.3 性能优化
避免过深层嵌套（>5级），否则PDF渲染慢。
使用
keep-together
属性防止分页断开：
。
4. 自定义符号与格式控制难题解决
自定义符号（如箭头、图标或混合符号）和格式控制（如颜色、字体、对齐）是XSL-FO列表的高级需求。难题在于：符号不统一、缩进错位、跨级格式不一致。
4.1 自定义符号：从Unicode到外部图像
Unicode符号
：简单高效，但字体依赖。
示例：混合符号列表。
技巧
：使用
font-family
指定字体，确保PDF嵌入。Unicode示例：
（✓）。
外部图像符号
：对于复杂图标，使用
fo:external-graphic
。
难题解决
：图像路径需绝对或相对正确；使用
scaling=”uniform”
保持比例。如果图像不显示，检查XSL-FO处理器的图像支持（如FOP需配置）。
混合符号
：结合文本和图像。
4.2 格式控制：对齐、颜色与间距
标签对齐
：默认右对齐，使用
text-align
调整。
颜色与字体
：全局或局部应用。
间距与缩进控制
：
space-before
和
space-after
：控制列表前后间距。
自定义缩进：使用
margin-left
或
start-indent
。
多级格式难题解决
：为每级定义样式表（XSLT变量）。
在模板中动态应用：
provisional-distance-between-starts=”{$level2-indent}”
。
4.3 实战：自定义多级混合列表
场景
：一个技术文档，第一级用数字，第二级用字母，第三级用自定义符号（如箭头）。
完整XSL-FO示例
（假设已通过XSLT生成）：
输出效果
：
安装指南
a. 下载软件
→ 检查版本
难题解决总结
：
符号不一致
：统一使用Unicode或嵌入字体（如通过
font-family
指定）。
格式崩溃
：递归增加缩进距离，避免负值；测试多级时用
border
调试：
。
XSLT集成
：始终在XSLT中生成FO，确保动态性。使用
xsl:for-each-group
处理分组编号。
5. 最佳实践与调试技巧
一致性
：定义全局样式变量在XSLT中，避免硬编码。
调试
：使用
fo:block
的
background-color
可视化布局；生成中间FO文件检查。
兼容性
：测试FOP、RenderX等处理器；对于PDF，确保字体子集化以减小文件大小。
性能
：大型列表用
keep-with-next
连接相关项。
通过这些技巧，您可以解决XSL-FO列表的常见痛点，实现专业级文档输出。如果遇到特定处理器问题，参考官方文档或社区资源进一步优化。