CKEditor 5 摸爬滚打（二）—— 自定义一个简单的加粗插件（上）

基于编辑器做二次开发，可能大部分的工作量都在于自定义插件

而 CKEditor 5 实现了一套自己的 MVC 架构，导致开发自定义插件尤为复杂

 

一、插件的基本架构

CKEditor 5 的自定义插件都需要从 Plugin 类继承，在此基础上根据实际情况开发三个模块：

1. editing: 插件的核心代码，注册插件对应的 Model，以及插件相关的命令、视图转换等；

2. ui: 常用的是 ButtonView，用来注册工具栏上的图标按钮；其他需要自定义的视图需要自行编写模板 Template；

3. command: 自定义指令 Command，一般用于工具栏，用来控制工具栏按钮的状态和行为；也可以注册一般命令，只在代码中触发，而不暴露给用户；

 

这里提到了 Model 这个概念，它是 CKEditor 5 在编辑器中的数据模型

也就是说，我们在 CKEditor 5 中编辑内容的时候，并不是像常规编辑器那样直接编辑 DOM，而是编辑 Model

Model 其实就像是 Vue 或者 React 中的模板，每个插件需要创建自己的 schema（类似于组件），组装成类似这样的 Model

<$root>
  <paragraph>
    <$text>this is text content</$text>
  </paragraph>
  <paragraph>
    <plugin-image src="foo" title="bar"></plugin-image>
  </paragraph>
</$root>

然后通过转换器 conversion，在输出的时候将 Model 转换为富文本：

<p>this is text content</p>
<p>
  <div class="plugin-image">
    <img src="foo">
    <p class="title">bar</p>
  </div>
</p>

这里 plugin-image 的转换结果是瞎写的，在开发的时候需要自行定义转换规则

需要注意的是，由于 Model 和 conversion 的存在，一切直接操作 DOM 的开发手段都会失效

 

一下子接收到这些概念可能有点懵，不要慌，接下来用一个加粗插件的简单例子来深入了解

 

二、添加工具栏图标

在项目的 packages 目录下创建插件目录 plugin-bold，然后创建以下文件：

---

首先是 command.js：

// command.js

import Command from "@ckeditor/ckeditor5-core/src/command";

export default class BoldCommand extends Command {
  refresh() {
    this.isEnabled = true;
  }

  execute() {
    console.log("Execute Plugin-Bold");
  }
}

这里的 BoldCommand 对象继承自 CKEditor5-Core 的 Command 类，这个类提供了三个静态属性：

1. editor: 编辑器实例；

2. value: 命令的值，有需要时可以手动修改；

3. isEnabled: 是否启用，命令被禁用时无法触发，一般会关联工具栏中的启用状态。

另外还有两个钩子函数 refresh() 和 execute()

refresh 会在编辑器更新的时候执行，类似于 React 中的 render 函数

execute 是该命令的执行函数，会在命令被触发时执行

目前只是简单的创建了 BoldCommand 这个子类，具体的逻辑后面再来开发 

---

然后编辑 editing.js

// editing.js

import Plugin from "@ckeditor/ckeditor5-core/src/plugin";
import BoldCommand from "./command";
import { COMMAND_NAME__BOLD } from "./constant";

export default class BoldEditing extends Plugin {
  static get pluginName() {
    return "BoldEditing";
  }
  init() {
    const editor = this.editor;
    // 注册一个 BoldCommand 命令
    editor.commands.add(COMMAND_NAME__BOLD, new BoldCommand(editor));
  }
}

eidting.js 继承自 Plugin 类，加载的时候会自动执行 init() 方法

完整的 editing.js 会包含很多内容，这里先只是注册一个 BoldCommand 命令，其他的逻辑后面补充

在通过 editor.commands.add() 方法注册命令的时候，第一个参数是命令名称，类型为字符串，我放在 constant.js 中单独维护

// constant.js
export const COMMAND_NAME__BOLD = 'ck-bold';
export const COMMAND_LABEL__BOLD = '加粗';

---

接下来就是加粗插件在工具栏上的按钮 toolbar-ui.js

// toolbar-ui.js

import Plugin from "@ckeditor/ckeditor5-core/src/plugin";
import ButtonView from "@ckeditor/ckeditor5-ui/src/button/buttonview";
import boldIcon from "@ckeditor/ckeditor5-basic-styles/theme/icons/bold.svg";
import { COMMAND_NAME__BOLD, COMMAND_LABEL__BOLD } from "./constant";

