【element-tiptap】Tiptap编辑器核心概念----内容、扩展与词汇

Tiptap 需要定义非常严格的数据模式，来指定文档的结构和节点之间的嵌套方式。你可以通过下面的几个属性自定义extension 的数据模式。

• content 指明该扩展可以允许的子节点的类型
• draggable 该扩展是否可以拖拽
• group 指定自身的类型是块级还是行内
• inline 布尔值，指定是否行内显示
• marks 标记
• atom 设置为 true 表示不能有子节点，不能直接编辑内容
• attrs 节点属性
• selectable 节点能否选中
• code⁠ 布尔值 表示该节点是否包含代码，如果包含代码的话某一些命令的表现可能会不一样
• whitespace “pre” | “normal” 控制节点中空格的显示方式。默认值是 normal，会将空格折叠，并用空格代替换行符等；如果设置成 pre，不会折叠空格。如果设置成 true 的话，跟设置成 pre 是一样的效果。
• definingAsContext⁠ 布尔值，在内容被替换的时候，比如粘贴操作，是否保留该节点作为新内容的父节点。
• definingForContent⁠ 在插入内容时是否保留定义的父节点，一般用于特殊的块级元素，例如代码块、引用块等
• defining⁠ 如果设置为true，上面两个属性都会设置为true
• isolating 当启用时（默认为 false），这种类型节点的边界会被视为常规编辑操作（如退格或提升）不能跨越的边界。表格单元格就是一个可能需要启用此功能的节点示例
• toDOM 方法 定义节点是如何渲染成DOM的。返回一个DOM节点或者一个描述节点结构的对象。
• parseDOM⁠ TagParseRule [] 定义如何将 HTML 解析为编辑器的内部结构

// 1. 解析自定义格式
const CustomFormat = Mark.create({
  name: 'customFormat',
  parseDOM: [
    {
      // 样式匹配
      style: 'color',
      getAttrs: (value) => ({
        color: value
      })
    },
    {
      // 类名匹配
      tag: 'span.custom',
      getAttrs: (dom) => ({
        color: dom.style.color
      })
    }
  ]
})

// 2. 解析外部粘贴的内容
const ExternalContent = Node.create({
  name: 'external',
  parseDOM: [
    {
      tag: '[data-source="external"]',
      getAttrs: (dom) => ({
        source: dom.getAttribute('data-source'),
        id: dom.getAttribute('data-id')
      })
    }
  ]
})

• toDebugString⁠ fn(node: Node) → string 定义该节点在调试的时候显示的信息
• leafText⁠?: fn(node: Node) → string 定义将此类型的叶节点序列化为字符串的默认方式（如Node.textBetween和Node.textContent所使用的）
• linebreakReplacement 布尔值 表示该节点是否能起到换行的作用，但不使用换行符
  实际应用：

// 1. 在富文本和纯文本间转换
const convertToPlainText = () => {
  // <br> 节点会被转换为 \n
  editor.commands.setBlockType('plain')
}

// 2. 在预格式化和普通文本间转换
const togglePreformatted = () => {
  // 自动处理换行符的转换
  editor.commands.toggleBlockType('preformatted')
}

Attributes 还能一次性给多个扩展设置。例如文本对齐方式、行高、文字样式、或者其他的样式相关的属性就很适合一次性设置。例如 TextAlign 扩展

import { Extension } from '@tiptap/core'

const TextAlign = Extension.create({
  addGlobalAttributes() {
    return [
      {
        // Extend the following extensions
        types: ['heading', 'paragraph'],
        // … with those attributes
        attributes: {
          textAlign: {
            default: 'left',
            renderHTML: (attributes) => ({
              style: `text-align: ${attributes.textAlign}`,
            }),
            parseHTML: (element) => element.style.textAlign || 'left',
          },
        },
      },
    ]
  },
})

renderHTML 方法可以用来控制扩展如何转换为 HTML。它接收一个属性对象作为参数，其中包含所有自持有的属性、全局的属性以及配置的CSS类。例如下面的 Bold 扩展：

renderHTML({ HTMLAttributes }) {
  return ['strong', HTMLAttributes, 0]
},

返回的数组中的第一个元素是HTML的标签。如果第二个参数是一个对象，它就是属性的集合；如果是一个嵌套的数组，那么就是子元素。最后的数字表示元素要插入的位置。
下面是放子元素的示例：

renderHTML({ HTMLAttributes }) {
  return ['pre', ['code', HTMLAttributes, 0]]
},

如果还想在这里添加具体的属性，可以使用 mergeAttributes

import { mergeAttributes } from '@tiptap/core'

// ...

renderHTML({ HTMLAttributes }) {
  return ['a', mergeAttributes(HTMLAttributes, { rel: this.options.rel }), 0]
},

parseHTML() 方法定义从 HTML 转换为编辑器文档的方式。这个方法可以获取 HTML DOM 元素，返回一个包含属性、标签等信息的对象。
下面是一个简单的 Bold 标记的例子：

parseHTML() {
  return [
    {
      tag: 'strong',
    },
  ]
},

我们定义了一个规则，将所有的 strong 标签转为 Bold 标记。下面是一个更复杂的转换规则，将所有的 strong 标签和 b 标签，以及行内设置 font-weight 为bold或者700的标签都识别成 Bold 标记。getAttrs 方法用来匹配更复杂的规则，如果检查成功需要返回 null，所以这个方法的最后是 && null。

