Tiptap 模式

与许多其他编辑器不同,Tiptap 基于一个 模式,定义了内容的结构。这使您能够定义文档中可能出现的节点类型、其属性以及如何嵌套它们。

这个模式是 非常 严格的。您不能使用未在您的模式中定义的任何 HTML 元素或属性。

让我给你一个例子:如果您将类似 This is <strong>important</strong> 的内容粘贴到 Tiptap 中,而没有处理 strong 标签的扩展,您将只会看到 This is important — 没有 strong 标签。

如果想知道何时发生这种情况,可以启用 enableContentCheck 选项并监听 contentError 事件。

模式是什么样子的

当您完全使用提供的扩展时,其实不需要太在意模式。如果您正在构建自己的扩展,那么了解模式的工作方式可能会很有帮助。让我们看看典型 ProseMirror 编辑器最简单的模式:

// 底层 ProseMirror 模式
{
  nodes: {
    doc: {
      content: 'block+',
    },
    paragraph: {
      content: 'inline*',
      group: 'block',
      parseDOM: [{ tag: 'p' }],
      toDOM: () => ['p', 0],
    },
    text: {
      group: 'inline',
    },
  },
}

我们在这里注册了三个节点。doc、paragraph 和 text。doc 是根节点,允许一个或多个块节点作为子节点(content: 'block+')。因为 paragraph 在块节点组中(group: 'block'),所以我们的文档只能包含段落。我们的段落允许零个或多个内联节点作为子节点(content: 'inline*'),所以其中只能有 text。parseDOM 定义了如何从粘贴的 HTML 中解析节点。toDOM 定义了它将如何在 DOM 中呈现。

在 Tiptap 中,每个节点、标记和扩展都生活在自己的文件中。这使我们可以将逻辑分开。在底层,整个模式将被合并在一起:

// Tiptap 模式 API
import { Node } from '@tiptap/core'

const Document = Node.create({
  name: 'doc',
  topNode: true,
  content: 'block+',
})

const Paragraph = Node.create({
  name: 'paragraph',
  group: 'block',
  content: 'inline*',
  parseHTML() {
    return [{ tag: 'p' }]
  },
  renderHTML({ HTMLAttributes }) {
    return ['p', HTMLAttributes, 0]
  },
})

const Text = Node.create({
  name: 'text',
  group: 'inline',
})

使用外部 SchemaSpec

将完整的 ProseMirror SchemaSpec 传给编辑器的 schemaSpec 选项,即可将文档结构与本地扩展行为分开定义。当多个编辑器需要共享相同结构,但使用不同的渲染或交互代码时,可以采用这种方式。

此规范控制节点和标记的结构。本地扩展仍负责提供 HTML 解析和渲染、文本序列化、命令、键盘快捷键、节点视图及插件。

import { Editor } from '@tiptap/core'
import Bold from '@tiptap/extension-bold'
import Document from '@tiptap/extension-document'
import Paragraph from '@tiptap/extension-paragraph'
import Text from '@tiptap/extension-text'
import type { SchemaSpec } from '@tiptap/pm/model'

const schemaSpec: SchemaSpec = {
  nodes: {
    doc: { content: 'block+' },
    paragraph: {
      group: 'block',
      content: 'inline*',
      marks: 'bold',
      attrs: {
        tone: { default: 'newsletter', validate: 'string' },
      },
    },
    text: { group: 'inline' },
  },
  marks: {
    bold: {},
  },
}

const LocalParagraph = Paragraph.extend({
  addAttributes() {
    return {
      tone: {
        parseHTML: (element) => element.getAttribute('data-tone'),
        renderHTML: (attributes) => ({ 'data-tone': attributes.tone }),
      },
    }
  },
})

const editor = new Editor({
  element: document.querySelector('.editor'),
  extensions: [Document, LocalParagraph, Text, Bold],
  schemaSpec,
  content: '<p>Hello <strong>world</strong>.</p>',
})

editor.getHTML()
// '<p data-tone="newsletter">Hello <strong>world</strong>.</p>'

