企业官网建设流程全解析

tiptap v3 列表扩展统一收编：@tiptap/extension-list-item 废弃与 ListKit 迁移指南

【免费下载链接】tiptapThe headless rich text editor framework for web artisans.项目地址: https://gitcode.com/GitHub_Trending/ti/tiptap

本文基于 tiptap 仓库中 packages-deprecated/extension-list-item/CHANGELOG.md 的核心变更记录展开，面向正在从 tiptap v2 拆分式列表包（@tiptap/extension-list-item等）升级到 v3 统一列表包@tiptap/extension-list的开发者。读完本文你将掌握ListKit的一键聚合用法、六个列表扩展的独立引入方式、依赖卸载与安装的完整迁移步骤，以及本仓库源码中对应的实际实现与测试佐证。

一、背景：为什么会有这份 CHANGELOG

在 tiptap 的 v3 发布中，列表相关的扩展发生了一次结构性重构：原来分散在@tiptap/extension-list-item、@tiptap/extension-bullet-list、@tiptap/extension-ordered-list、@tiptap/extension-task-list、@tiptap/extension-list-keymap等多个独立 npm 包中的代码，被统一收编进单一包@tiptap/extension-list。

这一点从仓库目录结构可以直接印证：原本的独立包@tiptap/extension-list-item已被移入packages-deprecated/（废弃）目录，它的源码如今只剩下一层薄薄的“转发层”：

// packages-deprecated/extension-list-item/src/index.ts import { ListItem } from '@tiptap/extension-list' export type { ListItemOptions } from '@tiptap/extension-list' export { ListItem } from '@tiptap/extension-list' export default ListItem

该废弃包的 package.json 中，名称仍为@tiptap/extension-list-item、版本停留在 3.30.3，但devDependencies与peerDependencies都已指向@tiptap/extension-list，即它的所有实现都委托给了新包。

而在活跃维护的 packages/extension-list/src/index.ts 中，可以清晰看到新包统一导出了全部列表模块：

export * from './bullet-list/index.js' export * from './item/index.js' export *from './keymap/index.js' export * from './kit/index.js' export * from './ordered-list/index.js' export * from './task-item/index.js' export * from './task-list/index.js'

其中./item/就是原ListItem的真正实现所在（见 packages/extension-list/src/item/list-item.ts）。这正是本 CHANGELOG 中「List repackaging（列表重打包）」条目的仓库级证据。

二、v3 迁移核心：用 ListKit 一次配置全部列表扩展

CHANGELOG 明确指出，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.configure(...)中每个键对应当前仓库packages/extension-list/src/kit/index.ts里ListKitOptions接口的一个字段，每个字段的取值类型为Partial<对应扩展 Options> | false。也就是说，除了逐个传入配置对象外，你还可以显式传false关闭某个子扩展（例如listKeymap: false），源码注释中给出的语义是“若设为 false，则该扩展不会被注册”。

其中HTMLAttributes是 tiptap 扩展渲染时的通用配置项，用于向对应节点的 DOM 元素注入额外的 HTML 属性（这里示例值即 class 名），实际生产代码中通常这样写：

ListKit.configure({ listItem: { HTMLAttributes: { class: 'my-list-item' } }, })

需要提醒的是：CHANGELOG 示例里的"bullet-list"这类字符串写法会被 tiptap 合并进对应节点的 HTML 属性，具体生效方式取决于你传入的是字符串属性还是对象，建议按实际使用的 tiptap v3 版本（本仓库对应@tiptap/extension-list3.30.3）中的类型提示为准。

三、依赖清理：卸载旧包、安装新包

由于代码已整体迁出旧的列表扩展包，CHANGELOG 要求从项目中移除如下旧依赖：

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

配套的还有一处细节变更值得留意：本 CHANGELOG 的 3.22.4 版本条目提到一次修复——“Fix dependencies installation after packages updates producing peer dependency resolution conflicts”（修复包更新后依赖安装产生的 peer dependency 解析冲突）。这正是因为在迁移后，旧包与@tiptap/extension-list之间存在 peer 依赖关系，若清理不彻底容易在npm install时触发冲突，务必按上述两条命令完整执行。

