【element-tiptap】Tiptap编辑器介绍

前言：写了好几篇文章都是扩展编辑器的功能的，其中很多功能都是在开源的代码的基础上进行修改。做了这么多功能深切的觉得应该深入了解一下基础配置，所以以后会穿插进行 Tiptap 基础知识文章的撰写。

一、Settings

editor#settings
editor 是 Tiptap 的核心对象，创建一个编辑器使用 new Editor() 方法，今天来学习一下创建编辑器的时候都有哪些配置信息可以传递给 Tiptap。

1、element

HTMLElement
编辑器的宿主元素，在宿主元素不可用之前启用编辑器也是可以的，会自动延后挂载行为，执行下面的方法进行挂载：

yourContainerElement.append(editor.options.element)

2、extensions

Array
添加到编辑器中的扩展，可以是 tiptap 提供的，也可以是在原有的扩展上进行 extend 的，也可以是通过 Extension.create() 方法新创建的扩展。例如 Heading、Paragraph 等等

3、content

String
编辑器初始的内容，字符串中可以包含标签，会自动被解析，渲染成DOM元素

4、editable

Boolean
是否可编辑

5、autofocus

初始状态下焦点的位置，可选值如下
start：文档开头
end：文档结尾
all：选中整个文档
Number：文档中的哪个位置
true：允许自动聚焦
false：不允许自动聚焦
null：不允许自动聚焦

6、enableInputRules

false 或者 Array
false 表示不开启自动转换的规则
允许的输入规则，默认情况下，编辑器允许所有的输入规则，一般情况下不需要指定，全部允许就行了。
用于 Markdown 快捷输入，比如 ‘#’ 表示标题一，可以自定义快捷输入。这个快捷输入是添加到扩展上的，以下面的方式进行添加：

// Use the ~single tilde~ markdown shortcut
import Strike from '@tiptap/extension-strike'
import { markInputRule } from '@tiptap/core'
const inputRegex = /(?:^|\s)((?:~)((?:[^~]+))(?:~))$/

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

如果要允许这条输入规则，就需要在 enableInputRules 中写上这个扩展项

enableInputRules: [CustomStrike],

7、enablePasteRules

false 或者 Array
默认情况下，编辑器允许所有的粘贴规则
粘贴规则的作用和输入规则是一样的，就是快捷输入符号的粘贴。

8、injectCSS

默认情况下编辑器有一系列的样式style，这个属性设置成 false 的话可以禁用原有的样式。应该也不咋会用到。

9、injectNonce

String
给动态创建的元素提供一个随机字符串，以使用Content-Security-Policy，防止爬虫或网站攻击等。

10、editorProps

Object
这个配置项会被prosemirror 进行处理，如果你想重写某些编辑器的属性或者方法，就可以传递这个属性，例如可以给编辑器设置生命周期的监听函数

new Editor({
  // Learn more: https://prosemirror.net/docs/ref/#view.EditorProps
  editorProps: {
    transformPastedText(text) {
      return text.toUpperCase()
    },
  },
})

粘贴字母进去会直接变成大写୧(๑•̀◡•́๑)૭

11、parseOptions

Object
这个也是要传递给prosemirror#ParseOptions解析的属性。是用来控制粘贴行为的。
一般也不会用到，感兴趣的童鞋可以上官网瞅瞅

二、Methods

编辑器提供了一系列的公共方法，方法是普通的函数，可以返回任何类型的数据。需要注意方法和命令是不一样的，命令主要用来修改编辑器的state属性，包括选区、内容等方面，只能返回布尔值。

1、can()

检查一个命令或者命令链能否被调用，不会实际执行命令。如果可以执行，则会返回 true，链式会继续往下执行

2、chain()

创建一个命令链以便于一次性调用多个命令。

// Execute two commands at once
editor.chain().focus().toggleBold().run()

3、destroy()

销毁编辑器实例、解绑所有方法。

4、getHTML()

以HTML形式获取当前的编辑器文档内容

5、getJSON()

以JSON形式获取当前的编辑器文档内容

6、getText()

以纯文本形式获取当前的编辑器文档内容
可以传递一个配置对象参数，指定分割节点的字符

// 纯文本
editor.getText()
// 节点之间通过两个空行分割
editor.getText({ blockSeparator: '\n\n' })

7、getAttributes()

获取当前选定节点或标记(mark)的属性。
接受一个字符串参数，指明节点或者标记的名称

editor.getAttributes('link').href

8、isActive()

参数一：String 节点名或者标记名
参数二：Object 要判断的属性
对当前选中的节点或者标记进行条件判断，返回布尔值，表示是否满足传递进去的条件

// 判断当前选中节点是否是标题
editor.isActive('heading')
// 判断当前选中节点是否是二级标题
editor.isActive('heading', { level: 2 })
// 判断当前选中的节点或者标记是否具有指定的属性
editor.isActive({ textAlign: 'justify' })

9、registerPlugin()

参数一：Plugin 要注册的插件
参数二：handlePlugins (newPlugin: Plugin, plugins: Plugin[]) => Plugin[] 控制如何将要注册的插件合并到现有的插件列表
注册 ProseMirror 插件

10、setOptions()

参数：Object
更新编辑器选项

// 给当前的编辑器实例增加一个类名
editor.setOptions({
  editorProps: {
    attributes: {
      class: 'my-custom-class',
    },
  },
})

11、setEditable()

参数一：Boolean 要将编辑器设置成可编辑的还是不可编辑的
参数二：Boolean 是否触发更新的监听器，默认为 false

12、unregisterPlugin()

参数：string | PluginKey
注销插件

13、$node()

参数一：String 表示节点类型，例如codeBlock、bulletList
参数二：Object 表示节点属性
获取文档中拥有指定属性的第一个某类型的节点

三、Properties

1、isEditable

是否可编辑

2、isEmpty

是否有内容

3、isFocused

是否被聚焦

4、isDestroyed

是否被销毁

5、isCapturingTransaction

编辑器是否正在捕获事务。
对于捕获事务的理解，事务就是编辑器中的各种操作，例如修改某个文字的颜色，修改某个区域的内容等，事务可以被捕获，然后集中起来一并执行，isCapturingTransaction 就可以判断编辑器是否正在捕获事务，如果没有在捕获事务，就需要手动对当前的操作执行捕获操作，如果正在捕获，那么就等编辑器自己捕获即可。