---
title: "列表"
description: "项目符号列表、有序列表、嵌套列表和任务列表如何在 DOCX 和 Tiptap 之间转换。"
canonical_url: "https://tiptap.zhcndoc.com/conversion/content-types/text-and-formatting/lists"
---

# 列表

项目符号列表、有序列表、嵌套列表和任务列表如何在 DOCX 和 Tiptap 之间转换。

项目符号列表和有序列表在 DOCX 和 Tiptap 之间转换时会保留嵌套结构。DOCX 中的编号格式和起始值在导入过程中不会被保留。

## 你需要了解的内容

- **扩展：** [`ConvertKit`](https://tiptap.zhcndoc.com/conversion/import/docx/convertkit.md) 捆绑了 `BulletList`、`OrderedList`、`ListItem` 和 `ListKeymap`。
- **配置：** 不需要。嵌套在所有管道阶段都可直接使用。

## 支持概览

|                 | 导入                        | 编辑器                                      | 导出   |
| --------------- | ------------------------- | ---------------------------------------- | ---- |
| 项目符号列表          | 支持                        | 支持（ConvertKit）                           | 支持   |
| 有序列表            | 支持                        | 支持（ConvertKit）                           | 部分支持 |
| 编号格式（a/A/i/I/1） | 内部读取用于区分有序列表与项目符号列表，然后丢弃  | OrderedList 扩展的 `type` 属性接受这些值，但导入器不会设置它 | 不保留  |
| 起始编号            | 未从 DOCX 编号中的 `w:start` 提取 | OrderedList 扩展的 `start` 属性受支持，但导入器不会设置它  | 不保留  |
| 嵌套列表            | 支持                        | 支持                                       | 支持   |
| 任务列表            | 不支持                       | 支持（需要 TaskList 扩展）                       | 不支持  |

## 导入

使用 [编辑器扩展](https://tiptap.zhcndoc.com/conversion/import/docx/editor-extension.md) 或 [REST API](https://tiptap.zhcndoc.com/conversion/import/docx/rest-api.md) 导入列表。两者产生的输出完全相同。

转换服务会将所有连续的 DOCX 列表段落分组为列表结构，而不考虑它们的编号 ID。缩进级别（`ilvl`）控制嵌套。导入器只读取 `numFmt` 值来将每个段落分类为项目符号或有序列表项。项目符号样式的编号会生成 `bulletList` 节点。十进制、字母和罗马数字编号都会生成 `orderedList` 节点，但不会进一步区分：在 Word 中以 `A, B, C` 编写的列表和以 `1, 2, 3` 编写的列表，在编辑器中都会作为没有任何属性的相同 `orderedList` 节点进入。Tiptap 的 OrderedList 扩展的 `type` 属性（它会渲染为 `<ol type="a">`）在导入时不会被填充。若想如今端到端保留自定义编号样式，可在内容加载后于编辑器端设置 `type` 属性。

DOCX 编号定义中的 `w:start` 值不会被解析，因此起始编号不会被导入。

## 编辑器渲染

[`BulletList`](https://tiptap.zhcndoc.com/editor/extensions/nodes/bullet-list.md)、[`OrderedList`](https://tiptap.zhcndoc.com/editor/extensions/nodes/ordered-list.md)、[`ListItem`](https://tiptap.zhcndoc.com/editor/extensions/nodes/list-item.md) 和 `ListKeymap` 扩展由 [`ConvertKit`](https://tiptap.zhcndoc.com/conversion/import/docx/convertkit.md) 注册。无需单独安装。

列表使用标准 HTML 元素渲染：项目符号列表使用 `<ul>`，有序列表使用 `<ol>`，列表项使用 `<li>`。如果在 `orderedList` 节点上设置了 `start` 和 `type` 属性，编辑器会将它们渲染为 HTML 属性（例如，`<ol start="5" type="a">`），但 DOCX 导入器不会设置这些属性。

嵌套通过 `listItem` 内容模型实现，它允许在列表项中包含块级内容，包括其他列表。任务列表需要单独的 [`TaskList`](https://tiptap.zhcndoc.com/editor/extensions/nodes/task-list.md) 和 [`TaskItem`](https://tiptap.zhcndoc.com/editor/extensions/nodes/task-item.md) 扩展。

## 导出

使用 [编辑器扩展](https://tiptap.zhcndoc.com/conversion/export/docx/editor-extension.md) 或 [REST API](https://tiptap.zhcndoc.com/conversion/export/docx/rest-api.md) 导出列表。两者对列表的处理完全相同。

项目符号列表和有序列表都会以正确的结构导出为 DOCX。嵌套通过递归增加 DOCX 缩进级别来保留。每个有序列表实例都会获得一个唯一的编号 ID，因此同一文档中的多个列表会独立编号。

> **编号格式和起始值不会被导出:**
>
> 导出转换器不会读取有序列表节点中的 `type` 或 `start` 属性。所有有序列表都会导出为默认的十进制编号（1, 2, 3），而不管编辑器中设置了什么格式。在编辑器中 `type: "a"` 且 `start: 5` 的列表，在 Word 中会导出为标准的 1, 2, 3 列表。

## 任务列表

编辑器支持带有 `checked` 属性的任务列表（`taskList` 和 `taskItem` 节点）。但是，任务列表不属于 DOCX 转换流水线。它们不能从 DOCX 导入，也不会包含在 DOCX 导出结果中。

如果你的编辑器使用任务列表，它们在编辑时会正常工作，但无法通过 DOCX 转换实现往返。