Tiptap 初体验

Tiptap 是一个基于 ProseMirror 的富文本编辑器框架。它本身不是一个开箱即用的完整编辑器界面，而是一套可组合、可扩展的编辑器内核。开发者可以按业务需要选择扩展、设计工具栏，并决定最终保存 HTML、JSON 或其他格式。

适合做什么

Tiptap 适合用来构建后台内容编辑器、博客文章编辑器、文档编辑器、评论输入框、知识库编辑器等场景。它的优势是编辑体验接近常见富文本工具，同时又能保留较强的可定制能力。

基础安装

在 React 项目中，常见的基础依赖包括：

pnpm add @tiptap/react @tiptap/starter-kit

如果需要链接、下划线、占位提示等能力，可以继续安装对应扩展：

pnpm add @tiptap/extension-link @tiptap/extension-underline @tiptap/extension-placeholder

创建编辑器

React 中通常使用 `useEditor` 创建编辑器实例，然后使用 `EditorContent` 渲染编辑区域。

import { EditorContent, useEditor } from '@tiptap/react'
import StarterKit from '@tiptap/starter-kit'

export function BasicEditor() {
  const editor = useEditor({
    extensions: [StarterKit],
    content: '<p>Hello Tiptap</p>',
  })

  return <EditorContent editor={editor} />
}

常用命令

Tiptap 使用链式命令操作内容和格式。常见命令包括加粗、斜体、标题、列表、引用和撤销重做。

editor.chain().focus().toggleBold().run()
editor.chain().focus().toggleItalic().run()
editor.chain().focus().toggleHeading({ level: 2 }).run()
editor.chain().focus().toggleBulletList().run()
editor.chain().focus().toggleBlockquote().run()
editor.chain().focus().undo().run()

获取内容

Tiptap 可以输出不同格式的内容。常见做法是编辑时使用 Tiptap 内部文档结构，保存时按业务需要导出 HTML 或 JSON。

const html = editor.getHTML()
const json = editor.getJSON()
const text = editor.getText()

如果文章最终用于网页展示，保存 HTML 片段会比较直接。如果需要后续继续进行结构化编辑、协作或复杂解析，保存 JSON 会更灵活。

设置内容

可以通过 `setContent` 把已有内容写入编辑器。

editor.commands.setContent('<h2>标题</h2><p>正文内容</p>')

如果后端返回的是 Tiptap JSON，也可以直接写入：

editor.commands.setContent({
  type: 'doc',
  content: [
    {
      type: 'paragraph',
      content: [{ type: 'text', text: '这是一段正文' }],
    },
  ],
})

常见扩展

`StarterKit`：提供段落、标题、列表、引用、代码块、撤销重做等基础能力。
`Link`：支持链接。
`Underline`：支持下划线。
`Placeholder`：支持空内容占位提示。
`TextAlign`：支持段落和标题对齐。

一个简单工具栏思路

工具栏本质上是一些按钮，每个按钮调用对应的编辑器命令。按钮状态可以通过 `editor.isActive()` 判断。

<button
  className={editor.isActive('bold') ? 'active' : ''}
  onClick={() => editor.chain().focus().toggleBold().run()}
>
  Bold
</button>

使用建议

先明确保存格式：HTML 适合展示，JSON 适合结构化编辑。
编辑器能力不要一次加太多，先覆盖标题、段落、列表、引用、代码块、链接等基础功能。
如果保存 HTML，需要做 HTML 白名单清洗，避免脚本和危险属性进入数据库。
文件导入场景中，可以先把 Markdown、PDF、Word 转成 Tiptap JSON，再写入编辑器。
如果用于代码内容较多的场景，可以禁用浏览器拼写检查，避免英文标识符被标红。

总结

Tiptap 的核心价值在于“编辑器能力可组合”。它不像传统富文本编辑器那样只给固定配置，而是允许开发者围绕业务构建自己的编辑体验。对于后台文章系统来说，Tiptap 可以用较少的基础扩展实现稳定的富文本编辑，并在后续逐步扩展到文件导入、结构化内容、协作编辑等能力。

Tiptap 初体验

标签

文章助手

推荐文章

欢迎来到我的博客

认识 useLayoutEffect

Next.js 开发技巧

Tiptap 初体验

标签

文章助手

推荐文章

欢迎来到我的博客

认识 useLayoutEffect

Next.js 开发技巧