如标题所见,这一篇我们讲配置,也是官方guide的第一节内容。我会按照文档的guide顺序,根据我自己的理解方式,一点点解读其内容,所以如果你不着急,我建议你看第一手资料;如果你的时间比较紧迫,需要快速上手,可以来看我的这篇专栏。
在上一篇介绍中,我们可以看到,目前的编辑器非常简陋,我们如何给它添加一些功能呢?
假设我们要增加一个可以让输入框中的文字变成标题(heading)的功能。那么,首先,我们要通过npm添加一个新的功能包@tiptap/extension-heading,并在Tiptap.vue中导入该包;在构造editor的过程中,给它传入一个配置对象,代码如下:
import Heading from '@tiptap/extension-heading';
//...
mounted() {
this.editor = new Editor({
content: '<p>I’m running Tiptap with Vue.js. </p>',
extensions: [
Heading
],
})
}
//...
为什么我把StarterKit这个工具包给去掉了呢,因为实际上,StarterKit这个包包含了大部分常用的工具如heading,paragraph,text等,当我们在extensions配置项中同时引入StarterKit和Heading时,vue会报一个重复扩展的警告,不信的同学可以试试。
如果这个时候你启动了项目,你会发现,界面上没有出现新东西,是不是扩展没有生效呢?实际上,如果控制台没报错的话,tiptap已经加入这个扩展了,之所以看不到是因为,你没有触发更改标题格式的事件,怎么触发呢?连个按钮都没有。不要着急,随着之后的深入学习,你会知道如何通过按钮去触发。现在我们先安心把配置相关的了解下。
扩展也是可以被配置的,可以通过.configure()方法并传入一个配置项进行设置。如上述的Heading,我们将其改为如下形式,就可以禁用掉默认的4,5,6大小的标题,只用1,2,3大小。
Heading.configure({
levels: [1, 2, 3],
}),
刚才说过,StarterKit包包含了大部分常用的工具,所以可以只引入StarterKit扩展,并对单个功能进行设置
import StarterKit from '@tiptap/starter-kit'
new Editor({
extensions: StarterKit.configure({
heading: {
levels: [1, 2, 3],
},
}),
})
当你不想指定StarterKit中的某个功能时(也就是说,你想让StarterKit包中所有的扩展按默认模式载入到Tiptap中),可以如下设置:
import StarterKit from '@tiptap/starter-kit'
new Editor({
extensions: [
StarterKit.configure({
history: false,
}),
],
})
另外,这一节提到了几个概念,分别是node,mark和extension。在后文中,会经常提及这些概念,所以我认为有必要在这里做一些简单的解释。
node:如果你把文档看做是一颗树,那么你可以认为node就是这棵树中的一种内容类型。比如标题(heading),段落(paragraph),文本(text),代码块(code block)等等。
mark:可以将一种或多种mark添加到指定的node上。比如往一段文字(node)上添加加粗效果(mark)。
extension:extension赋予tiptap一些能力,比如heading,color等等。它们不能添加到模式中,但可以添加功能或更改编辑器的行为。
这是guide第二节内容,这里我们就能学会如何通过按钮来使用扩展了。tiptap提供了一系列API来触发命令和激活状态。下面,我们将在Tiptap.vue中添加一个button,并通过触发命令来使得加粗生效。
<template>
<div>
<button @click="editor.chain().focus().toggleBold().run()">加粗</button>
<editor-content :editor="editor" />
</div>
</template>
在构造editor时,我们让starterkit内部所有扩展生效,即
this.editor = new Editor({
content: '<p>I’m running Tiptap with Vue.js. </p>',
extensions: [
StarterKit.configure({
history:false
})
],
})
不出意外,可以看到在选中一段文本后单击加粗按钮,选中的文本就会被加粗。click事件触发的那段代码是什么意思呢?官方是这样解释的:
既然我们已经知道了如何用按钮控制文本的加粗,那么,在配置那一节中的内容,就知道解决的思路了。我通过查询了Heading扩展的API,只需要将链式调用改为:
editor.chain().focus().toggleHeading({level:1}).run(); 即可
从目前来看,使用tiptap并不是一件方便的事情,你需要自己去写相应的按钮,并给其绑定回调函数。怎么说呢,tiptap更像是一把双刃剑把,它能高度自定义化,但同样需要开发者花费时间精力去搞明白如何去自定义。