为 DOCX 导出自定义列表编号和项目符号

@tiptap-pro/extension-export-docx 接受一个可选的 编号格式定义 注册表（多级标记样式、标记文本、对齐、缩进和字体），并通过外层 <ol> 或 <ul> 上的属性按列表进行选择。具有匹配 id 的列表会按对应定义导出；没有对应定义的列表则保留其类型对应的默认层级。

当层级使用 baseStyle: 'bullet' 时，格式表示的是字形层级而不是计数器，因此同一个注册表也可以承载装饰性项目符号。请参阅项目符号层级。

此功能为可选启用。未提供 numberingFormats 的使用者不会看到任何行为变化。

提供了什么

面向最终用户的选择器 UI 并不属于这些包；这属于应用层关注点，取决于你的组件库。

快速开始

import { Editor } from '@tiptap/core'
import { ConvertKit, type NumberingFormatDefinition } from '@tiptap-pro/extension-convert-kit'
import { ExportDocx, LevelFormat } from '@tiptap-pro/extension-export-docx'

// 1. 定义你的注册表：单一事实来源，供下面两侧共用。
const MY_FORMATS: NumberingFormatDefinition[] = [
  {
    id: 'decimal-paren',
    levels: [
      { baseStyle: LevelFormat.DECIMAL, textTemplate: '%1)' },
      { baseStyle: LevelFormat.LOWER_LETTER, textTemplate: '%2)' },
      { baseStyle: LevelFormat.LOWER_ROMAN, textTemplate: '%3)' },
    ],
  },
  {
    id: 'outline',
    levels: [
      { baseStyle: LevelFormat.DECIMAL, textTemplate: '%1.' },
      { baseStyle: LevelFormat.DECIMAL, textTemplate: '%1.%2.' },
      { baseStyle: LevelFormat.DECIMAL, textTemplate: '%1.%2.%3.' },
    ],
  },
]

// 2. 通过 ConvertKit 选择启用。传入 `formats` 会生成编辑器预览 CSS，
//    并自动注入；同时用相同的注册表注册 ExportDocx，以便
//    .docx 包含匹配的定义。
const editor = new Editor({
  extensions: [
    ConvertKit.configure({
      // 默认关闭，因此不使用自定义编号的使用者可以保持干净的
      // orderedList schema。传入一个选项对象（或 `true`）即可启用。
      orderedListNumbering: { formats: MY_FORMATS },
    }),
    ExportDocx.configure({
      numberingFormats: MY_FORMATS,
      onCompleteExport: (blob) => {
        /* 下载 blob */
      },
    }),
  ],
})

// 3. 在当前选区以所选格式开始一个编号列表
//    （或者，当已经在列表中时，使用 setOrderedListNumberingFormat 更改其格式）。
editor.chain().focus().toggleOrderedListWithFormat('outline').run()

更喜欢自己管理样式表？那就省略 formats，改为从 generateNumberingFormatCss 注入 CSS。这两种方式会生成相同的标记。

启用有序列表编号

OrderedListNumbering 随 @tiptap-pro/extension-convert-kit 提供，但默认关闭，以便为不使用自定义编号的使用者保持 orderedList schema 的简洁。通过 ConvertKit 选择启用：

ConvertKit.configure({ orderedListNumbering: true })

请传入选项对象而不是 true，以配置三项内容：

ConvertKit.configure({
  orderedListNumbering: {
    // 新建有序列表时开始使用的格式 id。默认为 `null`（普通的 `1. 2. 3.`）。
    defaultFormat: 'outline',
    // 新建项目符号列表时开始使用的格式 id。
    defaultBulletFormat: 'arrows',
    // 传给 ExportDocx 的相同定义。提供后，
    // 会据此生成并自动注入编辑器预览 CSS，
    // 因此屏幕上的标记会与导出结果一致，无需额外接线。
    formats: MY_FORMATS,
  },
})

在这里传入 formats，等同于你自己调用 generateNumberingFormatCss 并注入其结果：按你的设置选择最合适的方式即可。