export default class BoldToolbarUI extends Plugin {
  init() {
    this._createToolbarButton();
  }

  _createToolbarButton() {
    const editor = this.editor;
    const command = editor.commands.get(COMMAND_NAME__BOLD);
    editor.ui.componentFactory.add(COMMAND_NAME__BOLD, (locale) => {
      const view = new ButtonView(locale);
      view.set({
        label: COMMAND_LABEL__BOLD,
        tooltip: true,
        icon: boldIcon,
        // withText: true, // 在按钮上展示 label
        class: "toolbar_button_bold",
      });
      // 将按钮的状态关联到命令对应值上
      view.bind("isOn", "isEnabled").to(command, "value", "isEnabled");
      // 点击按钮时触发相应命令
      this.listenTo(view, "execute", () => editor.execute(COMMAND_NAME__BOLD));
      return view;
    });
  }
}

这里主要是引入了 ButtonView，并基于此创建了一个按钮实例 view（属性的注释可以参考第一小节的思维导图）

然后通过 bind() 方法将按钮 view 的 isOn 状态关联到 command 命令的值 value，将 isEnabled 状态关联到命令的 isEnabled

最终通过 editor.ui.componentFactory.add() 方法创建了一个 UI 组件，该方法的第一个参数是组件名称

因为没必要创建多余变量，我直接用了命令名称 COMMAND_NAME__BOLD（也可以用别的名称，但也需要单独维护，因为后面还会用到）

创建 UI 组件之后，就可以在创建组件的时候，通过配置 toolbar 属性（在数组中添加刚才设置的组件名称）将对应的按钮展示到 toolbar 上

在 toolbar 上展示的按钮，可以通过按钮自身的 isOn 和 isEnabled 状态来高亮和禁用

另外，BoldToolbarUI 依然是继承自 Plugin 类 

 

三、在编辑器中引入插件

插件的三大模块已经搞定，接下来在 main.js 中引入

// plugin-bold/main.js

import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
import ToolbarUI from './toolbar-ui';
import BoldEditing from './editing';
import { COMMAND_NAME__BOLD } from './constant';

export default class Bold extends Plugin {
  static get requires() {
    return [ BoldEditing, ToolbarUI ];
  }
  static get pluginName() {
   return COMMAND_NAME__BOLD;
  }
}

main.js 中的 Bold 也是 Plugin 的子类，这里有一个静态方法 requires，这个方法返回一个由 Plugin 组成的数组，用于加载依赖插件

到此为止这个插件已经可以用了，在编辑器 packages/my-editor/src/index.js 中注释掉除了 Essentials 和 Paragraph 以外的插件

并调整 create 函数中的 plugins 和 toolbar 配置项，删除被注释掉的插件

然后引入自己开发的 plugin-bold 插件

import Bold from '../../plugin-bold/main';

后面还会引入更多的自定义插件，所以最好是添加路径别名，可以在根目录的 webpack.config.js 追加配置项：

resolve: {
  alias: {
    "@plugin": path.resolve("/packages"),
  },
}

打包配置文件 packages/my-editor/webpack.config.js 同样需要修改：

resolve: {
  alias: {
    "@plugin": path.resolve( __dirname, "../"),
  },
},

然后就能用别名引入插件了：

import Bold from "@plugin/plugin-bold/main";

如果使用 VSCode 无法识别路径，可以在项目的根目录添加一个 jsconfig.json

{
  "compilerOptions": {
    "baseUrl": "./",
    "paths": {
      "@plugin/*": ["packages/*"]
    }
  },
  "exclude": ["node_modules"]
}

回到编辑器文件 packages/my-editor/src/index.js，编辑 ClassicEditor.create() 方法的第二个参数中的 plugins 和 toolbar

plugins: [ Essentials, Paragraph, Bold ],
toolbar: [ "undo", "redo", "|", Bold.pluginName ],

这里 toolbar 中添加的是 toolbar-ui.js 文件中 editor.ui.componentFactory.add() 创建的 UI 组件名

插件已经引入了，运行 yarn run dev 启动项目，可以看到这样的编辑器：

点击工具栏上的加粗按钮，控制台会打印 "Execute Plugin-Bold"，这说明我们成功地迈出了自定义插件的第一步

接下来就是最为头疼的部分：model 与 conversion

to be continue...