任务列表

Word 复选框列表会转换为 Tiptap 的 taskList 和 taskItem 节点，并且选中状态可以双向保留。导入是可选的，因为不包含任务节点的编辑器无法渲染它们。

所需内容

• 扩展： ConvertKit 会捆绑 TaskList 和 TaskItem。TaskItem 配置为 nested: true，因此导入的子列表仍然有效。
• 配置： 编辑器扩展会为你处理配置。使用 REST API 时，请发送 taskLists: "import"。

支持概览

列表之外的复选框会保持现状。导出的复选框在 Word 中仍然可以交互。下面会分别介绍这两种情况。

导入

使用编辑器扩展或 REST API 开启它。

ImportDocx.configure({
  token: 'your-jwt',
  // 'auto' is the default: it imports task lists when your editor can render
  // them, and leaves them as bullet lists when it cannot.
  taskLists: 'auto',
})

auto 会检查编辑器 schema 中是否同时存在 taskList 和 taskItem。使用 ConvertKit 时它们始终存在，因此 auto 会导入任务列表。传入 'import' 可强制导入，传入 'ignore' 则保留旧行为，将复选框列表导入为项目符号列表或有序列表。

支持识别的复选框

Word 会以多种方式写入复选框，其中三种可以转换：

• Glyph bullets. A box character used as the list bullet in the document's numbering, for example Wingdings U+F06F or the Unicode ballot box U+2610. This is the most common checkbox list in real documents. The ticked state comes from the glyph, so a list drawn with a ticked box imports as checked.
• Content controls. A w14:checkbox control, which is what modern Word inserts and what Tiptap exports. The ticked state comes from the control.
• Legacy form fields. The older Word form-field checkbox. The state comes from the field, falling back to its default when the current value is absent.

A checkbox only becomes a task item when it is the only checkbox in its paragraph and it comes before the text. That is what separates a checklist from a form. A row like Yes ☐ No ☐, or a tick box placed after a sentence, keeps importing as it does today.

Checkmark glyphs such as Wingdings U+F0FC (✔) are deliberately not treated as checkboxes. They are the most common decorative bullet in real documents, so reading them as checkboxes would turn ordinary lists and table tick marks into checklists.

编辑器渲染

TaskList and TaskItem come from ConvertKit, so there is nothing to install. See the TaskList and TaskItem extension pages for their own options and commands.

A task list renders as <ul data-type="taskList"> with <li data-type="taskItem" data-checked="true|false">. Each item holds a <label> with the checkbox and a <div> with the item's content.

ConvertKit ships the layout for these nodes, so the checkbox lines up with where a bullet would sit and item text lines up with bullet and numbered list text. You do not need to add CSS to get a checklist that matches the exported document.

自定义外观

Style the data attributes rather than replacing the layout, so the alignment ConvertKit sets is preserved:

/* A ticked item */
.tiptap ul[data-type='taskList'] li[data-checked='true'] > div > p {
  color: #6b7280;
  text-decoration: line-through;
}

/* The checkbox itself */
.tiptap ul[data-type='taskList'] li > label input {
  accent-color: #7c3aed;
}

To turn the nodes off entirely, or to pass their own options:

ConvertKit.configure({
  taskList: false,
  taskItem: false,
})

导出

Export with the editor extension or the REST API. Both behave the same.

A task item exports as a Word checkbox content control followed by its text. The control stays interactive in Word, so a reader can tick and untick it, and the ticked state you exported is what they see.

Items use Word's List Paragraph style with a hanging indent, so a checkbox list sits at the same indent as a bullet or numbered list in the same document, with the same spacing between rows.

Nested task lists export with the deeper indent Word uses for a nested list. When a task item holds several blocks, the checkbox goes on the first one and the rest are indented to match without a second checkbox.

往返转换

A Word checkbox list imported and exported again comes back as a Word checkbox list with its ticked states intact. The same holds in the other direction: a task list written in the editor, exported, then imported, keeps its items and their states.

Export always writes a content control, not the glyph-bullet shape most existing Word documents use. Both import correctly, so a document that arrives as glyph bullets leaves as content controls.