应用格式

setOrderedListNumberingFormat(id) 命令会在当前选区最外层的有序列表祖先上设置 numberingFormat 属性。传入 null 可清除它（此时列表会作为普通的 1. 2. 3. 导出）。

editor.chain().focus().setOrderedListNumberingFormat('decimal-paren').run()
editor.chain().focus().setOrderedListNumberingFormat(null).run()

当选区不在有序列表中，或者有另一种列表位于选区与该有序列表之间时，该命令返回 false，因为另一种列表会终止层级。要判断命令是否会找到列表，请使用 editor.can().setOrderedListNumberingFormat(null)，不要使用 editor.isActive('orderedList')：两者只会在这种情况下产生差异，而只有 can() 与命令实际行为一致。

以某种格式开始新列表

setOrderedListNumberingFormat 只会作用于选区已经位于其中的列表。要从非列表选区开始以所选格式创建编号列表，请使用 toggleOrderedListWithFormat(format?)。它会在一次调用中创建有序列表并应用格式，这正是“选择一种格式来开始编号列表”工具栏按钮的自然操作：

// 从段落开始：创建一个有序列表并设置其格式。
editor.chain().focus().toggleOrderedListWithFormat('outline').run()

// 省略格式可按配置的 `defaultFormat` 开始列表。
editor.chain().focus().toggleOrderedListWithFormat().run()

当选区已经位于有序列表中时，该命令会切换关闭该列表，与 toggleOrderedList 的行为一致。链式调用 toggleOrderedList().setOrderedListNumberingFormat(format) 会得到相同的最终状态；只是单个命令更方便，也会处理关闭切换的情况。

省略参数与传入 null 并不相同。省略参数时，新列表会使用配置的 defaultFormat；传入 null 时，新列表不会使用任何格式。

两个命令对 editor.can() 的回答含义不同，因此工具栏需要同时使用它们。toggleOrderedListWithFormat 与普通切换命令的判断方式相同：在普通段落中它会返回 true，因为可以创建列表；可以据此禁用“以此格式开始列表”的按钮。setOrderedListNumberingFormat 判断的是是否已有列表可供修改，在同一个普通段落中会返回 false。请使用 setter 的结果选择要运行的命令，而不是用它来禁用按钮：

// 一个“应用此格式”按钮，在两种位置都执行正确的操作。
if (editor.can().setOrderedListNumberingFormat(null)) {
  editor.chain().focus().setOrderedListNumberingFormat(id).run()
} else {
  editor.chain().focus().toggleOrderedListWithFormat(id).run()
}

项目符号列表

项目符号列表有对应的一组命令，目标是最外层的 bulletList 祖先：

editor.chain().focus().setBulletListNumberingFormat('arrows').run()
editor.chain().focus().toggleBulletListWithFormat('arrows').run()

上面的规则同样适用于项目符号命令，此时使用 defaultBulletFormat 而不是 defaultFormat。setBulletListNumberingFormat 在四种位置返回 false：不在任何列表中、位于有序列表中、位于任务列表中，以及只有跨过有序列表或任务列表才能到达的项目符号列表中。任务列表不是项目符号列表，因此会像有序列表一样终止层级。请根据 editor.can().setBulletListNumberingFormat(null) 分支；在这四种位置它都会返回 false，与上面的有序列表命令一致。

toggleBulletListWithFormat 的可达范围与有序列表对应命令相同：在任务列表内部使用它会将整个任务列表转换为普通项目符号列表，从而丢失复选框。

编辑器运行后添加格式

formats 只会在创建编辑器时读取一次。稍后才出现的注册表（通常是 DOCX 导入从文件中重建的注册表）应通过 registerNumberingFormats(formats) 注册。该命令会按 id 合并并刷新注入的预览样式表，因此文档中已有的列表会立即获得其标记：

editor.commands.registerNumberingFormats(formatsFromTheImport)

