富文本编辑器Tiptap系列教程——5分钟搭建基于Tiptap的富文本编辑器

固定菜单#

固定菜单就是我们常见的各种富文本编辑器的顶部或底部菜单。

例如，我们只引入 StarterKit ，然后用它提供的节点和扩展来做一个简单的 demo：

富文本编辑的菜单一般有这几种状态：点击事件、不可点击状态、激活状态，我们看一下bold的代码：

1
<button
2
  @click="editor.chain().focus().toggleBold().run()"
3
  :disabled="!editor.can().chain().focus().toggleBold().run()"
4
  :class="{ 'is-active': editor.isActive('bold') }"
5
>
6
  bold
7
</button>

Tiptap 中调用 API 可以像 Promise 一样链式调用，通过chain()就可以创建一条链，比如上面的示例，同时执行了focus()和toggleBold()方法，focus 可以让编辑器重新获取焦点，因为当单击内容之外的按钮时，编辑器会失焦，所以需要 focus 重新获取焦点，后面大多数命令都会添加 focus，toggleBold 将所选文本切换粗体/清除粗体标记，Tiptap 中大多数扩展都带有 set…()、unset…() 和 toggle…() 命令，很好理解。

注意：通过 chain 链式调用时需要添加 .run() 来实际执行所有命令。

那我们怎么管理当前菜单的激活状态呢 🤔️？

Tiptap 也提供了相应的 API isActive()检查是否已将某些标记应用于所选文本，返回 true 或 false，我们可以借助该功能来切换 CSS 类名。比如通过editor.isActive('bold')判断选择的内容是否含有 Bold 标记，如果所选文本跨越多个标记，或者只有部分选择有标记，isActive()将返回 false。

1
// 比较给定属性的示例
2
editor.isActive('highlight', { color: '#ffa8a8' })
3
// 支持正则表达式
4
editor.isActive('textStyle', { color: /.*/ })
5
// 比较标记的值
6
editor.isActive({ textAlign: 'right' })

气泡菜单#

气泡菜单就是出现在所选文本附近的菜单，可以快速对所选文本进行设置。Tiptap 提供了Bubble Menu扩展来实现此功能。

1. 安装

   1
   npm install @tiptap/extension-bubble-menu

2. 选项

   • element：菜单挂载点，HTML 节点
   • updateDelay：更新延迟，默认 250ms
   • tippyOptions：BubbleMenu 扩展基于 tippy.js，此参数将完全传递给它
   • pluginKey：扩展唯一标识，项目暂时未用到
   • shouldShow：自定义菜单是否显示

3. 使用

   1
   <template>
   2
     <bubble-menu
   3
       v-if="editor"
   4
       :editor="editor"
   5
       :tippy-options="{ duration: 100 }"
   6
     >
   7
       <button
   8
         @click="editor.chain().focus().toggleBold().run()"
   9
         :class="{ 'is-active': editor.isActive('bold') }"
   10
       >
   11
         bold
   12
       </button>
   13
       <button
   14
         @click="editor.chain().focus().toggleItalic().run()"
   15
         :class="{ 'is-active': editor.isActive('italic') }"
   16
       >
   17
         italic
   18
       </button>
   19
       <button
   20
         @click="editor.chain().focus().toggleStrike().run()"
   21
         :class="{ 'is-active': editor.isActive('strike') }"
   22
       >
   23
         strike
   24
       </button>
   25
     </bubble-menu>
   26
   </template>
   27
   
   28
   <script setup>
   29
   import { BubbleMenu, Editor } from '@tiptap/vue-3'
   30
   defineProps({
   31
     editor: {
   32
       type: Editor,
   33
       require: true,
   34
     },
   35
   })
   36
   </script>
   37
   
   38
   <style lang="scss" scoped></style>

   展开收起

   完了，当我们选择文本时就会出现气泡菜单

   

4. 自定义显示逻辑

   上面说到可以通过 shouldShow 控制自定义菜单是否显示，那么我们可以修改代码如下：

   1
   <template>
   2
     <bubble-menu
   3
       v-if="editor"
   4
       :editor="editor"
   5
       :tippy-options="{ duration: 100 }"
   6
       :should-show="shouldShow"
   7
     >
   8
       。。。
   9
     </bubble-menu>
   10
   </template>
   11
   
   12
   <script setup>
   13
   ...
   14
   const shouldShow = ({ editor, view, state, oldState, from, to }) => {
   15
     // 仅在无序列表选中的时候才显示气泡菜单
   16
     return editor.isActive("bulletList");
   17
   };
   18
   </script>

   展开收起

   这样只有当我们选中无序列表时才会显示气泡菜单。

浮动菜单#

浮动菜单就是出现在空行的菜单，可以快速设置当前行。Tiptap 提供了Floating Menu扩展来实现此功能。

安装

1
npm install @tiptap/extension-floating-menu

选项、展示逻辑都与气泡菜单相同，这里不再赘述。看下效果：

斜杠菜单#

斜杠菜单还是一个实验性的扩展，使用 / 开始一个新行，并会弹出一个窗口以选择应添加哪个节点。基于suggestion

保存输出结果#

一般会有两种保存：实时保存和手动保存。

• 文档发生改变时保存

  Tiptap 提供了onUpdate来监听编辑器内容变化，通过getJSON()和getHTML()即可拿到最新数据。

  1
  const editor = new Editor({
  2
    onUpdate({ editor }) {
  3
      const json = editor.getJSON()
  4
      const html = editor.getHTML()
  5
      console.log(json)
  6
      console.log(html)
  7
    },
  8
  })

• 手动保存

  通常是点击按钮时进行保存，此时通过初始化的editor实例，调用上述方法即可拿到数据。

回显#

回显时可以在编辑器初始化时设置content字段，或者调用setContent异步更新，JSON 格式或 HTML 格式都可以进行回填，并且官方提供了JSON 转 HTML 的 API。

而如果想将其他富文本编辑器内容转为 Tiptap 的内容，官方同样提供了一个 PHP 包来将 HTML 转换为兼容的 JSON 结构：ueberdosis/prosemirror-to-html。

1
// 编辑器初始化时设置
2
new Editor({
3
  content: `<p>示例文字</p>`,
4
})
5

6
// or 后期异步更新设置
7
editor.commands.setContent(json)

协同操作#

Tiptap 对 Y.js 提供一流的支持，添加实时协作、离线编辑或设备间同步等功能非常棒，当然此时就不能只是简单的 HTML 或 JSON 格式的存储了，以后再说，可以先看官方协同编辑文档。

Markdown#

Tiptap 基于一些原因， 目前不支持 Markdown 作为输入或输出格式，如：HTML 或 JSON 格式是嵌套结构，而 Markdown 是扁平的。如果想实现要 Markdown，可以参考前面提到的Nextcloud Text。

我们也可以在官方 demo中看到更多案例，有很多都是可以直接拿过来用的。