使用列表

概述

本指南展示了在 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特定列表项的渲染标签(文本和值)
ListTemplateWord 预定义的列表格式枚举

另请参阅

 中文