按 id 合并意味着重复调用是安全的：重新注册某个 id 会替换现有条目，而不是添加第二个条目，因此两次导入同一个文件只会保留一个定义。你在 formats 中配置的 id 也会以同样方式替换，因此导入的文档可以覆盖同名的项目规范。

完整注册表（已配置的格式以及之后注册的所有格式）位于扩展的 storage 中。将它传给导出器即可完成往返：

ExportDocx.configure({ numberingFormats: editor.storage.orderedListNumbering.numberingFormats })

启用 orderedListNumbering 后，ImportDocx 扩展会自动调用 registerNumberingFormats，因此导入的文档无需额外接线即可渲染自己的标记。以其他方式加载内容时，请手动调用它。

读取活动格式

要在工具栏中反映当前激活的格式，请从扩展的 storage 中读取它；当选区和文档发生变化时，它会保持同步：

const activeOrdered = editor.storage.orderedListNumbering.activeNumberingFormat
const activeBullet = editor.storage.orderedListNumbering.activeBulletNumberingFormat
// 一个格式 id；如果选区不在该类型的列表中，则为 `null`

Each field answers what its own command would target, so only one is set at a time: inside a bullet list nested in an ordered one, the bullet field reports that list and the ordered field reads null.

NumberingFormatDefinition

interface NumberingFormatDefinition {
  id: string
  levels: NumberingLevelDefinition[]
}

NumberingLevelDefinition

interface NumberingLevelDefinition {
  baseStyle: NumberingBaseStyle
  textTemplate: string
  startAt?: number
  alignment?: 'left' | 'center' | 'right'
  numberIndent?: number | string
  textIndent?: number | string
  markerFont?: NumberingMarkerFont
  suffix?: 'tab' | 'space' | 'nothing'
  isLegalNumbering?: boolean
  linkedStyle?: string
}

ConvertKit 的类型使用普通字符串字面量，因此该包不会引入 docx。这些字段在结构上与 ExportDocx 更严格（使用 docx 类型）的版本兼容，因此从 @tiptap-pro/extension-export-docx 传入 LevelFormat.DECIMAL 的效果与传入字符串 'decimal' 相同。

NumberingMarkerFont

interface NumberingMarkerFont {
  font?: string | { name: string }
  size?: number | string
  bold?: boolean
  italics?: boolean
  color?: string
  underline?: unknown
}

与 generateNumberingFormatCss 所理解的 docx IRunOptions 子集一致。你传递给 ExportDocx 的额外字段会在预览中被忽略，但仍会保留到 .docx 中。

textTemplate 语法

• %1 到 %9 引用的是 1 基索引的嵌套深度上的计数器。因此，无论 textTemplate 属于哪一层，%1 始终表示“最外层的计数器”。
• 其他所有字符都会按字面量渲染。
• 以非数字结尾的孤立 %（例如 "50%"）会被保留。
• 指向不计数层级、'bullet' 或 'none' 层级的 %N 不会绘制任何内容。

要让每一层显示自己的计数器，请按层级使用递增的 %N。要让某一层包含父级计数器（法律式大纲），请把它们串联起来：在第 1 层使用 '%1.%2.' 时会渲染为 '1.1.'。

项目符号层级

Word 从 w:lvlText 中的字形绘制项目符号，因此箭头、菱形或星号是文档携带的内容，而不是阅读者的 Word 决定的内容。层级使用 baseStyle: 'bullet' 的格式表示这样的项目符号层级，bulletList 通过同一个 numberingFormat 属性选择它：

numberingFormats: [
  {
    id: 'arrows',
    levels: [
      { baseStyle: 'bullet', textTemplate: '➔' },
      { baseStyle: 'bullet', textTemplate: '◆' },
    ],
  },
]
// { type: 'bulletList', attrs: { numberingFormat: 'arrows' }, content: [...] }

在 'bullet' 层级中，textTemplate 就是字形本身，markerFont.font 指定绘制它所使用的字体，这是 Word 符号字体项目符号所需的设置。层级上的其他配置（包括缩进）与计数器层级相同。只有精确的 bullet 值会将层级标记为项目符号层级，其他 baseStyle 仍然是计数器层级。