parseHTML() {
  return [
    // <strong>
    {
      tag: 'strong',
    },
    // <b>
    {
      tag: 'b',
      getAttrs: node => node.style.fontWeight !== 'normal' && null,
    },
    // <span style="font-weight: bold"> and <span style="font-weight: 700">
    {
      style: 'font-weight',
      getAttrs: value => /^(bold(er)?|[5-9]\d{2,})$/.test(value as string) && null,
    },
  ]
},

这个属性是用于向后端发送数据的时候，或者是在控制台打印 editor.editor.getHTML() 的时候，当前节点怎么展现。因为比如说像 latex 公式，在网页中它需要很复杂的结构来展示成 MathML，但是存储文档的话存一个 <latex>2^1=2</latex> 类似的latex公式就可以了。

给扩展增加命令，

import Paragraph from '@tiptap/extension-paragraph'

const CustomParagraph = Paragraph.extend({
  addCommands() {
    return {
      paragraph:
        () =>
        ({ commands }) => {
          return commands.setNode('paragraph')
        },
    }
  },
})

增加后就可以通过editor.commands.paragraph(); 访问

大多数核心的扩展都带有默认的快捷键，你可以使用 addKeyboardShortcuts() 方法对其进行修改

// Change the bullet list keyboard shortcut
import BulletList from '@tiptap/extension-bullet-list'

const CustomBulletList = BulletList.extend({
  addKeyboardShortcuts() {
    return {
      'Mod-l': () => this.editor.commands.toggleBulletList(),
    }
  },
})

输入规则是用定义用正则表达式监听用户输入的规则，常用于匹配 markdown 输入法。
例如下面的例子，输入 ~文字~ 的时候，会转换成 “ 文字 ”

// Use the ~single tilde~ markdown shortcut
import Strike from '@tiptap/extension-strike'
import { markInputRule } from '@tiptap/core'

// Default:
// const inputRegex = /(?:^|\s)((?:~~)((?:[^~]+))(?:~~))$/

// New:
const inputRegex = /(?:^|\s)((?:~)((?:[^~]+))(?:~))$/

const CustomStrike = Strike.extend({
  addInputRules() {
    return [
      markInputRule({
        find: inputRegex,
        type: this.type,
      }),
    ]
  },
})

粘贴规则类似于上面的输入规则，监听用户的粘贴的内容，如果有匹配上的字符串就进行转换。
不过在写正则表达式的时候有些不一样，输入规则通常要以指定的符号为开头和结尾，分别使用 ^ 和 $ 表示。但是粘贴只需要找字符串中成对出现的所有符号，不用考虑是否在一定要以某符号开头和结尾，例如 文本~~删除线1~~文本~~删除线2~~ 这种形式也可以转换成 “文本删除线1文本删除线2”，因此正则表达式会更灵活

// Check pasted content for the ~single tilde~ markdown syntax
import Strike from '@tiptap/extension-strike'
import { markPasteRule } from '@tiptap/core'

// Default:
// const pasteRegex = /(?:^|\s)((?:~~)((?:[^~]+))(?:~~))/g

// New:
const pasteRegex = /(~~([^~]+)~~)/g;

const CustomStrike = Strike.extend({
  addPasteRules() {
    return [
      markPasteRule({
        find: pasteRegex,
        type: this.type,
      }),
    ]
  },
})

编辑器的生命周期函数以及监听器可以放在扩展中

import { Extension } from '@tiptap/core'

const CustomExtension = Extension.create({
  onCreate() {
    // The editor is ready.
  },
  onUpdate() {
    // The content has changed.
  },
  onSelectionUpdate({ editor }) {
    // The selection has changed.
  },
  onTransaction({ transaction }) {
    // The editor state has changed.
  },
  onFocus({ event }) {
    // The editor is focused.
  },
  onBlur({ event }) {
    // The editor isn’t focused anymore.
  },
  onDestroy() {
    // The editor is being destroyed.
  },
})

在扩展中，有几个属性可以通过 this 来访问

// extension 的名字，例如 'bulletList'
this.name

// Editor 实例
this.editor

// ProseMirror 类型
this.type

// 配置项
this.options

// 被继承的 extension 的所有信息
this.parent

Tiptap 是在 ProseMirror 的基础上开发的，ProseMirror提供了强大的插件 API。使用 addProseMirrorPlugins() 向扩展中添加插件。

• 添加现成的插件

import { history } from '@tiptap/pm/history'

const History = Extension.create({
  addProseMirrorPlugins() {
    return [
      history(),
      // …
    ]
  },
})

• 使用插件 API 创建新的插件，例如下面代码创建一个事件处理的插件

import { Extension } from '@tiptap/core'
import { Plugin, PluginKey } from '@tiptap/pm/state'

export const EventHandler = Extension.create({
  name: 'eventHandler',

  addProseMirrorPlugins() {
    return [
      new Plugin({
        key: new PluginKey('eventHandler'),
        props: {
          handleClick(view, pos, event) {
            /* … */
          },
          handleDoubleClick(view, pos, event) {
            /* … */
          },
          handlePaste(view, event, slice) {
            /* … */
          },
          // … and many, many more.
          // Here is the full list: https://prosemirror.net/docs/ref/#view.EditorProps
        },
      }),
    ]
  },
})

在某些情况下，你需要动态运行 JavaScript 来创建节点，例如给图片渲染一个外框框，此时就需要使用 addNodeView 方法。这个方法需要返回父节点和当前节点

import Image from '@tiptap/extension-image'

const CustomImage = Image.extend({
  addNodeView() {
    return () => {
      const container = document.createElement('div')

      container.addEventListener('click', (event) => {
        alert('clicked on the container')
      })

      const content = document.createElement('div')
      container.append(content)

      return {
        dom: container,
        contentDOM: content,
      }
    }
  },
})