使用列表
概述
本指南展示了在 Aspose.Words FOSS for .NET 中如何表示和控制编号列表和项目符号列表。List 是一个可重复使用的列表定义,供使用它的每个段落共享,ListFormat 是单个段落引用列表及其当前层级的方式,ListLevel 保存列表中某一层级的实际编号或项目符号格式。
列表对象和 ListCollection
List 表示一个列表定义——文档可对多个段落应用的编号规则。List.ListId 用于标识它,List.IsMultiLevel 报告它是否定义了多个层级,List.ListLevels 返回一个 ListLevelCollection,其中包含该列表每个层级的一个 ListLevel。List.IsListStyleDefinition 和 IsListStyleReference 区分自行定义格式的列表与通过链接的 Style(可通过 List.Style 获得)引用格式的列表。每个文档的列表可通过 Document.Lists 访问,后者返回一个 ListCollection:ListCollection.Add(listTemplate) 从 Word 预定义的 ListTemplate 格式创建新列表,Add(listStyle) 从 Style 创建列表,AddSingleLevelList(listTemplate) 创建单层变体,AddCopy(srcList) 复制现有列表——在希望段落拥有独立编号(重新开始)而不是共享同一计数器时非常有用。ListCollection.GetListByListId(listId) 检索特定列表,Count 报告文档中列表的数量。
使用 ListFormat 将列表应用于段落
ListFormat 可从段落的格式中获取,控制段落所属的列表及其层级。ListFormat.List 是段落使用的 List,ListFormat.ListLevelNumber 是该列表中的零基层级;IsListItem 报告段落是否属于任何列表。ApplyBulletDefault() 和 ApplyNumberDefault() 在一次调用中为段落应用 Word 默认的项目符号或编号列表格式,RemoveNumbers() 移除列表格式,ListIndent()/ListOutdent() 将段落向列表更深层或更浅层移动——这与在列表段落开头按 Tab 或 Shift+Tab 时 Word 执行的操作相同。
列表层级与编号样式
ListLevel 保存列表一级的格式:NumberStyle(一种 NumberStyle 枚举值,例如阿拉伯数字或罗马数字),NumberFormat(将数字与文字(如句点或括号)组合的格式字符串),StartAt(起始数字),以及 RestartAfterLevel(哪个更高层级的递增会重新启动此层的计数器)。Alignment(一个 ListLevelAlignment 值:Left、Center、Right)和 TrailingCharacter(一个 ListTrailingCharacter 值:Tab、Space、Nothing)控制标签相对于段落文本的位置和分隔方式,配合 TabPosition、NumberPosition、TextPosition 实现精确布局。IsLegal 强制使用法律式编号(始终阿拉伯数字,无论 NumberStyle 如何),且 LinkedStyle 将该层级关联到段落 Style。对于图片项目符号,CreatePictureBullet() 和 DeletePictureBullet() 管理 ImageData 项目符号图像,ListLevel.Font 设置数字或项目符号字符本身的格式。ListLevel.GetEffectiveValue(index, numberStyle, customNumberStyleFormat) 计算编号序列中给定位置的实际标签值。
列表标签和预定义模板
ListLabel 描述特定列表项实例的呈现标签——LabelString 是 Word 显示的文字(例如 “3.” 或 “•”),LabelValue 是底层的数值,Font 是标签的格式。ListTemplate 是 Word 预定义列表格式的枚举(项目符号样式如 BulletDefault、BulletDisk、BulletCircle、BulletSquare、BulletDiamonds,以及编号格式),可与 ListCollection.Add(listTemplate) 一起使用,以从内置格式开始,而不是逐属性构建。
技巧与最佳实践
- 当一组新的段落需要独立重新开始的列表编号时,请使用
ListCollection.AddCopy(srcList),而不是重复使用已经附加到其他段落的List。 - 对于标准列表,建议使用
ListFormat.ApplyNumberDefault()/ApplyBulletDefault(),而不是手动配置每个ListLevel属性。 - 在直接修改列表格式之前,先检查
List.IsListStyleReference与IsListStyleDefinition的区别——引用样式的列表格式可能由其关联的Style控制。 - 在嵌套列表上显式设置
RestartAfterLevel,而不是依赖默认的重新启动行为,以便在特定大纲层级需要重置编号时生效。 - 使用
ListFormat.ListIndent()/ListOutdent()将段落在列表层级之间移动,而不是直接设置ListLevelNumber,因为这些方法在内部保持段落的列表格式一致。
常见问题
| 问题 | 原因 | 修复 |
|---|---|---|
| 两个段落应独立编号,但继续相同的序列 | 两个段落的 ListFormat.List 都指向同一个共享的 List 对象 | 通过 ListCollection.AddCopy(srcList) 为第二段落提供独立的列表,而不是复用相同的 List |
| 自定义编号格式字符串未按预期渲染 | ListLevel.NumberFormat 与该层级的 NumberStyle 的预期模式不匹配 | 验证 NumberFormat 和 NumberStyle 在正在编辑的层级中保持一致 |
| 在通过程序更改层级后,列表缩进看起来不正确 | ListLevelNumber 被直接设置,未更新相关的位置信息属性 | 使用 ListFormat.ListIndent()/ListOutdent() 而不是直接设置 ListLevelNumber |
| 图片项目符号未显示 | 未为该层级创建图片项目符号,或默认的文本项目符号格式仍然处于激活状态 | 在移除文本项目符号格式之前,调用 ListLevel.CreatePictureBullet() 并提供图像数据 |
FAQ
List 和 ListFormat 有何区别?
List 是在段落之间共享的可重复使用的编号/项目符号定义;ListFormat 是针对每个段落的——它通过 ListFormat.List 和 ListLevelNumber 指向特定段落使用的 List 以及所在的层级。
我如何检查段落是否属于列表?
读取段落格式中的 ListFormat.IsListItem;如果 true,则 ListFormat.List 和 ListLevelNumber 描述它所属的列表和层级。
我如何让新列表独立于现有列表,从 1 开始编号?
使用 ListCollection.AddCopy(srcList) 创建列表定义的独立副本,然后将该副本应用于新段落——而不是重复使用原始的 List,因为那样会继续使用相同的计数器。
我该如何从头创建项目符号列表或编号列表?
使用 ListFormat.ApplyBulletDefault() 或 ApplyNumberDefault() 以获得 Word 的默认格式,或者使用带有 ListTemplate 值的 ListCollection.Add(listTemplate),从 Word 预定义的格式之一开始,并在此基础上自定义生成的 List.ListLevels。
我该如何控制数字格式,例如使用 “1)” 而不是 “1.”?
在相关层级上将 ListLevel.NumberFormat 设置为所需的格式字符串,同时将 NumberStyle 设置为数字样式本身。
API Reference 摘要
| 类/方法 | 描述 |
|---|---|
List | 可重用的列表(编号/项目符号)定义 |
ListCollection | 文档中所有列表的集合 |
ListCollection.Add(listTemplate) / AddCopy(srcList) | 从预定义模板创建列表,或复制现有列表 |
ListFormat | 对每段的 List 以及当前级别的引用 |
ListFormat.ApplyBulletDefault() / ApplyNumberDefault() | 对段落应用默认的项目符号或编号格式 |
ListLevel | 对 List 的单级编号/项目符号格式 |
ListLevel.NumberStyle / NumberFormat | 该层级的数字样式和格式字符串 |
ListLabel | 特定列表项的渲染标签(文本和值) |
ListTemplate | Word 预定义的列表格式枚举 |