tiptap OrderedList 有序列表扩展完全指南从tiptap/extension-ordered-list到tiptap/extension-list的演进与迁移【免费下载链接】tiptapThe headless rich text editor framework for web artisans.项目地址: https://gitcode.com/GitHub_Trending/ti/tiptap导读本文以 tiptap 仓库中 tiptap/extension-ordered-list 的版本变更日志 为主线结合 monorepo 中列表扩展的真实实现源码系统讲解 tiptap 有序列表扩展的架构演进、配置项语义、Schema 与快捷键行为以及从分散列表包迁移到聚合包tiptap/extension-list的完整操作步骤。读完本文你将能理解为何当前extension-ordered-list包是一个瘦身后的重导出兼容层掌握OrderedList全部选项的默认值与底层影响并能在 v3 时代正确安装、配置和迁移列表相关依赖。适用前提说明本文涉及的命令与包结构以当前仓库v3.30.3 时代、基于 pnpm workspace 的 monorepo为准。仓库采用 pnpm workspace 管理多包且各列表扩展已被整合进tiptap/extension-listtiptap/extension-ordered-list仅作为兼容性入口存在见 packages/extension-ordered-list/src/index.ts。一、版本日志揭示的事实一个被合并进扩展聚合包的独立扩展tiptap/extension-ordered-list的 CHANGELOG.md 记录了该包完整的发布轨迹从2.0.0-alpha时代、到 v2 稳定期2.0.x2.12.0、再到 v3 时代的3.0.0-beta.x/3.0.0-next.x与最终稳定版 3.30.3。该日志可以提炼出三个关键事实v3 稳定版的绝大多数发布都是Patch Changes并且几乎全部内容仅是一行依赖说明例如3.30.3对应tiptap/extension-list3.30.3。这说明有序列表的真实实现早已不在本包而是一路跟随聚合包tiptap/extension-list的版本号同步发布。v3.0.0 是一次决定性的架构调整变更哈希2c911d2官方将所有列表相关扩展的代码搬进tiptap/extension-list本包变成纯转发层同时引入ListKit作为一次性注册/配置全部列表扩展的推荐方式。少数非纯版本号条目揭示出重要的行为变更v2.11.6 将有序列表默认type值改为null以便于 Schema 扩展9abb019beta.26 增加itemTypeName选项3d7c8e62.0.0-beta.219 支持在列表上保留 marks#3540/#3541提交36bb1e1。1.1 为什么这个包还在却几乎没有代码对照仓库结构即可验证上述判断。当前 packages/extension-ordered-list 包内src/index.ts全文仅做三件事从tiptap/extension-list导入OrderedList、再导出其类型OrderedListOptions、最后将其作为默认导出——即保持对老式import OrderedList from tiptap/extension-ordered-list的兼容package.json 中tiptap/extension-list被声明为唯一的peerDependenciesworkspace 内联解析真实实现位于 packages/extension-list/src/ordered-list/ordered-list.ts并在同一包的kit/目录下通过 ListKit 统一装配。也就是说对升级到 v3 的用户而言直接使用聚合包即可拿到与旧包完全等价的OrderedList同时还能减少对等依赖冲突。二、v3 官方迁移指南合并列表包与 ListKit变更日志在3.0.0/3.0.0-next.6条目中给出了完整的官方迁移说明。官方明确的推荐做法是使用ListKit一次性配置所有列表扩展。import { ListKit } from tiptap/extension-list; new Editor({ extensions: [ ListKit.configure({ bulletList: { HTMLAttributes: bullet-list, }, orderedList: { HTMLAttributes: ordered-list, }, listItem: { HTMLAttributes: list-item, }, taskList: { HTMLAttributes: task-list, }, taskItem: { HTMLAttributes: task-item, }, listKeymap: {}, }), ], });ListKit的可配置子项与源码完全对应ListKitOptions 依次暴露bulletList、listItem、listKeymap、orderedList、taskItem、taskList六个键每个键的类型是Partial选项 | false——即传入false可整体关闭某个子扩展例如纯文本编辑器不需要任务列表时设taskList: false、taskItem: false其余键则透传给对应的.configure()。2.1 依赖清理卸载旧包、安装聚合包官方在日志中明确给出了 npm 层面的替换命令。由于代码已全部迁移到聚合包可移除下列旧依赖npm uninstall tiptap/extension-ordered-list tiptap/extension-bullet-list tiptap/extension-list-keymap tiptap/extension-list-item tiptap/extension-task-list再安装聚合包作为替代npm install tiptap/extension-list值得注意的是当前仓库本身仍保留着tiptap/extension-ordered-list这一空壳包目的就是为上述旧依赖做平滑过渡若你直接以聚合包为目标未来升级时就不会再碰到日志3.22.4条目中提到的依赖更新后触发 peer dependency 解析冲突27ea931这一类连锁问题。2.2 需要更细粒度控制也可以单独使用各扩展官方迁移指南同时指出如果不想使用聚合式ListKit也可以单独引入各扩展以下是日志给出的逐包迁移对照与用法OrderedList本主题核心- import OrderedList from tiptap/extension-ordered-list import { OrderedList } from tiptap/extension-listimport { OrderedList } from tiptap/extension-list;BulletList- import BulletList from tiptap/extension-bullet-list import { BulletList } from tiptap/extension-listimport { BulletList } from tiptap/extension-list;ListItem- import ListItem from tiptap/extension-list-item import { ListItem } from tiptap/extension-listimport { ListItem } from tiptap/extension-list;TaskList- import TaskList from tiptap/extension-task-list import { TaskList } from tiptap/extension-listimport { TaskList } from tiptap/extension-list;TaskItem- import TaskItem from tiptap/extension-task-item import { TaskItem } from tiptap/extension-listimport { TaskItem } from tiptap/extension-list;ListKeymap- import ListKeymap from tiptap/extension-list-keymap import { ListKeymap } from tiptap/extension-listimport { ListKeymap } from tiptap/extension-list;源码层面单独的 OrderedList 通过Node.createOrderedListOptions({ name: orderedList, ... })注册其 content 定义为${itemTypeName}即有序列表内必须含至少一个列表项节点且官方注释明确使用 OrderedList 依赖同时启用 ListItem 扩展。三、OrderedList 选项深度解析结合源码确认默认值日志记录的关键演进——新增itemTypeNamebeta.262021-12-10、parseHTML属性直接返回值beta.16修复 #1863、保留列表上的 marks2.0.0-beta.219#3540/#3541——最终沉淀为OrderedListOptions的四个选项。其类型定义与默认值可从 ordered-list.ts 的addOptions()与接口注释中完整确认选项默认值说明来源/演进itemTypeNamelistItem列表项节点类型名用于content声明与切换命令beta.263d7c8e6新增HTMLAttributes{}渲染到ol标签上的自定义 HTML 属性如class各框架通用keepMarksfalse拆分列表项时是否保留当前 marks2.0.0-beta.219#3540/#3541keepAttributesfalse拆分列表项时是否保留属性与keepMarks配套演进3.1 keepMarks / keepAttributes 在命令中的真实作用路径查看 addCommands() 的实现可更准确地理解这两个开关。toggleOrderedList命令在keepAttributes为真时走命令链先toggleList再用textStyle的属性回填到listItem否则直接执行commands.toggleList(this.name, this.options.itemTypeName, this.options.keepMarks)toggleOrderedList: () ({ commands, chain }) { if (this.options.keepAttributes) { return chain() .toggleList(this.name, this.options.itemTypeName, this.options.keepMarks) .updateAttributes(ListItemName, this.editor.getAttributes(TextStyleName)) .run() } return commands.toggleList(this.name, this.options.itemTypeName, this.options.keepMarks) },同理addInputRules() 会在任一开关为真时改用携带keepMarks/keepAttributes参数及textStyle属性的wrappingInputRule。这解释了日志#3541Ability to preserve marks on lists的含义当用户把带有加粗/斜体等样式的段落转换为有序列表时这些样式不会丢失。3.2 HTMLAttributes 的典型用法HTMLAttributes与 OrderedList 节点自身的start/type属性会被 renderHTML() 通过mergeAttributes(this.options.HTMLAttributes, attributesWithoutType)合并后渲染到ol上。例如给所有有序列表加一个用于样式的类OrderedList.configure({ HTMLAttributes: { class: my-ordered-list }, })start与type属于节点内置属性会被从自定义属性中剥离并按规则输出见下一节不会和用户自定义 HTML 属性冲突。四、Schema 内建属性start 与 type有序列表节点在 addAttributes() 中声明了两个属性理解它们对粘贴外部富文本场景尤其重要start默认1。解析 HTML 时读取ol start无该属性则回落为1渲染时仅在start ! 1时输出start属性。type默认null。解析 HTML 时按三级策略探测编号类型读取ol上的type属性读取olstyle 中的list-style-type通过cssListStyleTypeToHtmlType映射读取第一个li上的list-style-type——官方注释指出这是Google Docs 的典型写法。映射规则集中在源码注释清晰的cssListStyleTypeToHtmlType函数中CSSlist-style-type值输出的 HTMLtype值upper-romanIlower-romaniupper-alpha/upper-latinAlower-alpha/lower-latina其他值不输出返回null渲染时仅当type存在且不等于1才输出type属性。这一设计正是日志 v2.11.6 条目Use null in ordered lists default type value for better schema extension support9abb019的直接体现把默认值从某种数字类型改为null使parseHTML探测到的type值如a、i能干净地写入 Schema避免与默认类型混淆也方便后续扩展覆盖属性。type相关行为在聚合包测试 orderedListType.spec.ts 中有覆盖parseHTML特性本身最早由 beta.16 的属性解析直接返回值变更修复 #1863奠定。五、快捷键、输入规则与粘贴处理5.1 快捷键addKeyboardShortcuts() 为Mod-Shift-7绑定了toggleOrderedList()Mod在 macOS 对应 Cmd、在其他平台对应 Ctrl。也就是说默认编辑器里按下Ctrl/Cmd Shift 7即可切换有序列表。5.2 输入规则从数字加点和空格开始有序列表支持输入即转换其识别正则在源码中直接导出便于扩展复用export const orderedListInputRegex /^(\d)\.\s$/即当用户输入诸如1.时wrappingInputRule会命中并把start属性设为该数字。值得注意的是 joinPredicate 的合并条件只有当现有列表的type为空或为1未定制编号风格且现有项数加start等于新输入的数字时才会把输入合并进已有列表而像a)、i)这类带类型的列表则刻意保持独立不参与合并。该输入规则能力源自 2.0.0-beta.17 的把 input rules 与 paste rules 整合进 core#1997。5.3 纯文本粘贴识别并重建有序列表结构源码通过 addProseMirrorPlugins() 注册了一个自定义handlePaste当剪贴板**只有纯文本无 HTML**且能按parsePlainTextOrderedListPaste解析出列表内容时直接构造orderedList节点并replaceSelectionWith替换选区从而实现从外部复制一段带编号的文本粘贴进来自动成为有序列表。若剪贴板含 HTML 或文本无法解析则返回false走 ProseMirror 默认路径。与误判列表相关的回归测试存在于 orderedListPhoneNumber.spec.ts——电话号(216) 555-1234这类行中出现的216)不应被识别为列表起点。5.4 Markdown 协同数字、字母与罗马数字标记v3 的列表实现还内置了 Markdown 的解析与渲染markdownTokenName: listparseMarkdown只处理ordered的 token并把 token 的start、typeMarker如a、i、I映射为节点属性renderMarkdown负责把节点内容按换行递归输出markdownTokenizer使用 utils.ts 与 roman.ts 中的ORDERED_LIST_ITEM_REGEX等工具处理数字/字母/罗马数字多种标记并支持带缩进的嵌套列表buildNestedStructure以首项缩进为基准构造层级markdownOptions.indentsContent: true指示内容需缩进表示层级。相关测试参见聚合包测试目录 packages/extension-list/tests其中 listItemMarkdown.spec.ts 与 orderedList 系列测试共同覆盖了这些行为。六、工程化变更脉络从 2.x 到 3.x 的关键节点变更日志中有多条非版本号条目勾勒出列表包跨越大版本演进的工程化路线版本区间变更内容工程含义3.0.0Majora92f4a6改用 tsup 构建不再产出 UMD依赖 UMD 产物者需自行重新打包rollup/esbuild 等3.0.0Major2c911d2全部列表包并入tiptap/extension-list引入ListKit前文迁移指南的根源3.0.x 系列1b4c82b使用 pnpm 包别名做版本锁定89bd9c7强制 type-only import 以让打包器在生成 dist/index.js 时忽略类型导入8c69002beta 与 stable 功能对齐monorepo 依赖管理、产物体积与稳定性的内部治理2.11.69abb019有序列表默认type用nullSchema 扩展更友好2.0.0-beta.21936bb1e1#3540/#3541列表保留 marks促成keepMarks/keepAttributes能力2.0.0-beta.210f387ad3新增 prosemirror 依赖解析包统一 PM 依赖版本避免多版本冲突2.0.0-beta.263d7c8e6新增itemTypeName选项支持自定义列表项节点名2.0.0-beta.17723b955#1997input rules 与 paste rules 收归 core输入/粘贴能力统一由 core 调度需要留意的是日志中 v2 段落在版本号上存在明显的分支/回填痕迹例如2.11.6之后直接出现2.5.8、2.5.x等更早的版本中间穿插大量 Version bump only 的占位条目。这属于多发布线合并时常见的补录现象不影响功能判断。另外 v2 段中 2024-05 的2.4.0条目记录了 added jsdocsb941eea即从该版本起为扩展补充了完整的 JSDoc 注释——这正是如今OrderedListOptions各字段都带default/example注释的由来。七、当前仓库中的上手资源若要在真实环境验证上述行为仓库内已有可直接参考的实现与示例有序列表实现全量源码packages/extension-list/src/ordered-list/ordered-list.ts选项、属性、命令、快捷键、粘贴、输入规则、Markdown配套辅助逻辑见同目录 utils.ts 与 roman.tsListKit装配逻辑与每个子扩展的开关语义packages/extension-list/src/kit/index.ts聚合包导出入口与各扩展文件索引packages/extension-list/src/index.ts、packages/extension-list/src/ordered-list/index.ts兼容性重导出包本文主题包packages/extension-ordered-list/src/index.ts行为回归测试packages/extension-list/tests/orderedListType.spec.ts、packages/extension-list/tests/orderedListPhoneNumber.spec.ts、packages/extension-list/tests/listItemMarkdown.spec.ts、packages/extension-list/tests/listKeymapTab.spec.ts可运行的前端示例Vue/React/JSX 三套入口demos/src/Nodes/OrderedList。八、小结升级到 v3 时的三句话结论依赖上用tiptap/extension-list取代tiptap/extension-ordered-list等六个旧包并按需通过ListKit.configure({ orderedList: { ... } })统一配置老包作为兼容层仍可在升级过渡期使用。配置上itemTypeName、HTMLAttributes、keepMarks、keepAttributes四个选项的默认值与行为全部可在 ordered-list.ts 中追溯start/type属性负责承载编号起点与罗马/字母编号风格。行为上Ctrl/CmdShift7、1.输入转换、纯文本粘贴解析、Markdown 双向转换都已内建若需要 UMD 构建产物则需自行使用打包器重新封装v3 已移除 UMD 输出。【免费下载链接】tiptapThe headless rich text editor framework for web artisans.项目地址: https://gitcode.com/GitHub_Trending/ti/tiptap创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考