使用Tiptap构建富文本编辑器的教程
Tiptap是一个基于ProseMirror的无头（headless）富文本编辑器框架，专为现代Web应用设计。它提供了强大的核心功能，同时允许开发者完全控制编辑器的外观和交互。本教程将指导你从零开始构建一个基础的Tiptap编辑器。
第一步：初始化项目
首先，你需要一个前端项目。如果你没有现成的项目，可以使用Vite快速创建一个。
打开终端，执行以下命令：
npm create vite@latest my-tiptap-editor — –template vanilla
创建后，进入项目目录：cd my-tiptap-editor
第二步：安装Tiptap
在项目目录下，安装Tiptap的核心包和必要的扩展。
运行命令：
npm install @tiptap/core @tiptap/pm @tiptap/starter-kit
starter-kit包包含了一些常用扩展，能让你快速开始。
第三步：创建基础编辑器
在项目的主HTML文件（例如index.html）中，创建一个用于挂载编辑器的元素。
接下来，在JavaScript文件（例如main.js）中，初始化编辑器。
首先导入所需模块：
import { Editor } from ‘@tiptap/core’
import StarterKit from ‘@tiptap/starter-kit’
然后，初始化一个新的Editor实例：
const editor = new Editor({
element: document.querySelector(‘#editor’),
extensions: [
StarterKit,
],
content: ‘
从这里开始编辑你的文档。
‘,
})
现在，如果你运行项目（npm run dev），应该能看到一个基础的富文本编辑器，已经支持加粗、斜体等基本格式。
第四步：添加自定义扩展
Tiptap的强大之处在于其可扩展性。你可以添加自定义节点、标记或功能。
例如，添加一个简单的自定义扩展来支持荧光笔标记。
首先，创建一个新的扩展文件（例如Highlight.js），或者直接在main.js中定义：
import { Mark } from ‘@tiptap/core’
const Highlight = Mark.create({
name: ‘highlight’,
addAttributes() {
return {
color: {
default: ‘yellow’,
},
}
},
parseHTML() {
return [
{
tag: ‘mark’,
},
]
},
renderHTML({ HTMLAttributes }) {
return [‘mark’, HTMLAttributes, 0]
},
addCommands() {
return {
setHighlight: (attributes) => ({ commands }) => {
return commands.setMark(this.name, attributes)
},
toggleHighlight: (attributes) => ({ commands }) => {
return commands.toggleMark(this.name, attributes)
},
unsetHighlight: () => ({ commands }) => {
return commands.unsetMark(this.name)
},
}
},
})
然后，将这个扩展添加到编辑器的extensions数组中：
const editor = new Editor({
element: document.querySelector(‘#editor’),
extensions: [
StarterKit,
Highlight, // 添加自定义扩展
],
content: ‘
你可以使用荧光笔标记文本。
‘,
})
为了使用这个新功能，你可以通过编辑器实例的commands来调用相关命令，或者将其绑定到UI按钮上。
第五步：构建用户界面
Tiptap本身不提供UI，你需要创建自己的工具栏。
在HTML中添加一个工具栏容器：
在JavaScript中为按钮添加事件监听器，以执行编辑器命令：
document.querySelector(‘#bold-btn’).addEventListener(‘click’, () => {
editor.chain().focus().toggleBold().run()
})
document.querySelector(‘#highlight-btn’).addEventListener(‘click’, () => {
editor.chain().focus().toggleHighlight({ color: ‘yellow’ }).run()
})
通过chain()方法可以组合多个命令，focus()确保编辑器保持焦点，run()执行命令链。
第六步：处理内容与状态
你可以随时获取和设置编辑器的内容。
获取HTML内容：
const html = editor.getHTML()
获取JSON内容（用于保存文档结构）：
const json = editor.getJSON()
设置内容：
editor.commands.setContent(‘
新的内容
‘)
监听内容变化：
editor.on(‘update’, ({ editor }) => {
console.log(‘内容已更新:’, editor.getHTML())
})
第七步：样式定制
你可以通过CSS完全控制编辑器的外观。
为编辑区域添加基本样式：
#editor {
min-height: 200px;
border: 1px solid #ccc;
padding: 1rem;
border-radius: 4px;
}
#editor:focus {
outline: none;
border-color: blue;
}
自定义荧光笔标记的颜色：
mark {
background-color: yellow;
padding: 0.1em 0.2em;
}
注意事项与进阶
1. Tiptap基于ProseMirror，因此熟悉ProseMirror的基本概念（如schema、state、transaction）有助于进行高级定制。
2. 官方提供了大量扩展，如列表、表格、代码块、图片等，可以通过npm安装使用。
3. 对于协作编辑，可以考虑@tiptap/extension-collaboration扩展。
4. 编辑器实例的生命周期管理很重要，在组件销毁时（如单页应用中）调用editor.destroy()以避免内存泄漏。
通过以上步骤，你已经创建了一个具备基本功能和自定义扩展的Tiptap富文本编辑器。你可以在此基础上继续添加更多扩展和UI组件，以满足具体的项目需求。Tiptap的模块化设计使得它既适合快速搭建简单编辑器，也适合构建复杂的文档编辑应用。
原创文章，作者：admin，如若转载，请注明出处：https://wpext.cn/874.html