项目符号层级不计数，因此指向它的 %N 不会绘制内容。在项目符号层级上，'Item %1:' 会在 Word 和预览中都渲染为 Item :。'none' 的行为相同，isLegalNumbering 也不会改变这一点：法律编号可以将计数器改绘为阿拉伯数字，但无法为没有计数器的层级创建计数器。

格式不绑定某一种列表类型。它会应用于声明它的列表，就像 Word 的 numId 无论列表外观如何都会指向一个定义：因此 <ol> 上的字形层级会绘制项目符号，而 <ul> 上的计数器层级会进行计数。generateNumberingFormatCss 会同时从 ul 和 ol 读取属性，因此预览和导出在两种情况下都保持一致。

嵌套在同类型列表中的列表会在自己的深度使用外层列表的层级，因此一个多级列表只保留一个定义。

任务列表

任务列表会渲染为 ul，但它不是项目符号层级中的一个层级。任务列表会保留复选框，而嵌套在任务列表中的项目符号列表也会保留自己的 numberingFormat。

任务列表同样会终止层级链，就像另一种列表一样。命令和 active… storage 字段会在这里停止，因此只有通过任务列表才能到达的项目符号列表又是最外层列表，并携带自己的格式。

Schema 约定：各自类型的最外层

numberingFormat 属性应放在每种列表类型的最外层列表上。一个定义会声明该多级列表所有嵌套层级。OrderedListNumbering 会在解析时强制执行这一点：如果粘贴的 HTML 中，嵌套在另一个 <ol> 中的 <ol> 或嵌套在另一个 <ul> 中的 <ul> 带有 data-numbering-format，该属性会被移除。

另一种列表类型会开始自己的层级，也会终止当前链：通过 <ol> 到达的 <ul> 又是最外层列表，因此即使外层还有另一个 <ul>，它也会保留自己的格式。命令和 active… storage 字段也会在此边界停止，因此每个命令都指向导出和预览实际绘制的列表。

同一个最外层列表下的所有嵌套层级共享一个计数器作用域，并且子级会在父级递增时重新开始，就像 Word 的行为一样。

循环规则

levels.length 定义了循环周期。当列表嵌套深度超过 levels.length - 1 时，深度 N 会在 DOCX 导出和编辑器预览 CSS 中都复用 levels[N % levels.length]。提供九个层级可以覆盖 Word 的完整嵌套深度而不循环；如果更深的层级可以自然重复较浅的条目，则可提供更少的层级。

默认值与 Word 标准一致

当省略 numberIndent / textIndent 时，导出器和 CSS 辅助函数都会输出 Word 的标准多级列表默认值：

Marker alignment

alignment says where the marker sits in relation to numberIndent, the position its level gives it. Word justifies the marker against that single point, and the editor preview does the same.

Body text sits at textIndent whichever you pick, so a right-aligned marker leaves a wider gap between itself and the text than a left-aligned marker of the same width. Under 'left' and 'center', a marker wider than that gap pushes the body text of its own item further right; a right-aligned marker grows into the space before numberIndent instead and never moves the text. Either way only that one item's text moves: a list nested inside the item still starts at the position its own level gives it.

// Roman numerals get wider as they count up. Right alignment keeps their
// periods in one column and the text in another.
levels: [{ baseStyle: LevelFormat.UPPER_ROMAN, textTemplate: '%1.', alignment: 'right' }]

A suffix of 'space' or 'nothing' drops the padded marker column, so under 'left' and 'center' the body text follows the marker directly instead of waiting for textIndent. Combined with 'right' the marker still ends at numberIndent, which leaves the body text starting there as well.

Indents on a single item

A level places every item that belongs to it, but a single item can sit somewhere else. When the paragraph inside a list item carries an indent attribute, that item's marker and body text both move to it and the level's textIndent no longer applies to that item. A negative firstLineIndent on the same paragraph sets that item's gap between marker and text, in place of the level's distance from numberIndent to textIndent. A heading inside a list item is read the same way.