如果使用 pnpm（本仓库使用 pnpm workspace），对应命令为pnpm remove ...与pnpm add @tiptap/extension-list。仓库根目录的 pnpm-workspace.yaml 即为该 monorepo 的工作区配置。

四、想分开用？六个扩展的逐个迁移对照表

如果希望获得更细粒度的控制，也可以不依赖ListKit，从@tiptap/extension-list中分别导入各个扩展。CHANGELOG 为每个扩展都给出了 import 迁移对照与用法，汇总如下：

例如最受影响的ListItem迁移，diff 形式如下：

- import ListItem from '@tiptap/extension-list-item' + import { ListItem } from '@tiptap/extension-list'

迁移后的独立使用方式（与旧版一致，只是导入来源变化）：

import { ListItem } from "@tiptap/extension-list"; new Editor({ extensions: [ListItem], });

之所以能保持“只改 import”的无痛迁移，正是因为ListItem的核心实现仍然存在，只是位置从独立的 packages-deprecated/extension-list-item 移到了 packages/extension-list/src/item/list-item.ts，并被 packages/extension-list/src/index.ts 重新导出。

五、仓库源码中的行为佐证

新包的列表行为并非只有声明，仓库中的测试给出了可直接验证的依据，例如：

• packages/extension-list/tests/listItemDelete.spec.ts：覆盖列表项的删除行为，呼应本 CHANGELOG 在 2.1.0-rc.0 中记录的**list-item:** improve delete behaviour与**lists:** improve list behaviour两处修复；
• packages/extension-list/tests/listKeymapTab.spec.ts：验证ListKeymap的 Tab 缩进等键盘行为；
• packages/extension-list/tests/orderedListType.spec.ts 与 packages/extension-list/tests/orderedListPhoneNumber.spec.ts：覆盖有序列表类型及自动编号等场景。

这些测试说明，列表功能在收编到@tiptap/extension-list后仍保持既有行为并被持续回归验证。

六、构建与版本管理的连带变化

除了功能层面的收编，本 CHANGELOG 在 v3 早期版本（3.0.1 / 3.0.0-next.1 等）中还记录了三条与打包发布相关的工程变更，升级时同样需要知晓：

1. 构建工具切换到 tsup，不再产出 UMD 构建（对应 commit 信息a92f4a6）：如果你依赖 UMD 直接在浏览器<script>中使用，需要自行重新打包（"please repackage if you require UMD builds"）；
2. monorepo 使用 pnpm 包别名做版本固定（1b4c82b），以便更精确地锁定多包仓库中各依赖的版本；
3. 强制使用类型导入（type-only imports）（89bd9c7），使打包器在生成 dist 的index.js时能忽略 TypeScript 类型导入，减小产物体积。

这些改动与packages-deprecated/extension-list-item/package.json中"main": "dist/index.cjs"、"module": "dist/index.js"、"type": "module"的双格式导出结构相对应。

七、结语与升级检查清单

整体来看，tiptap v3 对列表扩展的处理是典型的“多包拆分 → 单包聚合”演进：源码实现归一，历史包进入packages-deprecated保留兼容转发，官方通过ListKit提供一键配置入口。升级到 v3 后，建议按如下清单自查：

• 卸载@tiptap/extension-list-item等五个旧包，安装@tiptap/extension-list；
• 将源码中的默认导入改为从@tiptap/extension-list命名导入（ListItem、BulletList、OrderedList、TaskList、TaskItem、ListKeymap）；
• 若未使用StarterKit之外的列表配置，考虑直接切换到ListKit.configure({ ... })以获得单一配置入口；
• 确认打包链路的输出格式要求（tsup 已不再提供 UMD 产物）；
• 用仓库中对应的listItemDelete.spec.ts、listKeymapTab.spec.ts等用例验证自己的升级分支未破坏列表交互。

迁移完成后，项目中不再需要任何@tiptap/extension-list-item依赖，相关的编辑、删除、缩进与任务列表能力全部由@tiptap/extension-list统一提供，维护面也从多个包收敛为一个。

【免费下载链接】tiptapThe headless rich text editor framework for web artisans.项目地址: https://gitcode.com/GitHub_Trending/ti/tiptap