在此示例中,schemaSpec 允许粗体文本,并设置 tone 属性的默认值。LocalParagraph 继承段落渲染行为,并将 tone 映射到 HTML 的 data-tone 属性。Bold 扩展提供 <strong> 的解析和渲染,以及 toggleBold 命令。

匹配扩展

此规范和解析后的扩展必须包含完全相同的节点和标记名称。规范中的节点需要对应的本地节点扩展,标记也需要对应的本地标记扩展。本地节点或标记名称重复时会被拒绝。

不定义节点或标记的扩展可以添加到编辑器中,无需在此规范中声明。例如,仅添加键盘快捷键的扩展不需要对应条目。

如果使用 StarterKit,请在规范中包含它启用的所有节点和标记,或禁用未纳入规范的类型。仅包含段落的规范不能与默认 StarterKit 配置搭配使用。

本地节点和标记扩展可以只定义行为,其结构字段和属性则完全由 schemaSpec 提供。

结构规则

外部规范会替换本地结构字段,而不会填补缺失字段。如果省略某个字段,ProseMirror 会使用默认值,而不是本地扩展中的值。

  • 对于节点,此规范控制 content、marks、group、inline、atom、selectable、draggable、code、whitespace、definingAsContext、definingForContent、defining、isolating 和 linebreakReplacement。
  • 对于标记,此规范控制 inclusive、excludes、group、spanning 和 code。
  • 无论本地扩展优先级如何,此规范都会决定顶层节点以及节点和标记的顺序。

DOM 行为应保留在本地扩展中。外部规范中的 parseDOM 和 toDOM 字段会被忽略。tableRole 和 allowGapCursor 等自定义 schema 元数据也由本地扩展提供。

属性规则

此规范控制节点和标记的属性名称、默认值、必需性和验证规则。

  • 规范中不存在的本地属性会被移除,包括通过 addGlobalAttributes() 添加的属性。
  • 匹配的本地属性会保留其 parseHTML、renderHTML、rendered 和 keepOnSplit 行为;默认值和验证规则则由此规范提供。
  • 仅在规范中声明的属性会使用 Tiptap 默认的属性解析和渲染方式。如果需要自定义 HTML 表示形式,请定义本地属性钩子。
  • 未设置 default 的属性为必需属性。创建使用该属性的内容时,请提供属性值。

验证和更新

创建编辑器时,如果 schema 结构无效、结构字段类型无效、缺少本地实现、本地节点或标记类型多于规范,或本地类型名称重复,Tiptap 都会拒绝创建。

此规范只会在创建编辑器时应用。editor.setOptions({ schemaSpec }) 不会重建 schema。要更改结构,请创建新的编辑器,并迁移现有内容以符合新规范。

如果省略 schemaSpec,Tiptap 仍会根据本地扩展构建 schema。

节点和标记

区别

节点就像内容块,例如段落、标题、代码块、引用等等。

标记可以应用于节点的特定部分。这适用于 粗体、斜体 或 删除 文本。链接 也是标记。

节点模式

内容

内容属性精确地定义了节点可以包含什么样的内容。ProseMirror 对此非常严格。这意味着,不符合模式的内容将被抛弃。它需要一个字符串形式的名称或组。以下是一些示例:

Node.create({
  // 必须有一个或多个块
  content: 'block+',

  // 必须有零个或多个块
  content: 'block*',

  // 允许所有类型的“内联”内容(文本或硬换行)
  content: 'inline*',

  // 不能有除“文本”之外的其他内容
  content: 'text*',

  // 可以有一个或多个段落,或列表(如果使用列表)
  content: '(paragraph|list?)+',

  // 必须在顶部有一个确切的标题,并在下面有一个或多个块
  content: 'heading block+',
})

标记

您可以使用架构的 marks 设置来定义节点内部允许使用哪些标记。添加一个或多个名称或一组标记,允许所有或禁止所有标记,如下所示:

Node.create({
  // 只允许“粗体”标记
  marks: 'bold',

  // 只允许“粗体”和“斜体”标记
  marks: 'bold italic',

  // 允许所有标记
  marks: '_',

  // 不允许所有标记
  marks: '',
})

组

将该节点添加到一组扩展中,可以在模式的 content 属性中引用。

