列表
项目符号列表和有序列表在 DOCX 和 Tiptap 之间转换,并保留嵌套。导入按照 Word 编号的方式将列表保存在一起,并读取每个有序列表的编号格式和起始编号。
你需要了解的内容
- 扩展:
ConvertKit捆绑了BulletList、OrderedList、ListItem和ListKeymap。 - 配置: 不需要。嵌套在所有管道阶段都可直接使用。
支持概览
| 导入 | 编辑器 | 导出 | |
|---|---|---|---|
| 项目符号列表 | 支持 | 支持 (ConvertKit) | 支持 |
| 有序列表 | 支持 | 支持 (ConvertKit) | 支持 |
| 编号格式 (a/A/i/I/1) | 导入为 numberingFormat,加上用于字母和罗马数字的 type | 由 OrderedListNumbering 绘制(默认关闭)。 OrderedList 扩展的 type 属性也接受这些值 | 仅编辑器扩展,来自已注册的格式 |
| 起始编号 | 当列表不从 1 开始时导入为 start | 支持 OrderedList 扩展的 start 属性 | 仅编辑器扩展 |
| 嵌套列表 | 支持 | 支持 | 支持 |
| 任务列表 | 支持,选择加入 | 支持(ConvertKit) | 支持 |
导入
使用 编辑器扩展 或 REST API 导入列表。两者产生的输出完全相同。
转换服务根据 Word 编号为一个列表的连续列表段落构建一个列表:
- 同一编号 ID (
numId) 上的段落。 - 定义共享
nsid和相同级别的不同编号 ID 上的段落。使用w:startOverride重新启动计数的编号 ID 会启动一个新列表。 - 一个有序列表的项目之间的空段落。人们对他们的评价不断增加,所以他们并没有结束这个名单。每个都留在它前面的项目内,从而保留空白行。
列表项之间有文本的段落(例如标题)结束列表,项目符号或任务列表中的空段落也是如此。缩进级别 (ilvl) 控制嵌套。
项目符号式编号生成 bulletList 节点,十进制、字母和罗马编号生成 orderedList 节点。每个列表的最外面的列表都会获得 OrderedListNumbering 绘制的 numberingFormat,响应会在 numberingFormats 中列出这些格式。对于字母和罗马编号,有序列表还获得 type(a、A、i 或 I),并且当其第一级不从 1 开始时获得 start。
仅当启用 OrderedListNumbering 时,编辑器才会保留 numberingFormat,例如使用 ConvertKit.configure({ orderedListNumbering: true })。默认的 ConvertKit 配置会在加载内容时移除该属性,仅保留 type 和 start。REST 响应始终包含这三个字段。
编辑器渲染
BulletList、OrderedList、ListItem 和 ListKeymap 扩展由 ConvertKit 注册。无需单独安装。
使用标准 HTML 元素渲染列表:用于项目符号列表的 <ul>、用于有序列表的 <ol> 以及用于列表项的 <li>。如果在 orderedList 节点上设置 start 和 type 属性,编辑器会将它们渲染为 HTML 属性(例如 <ol start="5" type="a">)。当 OrderedListNumbering 打开时,列表的编号格式会绘制标记,并从格式自身的起始编号开始计数。
仅在格式注册后,编辑器才会绘制格式标记。启用 OrderedListNumbering 后,ImportDocx 会自动注册导入的格式。使用 REST API 导入后,请将响应中的 numberingFormats 传给 editor.commands.registerNumberingFormats(),参见编辑器运行后添加格式。
嵌套通过 listItem 内容模型实现,它允许在列表项中包含块级内容,包括其他列表。ConvertKit 也会注册 TaskList 和 TaskItem,因此复选框列表无需额外设置即可渲染。
导出
使用编辑器扩展或 REST API 导出列表。两者都支持项目符号列表、有序列表、嵌套列表和任务列表。只有编辑器扩展会保留编号格式和起始编号。
项目符号列表和有序列表均以正确的结构导出到 DOCX。通过递归增加 DOCX 缩进级别来保留嵌套。每个有序列表实例都会收到一个唯一的编号 ID,因此同一文档编号中的多个列表是独立的。具有 linkedStyle 格式的列表是例外,请参见下文。
编辑器扩展按照编辑器显示的方式对有序列表进行编号,但有一个例外:
- 具有
numberingFormat的列表以该格式导出。该扩展从@tiptap-pro/extension-export-docx0.34.0 读取编辑器中注册的格式。请参阅有序列表编号。 - 从版本 0.34.6 开始,不带
numberingFormat的列表从其start编号开始。与编辑器一样,具有格式的列表从格式自身的起始编号开始计数。 - 不导出
type属性。包含type: "a"且不包含numberingFormat的列表导出为 1, 2, 3。 - 例外:
linkedStyle级别的格式是 Word 中整个文档的一个列表。它的列表在 DOCX 中相互延续,而编辑器会重新启动每个列表。使用linkedStyle时检查导出的号码。
REST API 将有序列表导出为 1, 2, 3
/v2/convert/export/docx 端点不读取 numberingFormat、type 或 start。每个有序列表导出的十进制数字从 1 开始。
任务列表
Word 复选框列表会转换为 taskList 和 taskItem 节点,并且选中状态可以双向保留。导入是可选的;当你的 schema 能够渲染这些节点时,编辑器扩展会为你启用该功能。
请参阅任务列表,了解支持哪些复选框形状、如何设置样式,以及包含复选框的有序列表会如何处理。