前言

Tiptap 是基于 ProseMirror 开发的一款用于构建富文本编辑器的工具包。

Tiptap 本身自带一些合理的默认值，并且可以在其基础上进行大量的扩展，Tiptap 是高度自定义的，具有友好的 API 供我们使用，社区活跃，开源、免费。

Tiptap 声称是无头（headless）的包装器，因为不提供用户交互界面，这使得我们完全可以自由地去构建用户界面，而不受样式的约束。

Tiptap 支持目前主流的前端框架，如 Vue、React、Nuxt.js、Next.js、Svelte 等。

快速上手

创建项目

本文以 Next.js 为例，在项目中集成 Tiptap，初始化富文本编辑器，接下来根据官网操作步骤进行安装。

首先，得准备一个 Next.js 项目，用于学习 Tiptap 开发。

可以在终端命令行输入 npx create-next-app my-tiptap-project 创建 Next.js 项目。

或者阅读《配置一个 Next.js 项目模板，用于项目快速开发》这篇文章，学习创建并配置一个 Next.js 项目。

安装依赖

准备好 Next.js 项目之后，进行 Tiptap 核心依赖的安装。

在终端命令行输入 npm install @tiptap/react @tiptap/pm @tiptap/starter-kit。

引入组件

安装好 Tiptap 相关依赖之后，还需要创建一个组件，用于初始化 Tiptap。

在项目中创建 src/components/editor 文件夹，然后新建 index.tsx 文件，应包含如下代码。

'use client'

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

const Tiptap = () => {
  const editor = useEditor({
    extensions: [StarterKit],
    content: '<p>Hello World! 🌎️</p>',
  })

  return <EditorContent editor={editor} />
}

export default Tiptap

然后可以创建一个 src/app/editor/page.tsx 文件，引入刚创建的组件，专门用于测试学习 Tiptap。

import TiptapEditor from '@/components/editor'

export default function Page() {
  return (
    <>
      <TiptapEditor />
    </>
  )
}

最后，在浏览器输入 http://localhost:3000/editor 就会展示组件 editor 中的内容。

这样，一个最基本的 Tiptap 编辑器就初始化完毕，但是由于 Tiptap 是高度自定义的，因此关于富文本的一些内容还需要我们根据官网的 Tiptap API 和 Tiptap Guides 去按需自定义配置。

自定义配置

学习使用 Tiptap 开发编辑器，最重要的就是多看官方文档，多读官方文档，一定要熟悉 Tiptap 的 API 和一些扩展配置项，这样才能事半功倍，不然可能会踩很多坑。

增加样式

因为 TipTap 是无头的，不提供样式，所以在官方文档 Tiptap Editor Guides 中的 Styling 这一小节中介绍了如何自定义编辑器，根据业务需求实现自己的专属的样式。

TipTap API Editor 中提供了一种方式可以设置 editorProps 来更改 DOM 元素属性，如添加一些 Tailwind CSS 类来更改样式，因此我们可以试着使用这种方式来自定义编辑器的高度和背景色。

基于上述创建的 editor 组件修改为如下代码，通过 editorProps 中的 attributes 添加类名。

'use client'

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

const Tiptap = () => {
  const editor = useEditor({
    extensions: [StarterKit],
    content: '<p>Hello World! 🌎️</p>',
    editorProps: {
      // 给 DOM 元素增加 Tailwind CSS 类
      attributes: {
        class: 'min-h-14 bg-slate-100',
      },
    },
  })

  return <EditorContent editor={editor} />
}

export default Tiptap

在浏览器输入 http://localhost:3000/editor 后，就会展示上述所设置的效果，背景色为浅灰色，高度 56px。

继续增加样式，使其编辑器本身具备样式，不然无法正确显示内容的样式。

在命令行终端输入 npm install @tailwindcss/typography 安装插件为所有的标签增加样式。

然后，在 editor 组件中通过 editorProps 中的 attributes 添加类名。

editorProps: {
  // 给 DOM 元素增加 Tailwind CSS 类
  attributes: {
    class: 'min-h-14 bg-slate-100 prose lg:prose-lg focus:outline-none'
  }
}

最后，在 tailwind.config.ts 文件中引入插件 plugins: [require('@tailwindcss/typography')]。

使用插件

Extensions

TipTap API Extensions 这一项中提供了最流行的 TipTap 扩展的集合 StarterKit，该集合包括最基本的文本格式和编辑功能，支持回车换行、MarkDown 快捷键、撤销等功能。

在初始化 TipTap 的时候，我们已经安装完 @tiptap/starter-kit 这个依赖，并且也在 TipTap 中的扩展项中引入，其实已经具备最基本的编辑能力。

在浏览器输入 http://localhost:3000/editor 后，直接在编辑器中书写 MarkDown 测试效果。

Placeholder

在编辑器的基础上增加一个 Placeholder 的扩展，用来给予用户一个友好的提示效果。

在命令行终端输入 npm install @tiptap/extension-placeholder 安装扩展。

还需要为其设置样式，新建 src/components/editor/index.css 文件，新增如下内容。

.tiptap p.is-editor-empty:first-child::before {
  color: #adb5bd;
  content: attr(data-placeholder);
  float: left;
  height: 0;
  pointer-events: none;
}

在上述 editor 组件中的 extensions 中增加该扩展，并配置提示文字，增加后的组件内容为如下代码。

'use client'

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

const Tiptap = () => {
  const editor = useEditor({
    extensions: [
      StarterKit,
      Placeholder.configure({
        placeholder: '请输入内容…',
      }),
    ],
    content: '<p>Hello World! 🌎️</p>',
    editorProps: {
      attributes: {
        class: 'min-h-14 bg-slate-100 prose lg:prose-lg focus:outline-none',
      },
    },
  })

  return <EditorContent editor={editor} />
}

export default Tiptap

在浏览器输入 http://localhost:3000/editor 后，清空内容，就会提示输入内容。

更多 Extensions 可参照官方文档进行自定义扩展。

总结

Tiptap 提供的功能非常丰富，上述内容只是其中的冰山一角，更多丰富的功能还需我们深度阅读官方文档去自行实现，正是 Tiptap 提供的这种底层的能力，我们才能自定义编辑器。

值得一提的是，Tiptap 主打协同编辑，这是 Tiptap 区别于其他富文本编辑器的一大亮点。

同时，Tiptap 也具备 AI 的能力，只需要几行代码就可以将 Content AI 集成到 TipTap 编辑器中，为我们提供 AI 增强功能，如预构建命令、提示自定义、图像生成和智能自动完成等功能。

使用 Tiptap 打造你的专属编辑器

前言