Node.create({
  // 添加到“block”组
  group: 'block',

  // 添加到“inline”组
  group: 'inline',

  // 添加到“block”和“list”组
  group: 'block list',
})

内联

节点也可以被渲染为内联。当设置 inline: true 时,节点与文本内联渲染。这适用于提及。结果更像是一个标记,但具有节点的功能。一个区别是生成的 JSON 文档。多个标记同时应用,内联节点将导致嵌套结构。

Node.create({
  // 使节点与文本内联渲染,例如
  inline: true,
})

对于某些需要标记中不可用的功能的情况,例如节点视图,尝试看看内联节点是否可行:

Node.create({
  name: 'customInlineNode',
  group: 'inline',
  inline: true,
  content: 'text*',
})

内联节点可能很难选择,特别是在行边缘。快速修复:在使用 CSS 后,元素后面添加一个零宽空格:

.customInlineNode::after {
  content: "\200B";
}

原子

设置 atom: true 的节点不可直接编辑,应视为一个单元。在编辑器上下文中使用这种情况并不常见,但这将是其样子:

Node.create({
  atom: true,
})

一个例子是 Mention 扩展,它看起来像文本,但更像一个单一单元。由于它没有可编辑的文本内容,因此在复制此类节点时它是空的。不过,好消息是你可以控制这一点。以下是 Mention 扩展的示例:

// 用于将原子节点转换为纯文本
renderText({ node }) {
  return `@${node.attrs.id}`
},

可选择

除了已经可见的文本选择外,还有一个不可见的节点选择。如果您想使您的节点可选择,可以这样配置:

Node.create({
  selectable: true,
})

可拖动

所有节点都可以通过此设置配置为可拖动(默认情况下不是):

Node.create({
  draggable: true,
})

代码

用户期望代码的行为非常不同。对于所有包含代码的节点,您可以设置 code: true 以考虑这一点。

Node.create({
  code: true,
})

空格

控制此节点中的空格解析方式。

Node.create({
  whitespace: 'pre',
})

定义

当节点的完整内容被替换(例如,粘贴新内容)时,节点会默认被丢弃。如果节点在替换操作中应保留,请将其配置为 defining。

通常,这适用于 Blockquote、CodeBlock、Heading 和 ListItem。

Node.create({
  defining: true,
})

隔离

对于应在常规编辑操作(如退格)中封闭光标的节点,例如 TableCell,设置 isolating: true。

Node.create({
  isolating: true,
})

允许间隙光标

Gapcursor 扩展注册了一个新模式属性,用于控制该节点的各个地方是否允许间隙光标。

Node.create({
  allowGapCursor: false,
})

表格角色

Table 扩展注册一个新的架构属性来配置节点具有的角色。允许的值为 table、row、cell 和 header_cell。

Node.create({
  tableRole: 'cell',
})

标记模式

包含

如果您不希望标记在光标处于末尾时处于活动状态,请设置 inclusive 为 false。例如,这就是 Link 标记的配置方式:

Mark.create({
  inclusive: false,
})

排除

默认情况下,所有标记可以同时应用。通过 excludes 属性,您可以定义哪些标记不得与标记共存。例如,内联代码标记排除了任何其他标记(粗体、斜体及所有其他)。

Mark.create({
  // 不得与粗体标记共存
  excludes: 'bold',
  // 排除任何其他标记
  excludes: '_',
})

可退出

默认情况下,标记会“困住”光标,这意味着光标无法从标记中退出,除非通过从左到右移动光标到没有标记的文本中。 如果将此设置为 true,则标记在节点末尾时将是可退出的。这对于使用代码标记非常方便。

Mark.create({
  // 使此标记可退出 - 默认值为 false
  exitable: true,
})

组

将此标记添加到一组扩展中,可以在模式的 content 属性中引用。

Mark.create({
  // 将此标记添加到“基本”组
  group: 'basic',
  // 将此标记添加到“基本”和“foobar”组
  group: 'basic foobar',
})

代码

用户期望代码的行为非常不同。对于所有包含代码的标记,您可以设置 code: true 以考虑这一点。

Mark.create({
  code: true,
})