// Sits further right than its level puts it, with a 24px gap for the marker.
{
  type: 'listItem',
  content: [
    {
      type: 'paragraph',
      attrs: { indent: 96, firstLineIndent: -24 },
      content: [{ type: 'text', text: 'Positioned by the item, not by the level' }],
    },
  ],
}

Imported documents rely on this. The import writes each list paragraph's own Word indent onto the paragraph node as indent and firstLineIndent (see ConvertKit), so the items land where the source document drew them rather than on the level's ladder.

Conditions and limits:

• It applies only to a list that names a format the editor knows about, whether from formats or from registerNumberingFormats. Without one nothing positions the item, so the paragraph keeps rendering the indent itself as padding-left and text-indent, exactly as a paragraph outside a list does. The same holds when orderedListNumbering is off.
• A task list is not part of a numbering ladder, so an item in a checklist keeps its indent on the paragraph.
• A positive firstLineIndent is an ordinary first-line indent rather than a marker gap. It stays on the paragraph and indents the first line of the item's text.
• indentRight is left alone. A list positions the left edge of its items, not the right.
• A list item holding more than one block takes its position from the first block. The later blocks line up with it and do not render an indent of their own.
• The attributes stay on the node, so ExportDocx writes the same indent back out and a DOCX round trip keeps it.
• The editor positions the item and clears the paragraph's own padding-left and text-indent with an inline style. A rule of your own on that paragraph needs !important to take the block back.

generateNumberingFormatCss(formats, options?)

返回 CSS 文本，由你决定如何注入（例如 <style> 标签、CSS-in-JS 层、由构建流水线提供的样式表等）。该函数是纯函数且无依赖，可安全地在启动时或注册表发生变化时调用。

generateNumberingFormatCss(formats, {
  scope: '.tiptap.ProseMirror', // 默认
  maxDepth: 9, // 默认
})

生成的 CSS 会将每个列表标记及其正文文本定位到与 Word 渲染的绝对位置一致，包括每一层嵌套深度的阶梯式缩进。它会在列表及其每个条目上设置左边距和内边距，因此格式化列表内部 ul、ol 或 li 上优先级更低的自定义规则会被覆盖；垂直间距由你自行控制。如需为主题定制覆盖某些内容（深色模式、RTL、字体缩放），可以把输出包裹在你自己的选择器或作用域中，并依赖级联规则。

列表项需要使用 box-sizing: border-box。条目规则会将百分比宽度与内边距结合使用；没有该设置时，位于层级右侧的条目会超出列表的右边缘。ConvertKit 的 CSS 重置会在 .tiptap 内设置该属性，这覆盖默认作用域；如果在其他位置注入 CSS，请自行添加。

每个格式都会同时生成 ul[data-numbering-format="…"] 和 ol[data-numbering-format="…"] 规则，因为格式会应用于声明它的任意列表。随后每条链会通过自己的元素（ul:not([data-type="taskList"]) 或 ol）使用 > li > 进入下一级，因此任务列表会保留复选框，而层级会在另一种列表处停止，不会穿透它。

解析规则

• 匹配的 id 会使用相应的定义来渲染该多级列表的每一层（包括所有同类型的嵌套列表）。
• 未匹配的 id（拼写错误、缺少属性、空的 numberingFormats）会保留该列表类型的默认层级：有序列表使用普通的 1. 2. 3.，项目符号列表使用内置字形层级。
• 引用相同格式的同级多级列表会独立重新开始，每个都从各自的 startAt 开始。例外是任一层级带有 linkedStyle 的格式：它在整个文档中属于同一个列表，因此不同列表会继续编号。

已知限制

导出器刻意没有建模的 Word 功能：

另请参阅

• 编辑器扩展概览: 基础 ExportDocx 配置。
• 样式: 段落样式、标题、列表段落样式的 styleOverrides。
• REST API: 服务器端转换端点。