企业官网建设流程全解析

npm install @tiptap/vue-3 @tiptap/starter-kit @tiptap/extension-list

<template> <div class="toolbar"> <button @click="editor.chain().focus().toggleBulletList().run()">无序</button> <button @click="editor.chain().focus().toggleOrderedList().run()">有序</button> <button @click="editor.chain().focus().toggleTaskList().run()">任务</button> </div> <editor-content :editor="editor" class="tiptap" /> </template> <script setup> import { useEditor, EditorContent } from '@tiptap/vue-3' import StarterKit from '@tiptap/starter-kit' import { TaskList, TaskItem } from '@tiptap/extension-list' const editor = useEditor({ extensions: [ StarterKit, // 已含 BulletList / OrderedList / ListItem TaskList, TaskItem.configure({ nested: true }), // 默认不支持嵌套，显式打开 ], content: '<p>选中文本点上面的按钮试试</p>', }) </script>

三个按钮分别对应三种列表的切换命令，命令名就是列表名加toggle前缀，很好记。

按真实场景写列表

用输入规则打出文档清单，少点一次按钮

Tiptap 列表支持 Markdown 式输入规则：行首输入-自动变无序列表，1.变有序列表，[ ]变任务项。你甚至不用碰工具栏，打字本身就是操作。这个正则定义在 bullet-list.ts 的bulletListInputRegex里，想改触发符号（比如加个+）可以自己扩展。

给任务看板加可勾选的 TaskItem

任务项的勾选状态存在节点属性checked里，渲染成data-checked属性，复选框由内置 NodeView 负责。两个实用配置：

TaskItem.configure({ nested: true, // 允许任务下面挂子任务 onReadOnlyChecked: (node, checked) => { // 只读模式下点勾选框时触发，返回 false 则回滚 UI return true }, })

nested默认是false，不开的话任务项里按 Tab 不会缩进——这是任务列表嵌套失灵最常见的原因。

用 Tab 和 Shift+Tab 搭多层嵌套列表

嵌套不用写任何命令：光标在列表项里按 Tab 下沉（sinkListItem），按 Shift+Tab 上移（liftListItem），快捷键注册在 list-item.ts 里。当嵌套列表要整体删掉时，Backspace/Delete 会触发分支合并逻辑（见 helpers 目录），把子列表"提"到父级而不是留一个空壳。

把 Tiptap 列表样式调出高级感

Tiptap 列表本身不带样式，<ul>、<ol>、<li>都是原生标签，Tiptap 列表样式完全交给 CSS。任务列表的ul和li上会带data-type属性，正好用来做差异化选择器：

/* 基础缩进与间距 */ .tiptap ul, .tiptap ol { padding-left: 1.5rem; margin: 0.75rem 0; } /* 用伪元素换掉默认圆点 */ .tiptap ul:not([data-type="taskList"]) > li { list-style: none; } .tiptap ul:not([data-type="taskList"]) > li::before { content: "▸"; color: #6366f1; margin-left: -1rem; display: inline-block; width: 1rem; } /* 任务项：勾选后整行置灰 */ .tiptap li[data-type="taskItem"] { display: flex; gap: 0.5rem; } .tiptap li[data-type="taskItem"][data-checked="true"] span, .tiptap li[data-type="taskItem"][data-checked="true"] div { text-decoration: line-through; opacity: 0.6; }

想让某个列表单独换 class，在扩展配置里传HTMLAttributes即可，它会合并到渲染出的标签上：

OrderedList.configure({ HTMLAttributes: { class: 'my-steps' } })

这几个坑我替你踩过了

有序列表的start不是靠 configure 写死的。参考一些旧教程可能让你写OrderedList.configure({ start: 3 })，但start是节点属性，实际来源是输入规则：行首输入3.加空格，Tiptap 就会创建一个从 3 开始的有序列表（见 ordered-list.ts 中getAttributes: match => ({ start: +match[1] })）。渲染时只有start !== 1才会输出start属性，所以默认列表的 HTML 是干净的。

列表项里的加粗、颜色"丢失"是默认行为。keepMarks和keepAttributes默认false，意思是回车拆分列表项时新项不继承文本样式。希望新项保留当前加粗/字体颜色，就配置BulletList.configure({ keepMarks: true })。

任务项默认不能嵌套。再强调一次：TaskItem的nested默认false，不开 Tab 缩进不生效。

快捷键速查（前三个在对应列表扩展里注册，后三个在 ListItem 里注册）：

列表只是开始。下一步建议先试试把@tiptap/markdown接上（三种列表都内置了 Markdown 解析与序列化），再去看 任务列表的官方示例感受完整交互；如果你的产品里还有拖拽、粘贴转换这类需求，extension-list 的源码结构会告诉你该从哪个文件下手。

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