在UmiJS项目中正确使用Tiptap富文本编辑器

Tiptap是一个基于ProseMirror构建的现代化富文本编辑器框架，它提供了React、Vue等流行前端框架的封装。本文将详细介绍如何在UmiJS项目中正确集成Tiptap编辑器，并解决常见的配置问题。

常见错误分析

许多开发者在UmiJS项目中初次使用Tiptap时，会遇到"Schema is missing its top node type ('doc')"的错误。这个错误的核心原因是编辑器实例没有正确配置必要的扩展(extensions)。

解决方案

要解决这个问题，必须为Tiptap编辑器提供至少一个文档节点类型和基本功能扩展。以下是完整的配置示例：

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

const MarkdownEditor = () => {
    const editor = useEditor({
        extensions: [
            StarterKit,
        ],
        content: '<p>Hello World!</p>',
    })
    
    return (
        <EditorContent editor={editor} />
    )
}

关键配置说明

1. StarterKit扩展：这是Tiptap提供的一个包含基本功能的扩展包，包括了段落、标题、粗体、斜体等常见格式支持。

2. content属性：设置编辑器的初始内容，可以是HTML字符串或JSON格式。

3. extensions数组：这是必须配置的选项，用于定义编辑器支持的功能。

进阶配置

除了基本配置外，Tiptap还支持许多强大的功能：

import { useEditor, EditorContent } from '@tiptap/react'
import StarterKit from '@tiptap/starter-kit'
import Underline from '@tiptap/extension-underline'
import Link from '@tiptap/extension-link'

const MarkdownEditor = () => {
    const editor = useEditor({
        extensions: [
            StarterKit,
            Underline,
            Link.configure({
                openOnClick: false,
            }),
        ],
        content: '<p>自定义配置的编辑器</p>',
    })
    
    return (
        <EditorContent editor={editor} />
    )
}

最佳实践建议

1. 对于UmiJS项目，建议将编辑器封装为独立组件，便于复用和维护。

2. 根据项目需求选择适当的扩展，避免加载不必要的功能影响性能。

3. 考虑添加自定义样式，使编辑器与项目UI风格保持一致。

4. 对于复杂需求，可以创建自定义节点类型和扩展。

通过以上配置和最佳实践，开发者可以轻松地在UmiJS项目中集成功能丰富的Tiptap编辑器，避免常见的配置错误。