跨越

默认情况下,标记在作为 HTML 渲染时可以跨越多个节点。设置 spanning: false 以指示标记不得跨越多个节点。

Mark.create({
  spanning: false,
})

获取底层 ProseMirror 模式

有几个用例需要处理底层模式。如果您使用 Tiptap 的协作文本编辑功能,或者希望手动将内容呈现为 HTML,则需要此。

选项 1:使用编辑器

如果您需要在客户端并且无论如何都需要编辑器实例,它可以通过编辑器访问:

import { Editor } from '@tiptap/core'
import Document from '@tiptap/extension-document'
import Paragraph from '@tiptap/extension-paragraph'
import Text from '@tiptap/extension-text'

const editor = new Editor({
  extensions: [
    Document,
    Paragraph,
    Text,
    // 在这里添加更多扩展
  ]
})

const schema = editor.schema

选项 2:不使用编辑器

如果您只想获得模式 而不 初始化实际编辑器,可以使用 getSchema 辅助函数。它需要一个可用扩展的数组,并且方便地为您生成 ProseMirror 模式:

import { getSchema } from '@tiptap/core'
import Document from '@tiptap/extension-document'
import Paragraph from '@tiptap/extension-paragraph'
import Text from '@tiptap/extension-text'

const schema = getSchema([
  Document,
  Paragraph,
  Text,
  // 在这里添加更多扩展
])

无效模式处理

为了跟踪和响应内容错误,Tiptap 支持检查提供的内容是否与从注册的扩展派生的模式相匹配。 要使用此功能,请将 enableContentCheck 选项设置为 true,这会激活内容检查并发出 contentError 事件。 这些事件可以通过 onContentError 回调来监听。 默认情况下,此标志设置为 false,以保持与以前版本的兼容性。

注意

Tiptap 进行的内容检查在 JSON 内容类型上是 100% 准确的。但是,如果您将内容提供为 HTML,我们尽力警告缺少的节点,但在某些情况下可能会遗漏标记,因此,默认情况下会恢复到删除未识别内容的默认行为。

contentError 事件

当在编辑器设置期间提供的初始 content 与模式不兼容时,会发出 contentError 事件。

作为错误上下文的一部分,您将获得一个 disableCollaboration 函数。调用此函数会重新初始化编辑器,而不使用协作扩展,确保任何已删除的内容不会与其他用户同步。

此事件可以通过 onContentError 直接处理,如下所示:

new Editor({
  enableContentCheck: true,
  content: invalidContent,
  onContentError({ editor, error, disableCollaboration }) {
    // 在这里处理
  },
  ...options,
})

或者,通过将监听器附加到编辑器实例上的 contentError 事件。

const editor = new Editor({
  enableContentCheck: true,
  content: invalidContent,
  ...options,
})

editor.on('contentError', ({ editor, error, disableCollaboration }) => {
  // 在这里处理
})

有关更多实现示例,请参考 events 部分。

在不启用内容检查的情况下监听 contentError 事件

如果您想在不启用内容检查的情况下监听 contentError 事件,请在初始化 Tiptap 编辑器时将 emitContentError 设置为 true:

new Editor({
  enableContentCheck: false,
  emitContentError: true,
  ...options,
})

此设置允许您在编辑器中拥有无效内容,但仍会在内容无效时收到通知。

推荐处理

您处理模式错误的方式将取决于您的应用程序和要求,但以下是我们的建议:

不使用协作编辑

根据您的用例,删除未知内容的默认行为使您的内容保持在已知有效状态,以供将来编辑。

使用协作编辑

根据您的用例,您可能希望设置 enableContentCheck 标志,并监听 contentError 事件。当收到此事件时,您可能希望类似于以下示例进行响应:

onContentError({ editor, error, disableCollaboration }) {
  // 删除协作扩展。
  disableCollaboration()

  // 由于内容无效,我们不想发出更新
  // 防止与其他编辑器或服务器同步
  const emitUpdate = false

  // 禁用编辑器以防止进一步的用户输入
  editor.setEditable(false, emitUpdate)

  // 可能向用户显示通知,告知他们需要刷新应用程序
}