core-concepts
前言：这篇文章来介绍一下 Tiptap 编辑器的一些核心概念

（一）结构

1、 Schemas

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

new Editor({
  enableContentCheck: true,
  content: invalidContent,
  onContentError({ editor, error, disableCollaboration }) {
    // your handler here
  },
  ...options,
})

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

editor.on('contentError', ({ editor, error, disableCollaboration }) => {
  // your handler here
})

2、Marks

标记可以附加到每一个节点上，用来给节点的某些特殊的部分增加样式或者注释文本。
在 schema 中，必须指定可以允许的 marks 的类型，和上面的 schema 中指定 nodes 的写法类似。
默认情况下，带有行内内容的节点会允许所有的在 schema 中定义的 marks 应用于它们的子节点，但是可以在节点的 marks 属性中进行自定义。
例如下面这个简单的 schema，允许 strong 和 em 标记应用于 paragraphs 中的文本，但是不允许应用于 headings 中的文本：

const markSchema = new Schema({
  nodes: {
    doc: {content: "block+"},
    paragraph: {group: "block", content: "text*", marks: "_"},
    heading: {group: "block", content: "text*", marks: ""},
    text: {inline: true}
  },
  marks: {
    strong: {},
    em: {}
  }
})

标记集合会被解析成标记的所有名称以空格分隔的字符串的形式，_ 会作为一个通配符，匹配所有的标记；而空字符串表示不允许任何的标记。
Tiptap 中提供了一系列 marks 扩展

3、commands

① 执行 command

通过编辑器实例上的 commands 属性，调用 command

editor.commands.setBold()

像酱紫执行命令就可以让文本加粗

② 链式执行 command

大多数的命令都可以合并到一次调用中，这会比单独调用函数更加高效。下面的例子是让选中的文本加粗

editor.chain().focus().toggleBold().run()

chain() 用来开启新的执行链，run() 方法用来实际执行所有的命令。这些命令很可能都是通过点击按钮触发的，但是按钮通常不在编辑器内部，所有可能会需要先执行 focus 聚焦于编辑器，然后再执行 toggleBold 方法加粗选中的文本。所以大部分命令在执行前都会先链式调用 focus()，这样用户就可以继续进行编辑操作。
执行链上的方法是排着队执行的。一个执行链上的方法会被合并到一个 transaction 中，一个执行链只会触发一次更新监听器。
默认情况下，ProseMirror 是不支持链式操作的，我们需要通过 Transaction mapping 在命令执行链中更新位置。
下面是一个例子，链式执行删除和插入命令：

// 添加两个自定义命令演示两个 transaction 步骤之间的映射
addCommands() {
  return {
    delete: () => ({ tr }) => {
      const { $from, $to } = tr.selection

      // 使用 tr.mapping.map 在 transaction 步骤之间映射位置
      const from = tr.mapping.map($from.pos)
      const to = tr.mapping.map($to.pos)

      tr.delete(from, to)

      return true
    },
    insert: (content: string) => ({ tr }) => {
      const { $from } = tr.selection

      // 使用 tr.mapping.map 在 transaction 步骤之间映射位置
      const pos = tr.mapping.map($from.pos)

      tr.insertText(content, pos)

      return true
    },
  }
}

现在就可以执行下面的操作，确保插入内容时位置不会错误

editor.chain().delete().insert('foo').run()

③ 自定义命令中的链

当链接到一个命令的时候，事务会处于保留状态。如果你想链式调用自定义命令，你需要使用当前的事务，并且将你的自定义命令添加到当前的调用链上，如以下代码：

addCommands() {
  return {
    customCommand: attributes => ({ chain }) => {
      // Doesn’t work:
      // return editor.chain() …

      // Does work:
      return chain()
        .insertContent('foo!')
        .insertContent('bar!')
        .run()
    },
  }
}

④ 行内命令

如果命令中执行的代码比较简单，可以直接写成行内命令的形式：

editor
  .chain()
  .focus()
  .command(({ tr }) => {
    // manipulate the transaction
    tr.insertText('hey, that’s cool!')
    return true
  })
  .run()

⑤ 空运行命令

在执行某些命令之前，可以使用 can() 方法，来判断这个命令能不能执行，例如在菜单中的按钮能不能显示等。这个方法不会执行任何修改而只是会判断后面跟的命令是否可以执行。

editor.can().toggleBold()

can() 方法也可以和 chain() 一起使用，来判断是否执行链上所有的方法都可以执行

editor.can().chain().toggleBold().toggleItalic().run()

如果链式操作中的所有命令都能执行，can() 方法才会返回 true。如果其中有自定义命令，切记要返回布尔值。
就是说上面一连串的方法，最后返回的是个布尔值，不会有任何的修改。

⑥ 尝试命令

如果有一连串的命令，运行一个命令成功后，就不再往后执行，就可以使用 first 命令。好像有 if~else~ 的作用，或者是替代 can() 判断的作用。
例如下面的例子，backspace 键会首先去尝试撤销一个输入规则；如果成功的话就执行这个操作，如果失败的话就执行下一个命令，删除选区内容

editor.first(({ commands }) => [
  () => commands.undoInputRule(),
  () => commands.deleteSelection(),
  // …
])

下面的写法作用相同：

export default () =>
  ({ commands }) => {
    return commands.first([
      () => commands.undoInputRule(),
      () => commands.deleteSelection(),
      // …
    ])
  }

就是说如果当前焦点是一个列表，点击删除键，会列表输入规则删除，变成普通的文本输入

⑦ 关键命令列表

内容

节点&标记

列表

选区