CKEditor 5 摸爬滚打（四）—— 开发带有弹窗表单的超链接插件

前面的几篇文章已经介绍了 CKEditor5 插件的构成，并开发了一个加粗插件

这篇文章会用一个超链接插件的例子，来介绍怎么在 CKEditor5 中开发带有弹窗表单的插件

 

 

一、设计转换器 Conversion

开发 CKEditor5 的插件有两个必须步骤：

1. 设计好 View、Model 以及转换规则 conversion;

2. 创建只含基本逻辑的 command.js 和 toolbar-ui.js

而对于超链接插件，View 肯定是一个 <a> 标签：

<!-- View -->
<a herf="${url}" target="_blank">${链接名称}</a>

和加粗插件类似，<a> 标签中的文本可以编辑，所以对应的 Model 也应该继承自 $text，然后通过自定义属性进行转换

<!-- Model -->
<paragraph>
  <$text linkHref="url">超链接</$text>
</paragraph>

所以 Schema 的注册可以这么来：

_defineSchema() {
  const schema = this.editor.model.schema;
  // SCHEMA_NAME__LINK -> 'linkHref'
  schema.extend("$text", {
    allowAttributes: SCHEMA_NAME__LINK
  });
}

然后完善一下 conversion，editing.js 就完成了:

// editing.js

import Plugin from "@ckeditor/ckeditor5-core/src/plugin";
import inlineHighlight from '@ckeditor/ckeditor5-typing/src/utils/inlinehighlight';
import LinkCommand from "./command";
import {
  SCHEMA_NAME__LINK,
  COMMAND_NAME__LINK,
} from "./constant";

const HIGHLIGHT_CLASS = 'ck-link_selected';

export default class LinkEditing extends Plugin {
  static get pluginName() {
    return "LinkEditing";
  }

  init() {
    const editor = this.editor;

    this._defineSchema();
    this._defineConverters();

    // COMMAND_NAME__LINK -> 'link'
    editor.commands.add(COMMAND_NAME__LINK, new LinkCommand(editor));

    // 当光标位于 link 中间，追加 class，用于高亮当前超链接
    inlineHighlight(editor, SCHEMA_NAME__LINK, "a", HIGHLIGHT_CLASS);
  }

  _defineSchema() {
    const schema = this.editor.model.schema;
    schema.extend("$text", {
      // SCHEMA_NAME__LINK -> 'linkHref'
      allowAttributes: SCHEMA_NAME__LINK,
    });
  }

  _defineConverters() {
    const conversion = this.editor.conversion;

    conversion.for("downcast").attributeToElement({
      model: SCHEMA_NAME__LINK,
      // attributeToElement 方法中，如果 view 是一个函数，其第一个参数是对应的属性值，在这里就是超链接的 url
      // 实际项目中需要校验 url 的真实性，这里就省略掉了
      view: createLinkElement,
    });

    conversion.for("upcast").elementToAttribute({
      view: {
        name: "a",
        attributes: {
          href: true,
        },
      },
      model: {
        key: SCHEMA_NAME__LINK,
        value: (viewElement) => viewElement.getAttribute("href"),
      },
    });
  }
}

function createLinkElement(href, { writer }) {
  return writer.createAttributeElement("a", { href });
}

 

二、基础的 Command 和 ToolbarUI

先来完成简单的 command.js

// command.js 基础版

import Command from "@ckeditor/ckeditor5-core/src/command";
import { SCHEMA_NAME__LINK } from "./constant";

export default class LinkCommand extends Command {
  refresh() {
    const model = this.editor.model;
    const doc = model.document;

    // 将链接关联到到 value
    this.value = doc.selection.getAttribute(SCHEMA_NAME__LINK);
    // 根据 editing.js 中定义的 schema 规则来维护按钮的禁用/启用状态
    this.isEnabled = model.schema.checkAttributeInSelection(doc.selection, SCHEMA_NAME__LINK);
  }

  execute(href) {
    console.log('LinkCommand Executed', href);
  }
}

整个超链接插件的交互过程是：选中文本 -> 点击工具栏按钮 -> 打开弹窗 -> 输入连接 -> 点击确定

所以工具栏按钮的点击事件，并没有直接触发 command，而是打开弹窗。最终是弹窗的确定按钮触发 command

基于这个逻辑，可以完成基础的 toolbar-ui.js

// toolbar-ui.js

import Plugin from "@ckeditor/ckeditor5-core/src/plugin";
import ButtonView from "@ckeditor/ckeditor5-ui/src/button/buttonview";
import linkIcon from "@ckeditor/ckeditor5-link/theme/icons/link.svg";
import {
  COMMAND_NAME__LINK,
  TOOLBAR_NAME__LINK,
  TOOLBAR_LABEL__LINK,
} from "./constant";

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

  _createToolbarButton() {
    const editor = this.editor;
    // COMMAND_NAME__LINK -> 'link'
    const linkCommand = editor.commands.get(COMMAND_NAME__LINK);

    // TOOLBAR_NAME__LINK -> 'ck-link'
    editor.ui.componentFactory.add(TOOLBAR_NAME__LINK, (locale) => {
      const view = new ButtonView(locale);
      view.set({
        // TOOLBAR_LABEL__LINK -> '超链接'
        label: TOOLBAR_LABEL__LINK,
        tooltip: true,
        icon: linkIcon,
        class: "toolbar_button_link",
      });

      view.bind("isEnabled").to(linkCommand, "isEnabled");
      // 根据 command 的 value 来控制按钮的高亮状态
      view.bind("isOn").to(linkCommand, "value", (value) => !!value);

      this.listenTo(view, "execute", () => {
        // 点击按钮的时候打开弹窗
        this._openDialog(linkCommand.value);
      });
      return view;
    });
  }

  // value 为已设置的超链接，作为初始值传给弹窗表单
  _openDialog(value) {
    // 在弹窗中触发命令
    this.editor.execute(COMMAND_NAME__LINK);
  }
}

准备就绪，接下来就是重头戏：开发弹窗表单组件

 

 

三、开发弹窗组件

CKEditor 提供了一套定义视图的规则 TemplateDefinition，可以从 View 继承然后按照相应的格式开发视图

这种方式就像是手动定义一个 DOM 树结构，类似于 Vue 的 render 方法，或者使用 js 而不是 jsx 的 React 视图模板

在熟悉了规则之后还是能很顺手的完成视图开发，但很难算得上高效

直到我忽然意识到：弹窗视图是在编辑器视图之外的，也就是说弹窗不需要转成 Model。

既然如此，那可不可以使用原生 JS 开发的插件呢？答案是可以的

 

所以我最终使用 JS 开发了一个弹窗组件 /packages/UI/dialog/dialog.js，这里就不细讲了，贴一下代码：

// dialog.js

import { domParser } from "../util";
import "./dialog.less";

// 用于批量绑定/解绑事件
const EventMaps = {
  'closeButton': {
    selector: '.dialog-button_close',
    handleName: 'close',
  },
  'cancelButton': {
    selector: '.dialog-button_cancel',
    handleName: 'close',
  },
  'submitButton': {
    selector: '.dialog-button_submit',
    handleName: '_handleSubmit',
  },
  'mask': {
    selector: '.dialog-mask',
    handleName: 'close',
    verifier: 'maskEvent'
  }
}

export default class Dialog {
  constructor(props) {
    Object.assign(
      this,
      {
        container: "body", // querySelector 可接收的参数
        content: {}, // 内容对象 { title, body, classes }
        afterClose: () => {},
        beforeClose: () => {},
        onSubmit: () => {},
        maskEvent: true,  // 是否允许在点击遮罩时关闭弹窗
         '60%', // 弹窗宽度，需携带单位
      },
      props || {}
    );

    this.$container = document.querySelector(this.container);
    this.render();
  }

  render() {
    let config = {};
    if (typeof this.content === 'object') {
      config = this.content;
    } else {
      config.body = this.content;
    }

    this.$pop = domParser(template({
      ...config,
       this.width
    }));
    this.$container.appendChild(this.$pop);
    this._bind();
  }

  close() {
    typeof this.beforeClose === "function" && this.beforeClose();
    this.$pop.style.display = "none";
    this.destroy();
    typeof this.afterClose === "function" && this.afterClose();
  }

  destroy() {
    this._unbind();
    this.$pop && this.$pop.remove();
  }

  _bind() {
    for (const key in EventMaps) {
      const item = EventMaps[key];
      // 当存在检验器，且校验器为 falsy 时，不监听事件
      if (item.verifier && !this[item.verifier]) {
        continue;
      }
      this[key] = this.$pop.querySelector(item.selector);
      this[key].addEventListener("click", this[item.handleName].bind(this));
    }
  }

  _unbind() {
    for (const key in EventMaps) {
      const item = EventMaps[key];
      try {
        this[key] && this[key].removeEventListener("click", this[item.handleName].bind(this));
      } catch(err) {
        console.error('Dialog Unbind Error: ', err);
      }
    }
  }

  _handleSubmit() {
    typeof this.onSubmit === "function" && this.onSubmit();
    this.close();
  }
}

function template(config) {
  const { classes, title, body, width } = config || {};
  const cls =
    typeof classes === "string"
      ? classes
      : Array.isArray(classes)
      ? classes.join(" ")
      : "";

  return `
    <div class="dialog">
      <div class="dialog-main ${cls}" style="${width || "60%"};">
        <div class="dialog-header">
          <span class="dialog-title">${title || ""}</span>
          <span class="dialog-header-action">
            <button class="dialog-button dialog-button_close button-icon">X</button>
          </span>
        </div>
        <div class="dialog-content">
          ${body || ""}
        </div>
        <div class="dialog-footer">
          <button class="dialog-button dialog-button_cancel">取消</button>
          <button class="dialog-button button-primary dialog-button_submit">确认</button>
        </div>
      </div>
      <div class="dialog-mask"></div>
    </div>
  `;
}

// util.js

export const domParser = (template) => {
  return new window.DOMParser().parseFromString(
    template,
    'text/html'
  ).body.firstChild
}

// dialog.less

.dialog{
  position: fixed;
  left: 0;
  top:0;
  right:0;
  bottom:0;
  background: transparent;
  z-index: 1000;
  overflow: auto;

  &-mask {
    position: absolute;
    left: 0;
    top:0;
    right:0;
    bottom:0;
    background: rgba(0,0,0,0.4);
  }

  &-main {
    background: white;
    position: absolute;
    left: 50%;
    top: 20%;
    box-shadow: 0 2px 8px 0 rgba(0, 0, 0, 0.14);
    transform: translateX(-50%);
    animation-duration: .3s;
    animation-fill-mode: both;
    animation-name: popBoxZoomIn;
    z-index: 1;
  }

  &-header {
    padding: 16px 20px 8px;

    &-action {
      .dialog-button_close {
        background: transparent;
        border: none;
        outline: none;
        padding: 0;
        color: #909399;
        float: right;
        font-size: 16px;
        line-height: 24px;
        &:hover {
          background-color: transparent;
        }
      }
    }
  }

  &-content{
    position: relative;
    padding: 20px;
    color: #606266;
    font-size: 14px;
    word-break: break-all;
  }

  &-footer {
    padding: 10px 20px 16px;
    text-align: right;
    box-sizing: border-box;
  }

  &-button {
    display: inline-block;
    line-height: 1;
    white-space: nowrap;
    cursor: pointer;
    background: #fff;
    border: 1px solid #dcdfe6;
    color: #606266;
    text-align: center;
    box-sizing: border-box;
    outline: none;
    margin: 0;
    transition: .1s;
    font-weight: 500;
    padding: 10px 16px;
    font-size: 14px;
    border-radius: 4px;

    &:hover {
      background-color: #efefef;
    }

    & + .dialog-button {
      margin-left: 10px;
    }

    &.button-primary {
      color: #fff;
      background-color: #3c9ef3;
      border-color: #3c9ef3;

      &:hover {
        border-color: rgba(#3c9ef3, .7);
        background-color: rgba(#3c9ef3, .7);
      }
    }
  }
}


@keyframes popBoxZoomIn {
  from {
    opacity: 0;
    transform: scale3d(.7, .7, .7);
  }

  50% {
    opacity: 1;
  }
}

这个 dialog.js 只是提供了弹窗，接下来还需要开发超链接的表单组件 /packages/plugin-link/form/link-form.js，嵌入到 dialog 中：

// link-form.js

import Dialog from "../../UI/dialog/dialog";
import "./link-form.less";

export default class LinkForm {
  constructor(props) {
    Object.assign(
      this,
      {
        value: undefined, // 初始值
        onSubmit: () => {},
      },
      props || {}
    );

    this.render();
  }

  render() {
    const content = template(this.value);
    this.$form = new Dialog({
      content,
       "420px",
      onSubmit: this._submit.bind(this),
    });

    const dialog = this.$form.$pop;
    this.$input = dialog.querySelector(`input[name=linkValue]`);
    this.$cleanButton = dialog.querySelector(".link-form-button");

    this._bind();
  }

  destroy() {
    this._unbind();
  }

  _bind() {
    this.$cleanButton.addEventListener("click", this._handleCleanup.bind(this));
  }

  _unbind() {
    try {
      this.$cleanButton.removeEventListener(
        "click",
        this._handleCleanup.bind(this)
      );
    } catch (e) {
      console.error("LinkForm Unbind Error: ", e);
    }
  }

  _submit() {
    if (typeof this.onSubmit !== "function") {
      return;
    }

    return this.onSubmit(this.$input.value);
  }

  _handleCleanup() {
    this.$input.value = "";
  }
}

function template(initialValue) {
  const body = `
    <div class="link-form">
      <input
        placeholder="插入链接为空时取消超链接"
        type="text"
        class="link-form-input"
        name="linkValue"
        value="${initialValue || ""}"
      />
      <span title="清空" class="link-form-button">X</span>
    </div>
  `;

  return {
    classes: "link-form-dialog",
    title: "插入超链接",
    body,
  };
}

// .link-form.less

.link-form {
  line-height: normal;
  display: inline-table;
  width: 100%;
  border-collapse: separate;
  border-spacing: 0;

  &-input {
    vertical-align: middle;
    display: table-cell;
    background-color: #fff;
    background-image: none;
    border-radius: 4px;
    border-top-right-radius: 0;
    border-bottom-right-radius: 0;
    border: 1px solid #dcdfe6;
    box-sizing: border-box;
    color: #606266;
    font-size: inherit;
    height: 40px;
    line-height: 40px;
    outline: none;
    padding: 0 15px;
    transition: border-color 0.2s cubic-bezier(0.645, 0.045, 0.355, 1);
    width: 100%;

    &:focus {
      outline: none;
      border-color: #409eff;
    }
  }

  &-button {
    background-color: #f5f7fa;
    color: #909399;
    vertical-align: middle;
    display: table-cell;
    position: relative;
    border: 1px solid #dcdfe6;
    border-radius: 4px;
    border-top-left-radius: 0;
    border-bottom-left-radius: 0;
    border-left: 0;
    padding: 0 20px;
    width: 1px;
    white-space: nowrap;
    cursor: pointer;

    &:hover {
      background-color: #e9ebef;
    }
  }

  ::-webkit-input-placeholder {
    color: #c4c6ca;
    font-weight: 300;
  }
}

然后只要在工具栏图标的点击事件中创建 LinkForm 实例就能打开弹窗

// toolbar-ui.js

import LinkForm from "./form/link-form";

export default class LinkToolbarUI extends Plugin {
  // ...
  _openDialog(value) {
    new LinkForm({
      value,
      onSubmit: (href) => {
        this.editor.execute(COMMAND_NAME__LINK, href);
      },
    });
  }
  // ...
}

 

 

四、插入超链接

万事俱备，就差完善 command.js 中的具体逻辑了

和之前的加粗插件类似，只需要向文本 $text 添加属性 linkHref 即可

但超链接有一个需要注意的问题在于：当光标位于超链接上，却并没有选中整个超链接，这种情况应该如何处理

CKEditor5 提供的工具函数 findAttributeRange 可以解决这个问题

这个函数可以根据给定的 position 和 attribute 来获取完整的 selection

所以最终的 command.js 是这样的：

// command.js

import Command from "@ckeditor/ckeditor5-core/src/command";
import findAttributeRange from "@ckeditor/ckeditor5-typing/src/utils/findattributerange";
import { SCHEMA_NAME__LINK } from "./constant";

export default class LinkCommand extends Command {
  refresh() {
    const model = this.editor.model;
    const doc = model.document;

    // 将链接关联到到 value
    this.value = doc.selection.getAttribute(SCHEMA_NAME__LINK);
    // 根据 editing.js 中定义的 schema 规则来维护按钮的禁用/启用状态
    this.isEnabled = model.schema.checkAttributeInSelection(
      doc.selection,
      SCHEMA_NAME__LINK
    );
  }

  execute(href) {
    const model = this.editor.model;
    const selection = model.document.selection;

    model.change((writer) => {
      // 选区的锚点和焦点是否位于同一位置
      if (selection.isCollapsed) {
        const position = selection.getFirstPosition();

        // 光标位于 link 中间
        if (selection.hasAttribute(SCHEMA_NAME__LINK)) {
          const range = findAttributeRange(
            position,
            SCHEMA_NAME__LINK,
            selection.getAttribute(SCHEMA_NAME__LINK),
            model
          );
          this._handleLink(writer, href, range)
        }
      } else {
        const ranges = model.schema.getValidRanges(
          selection.getRanges(),
          SCHEMA_NAME__LINK
        );
        for (const range of ranges) {
          this._handleLink(writer, href, range)
        }
      }
    });
  }

  _handleLink(writer, href, range) {
    if (href) {
      writer.setAttribute(SCHEMA_NAME__LINK, href, range);
    } else {
      writer.removeAttribute(SCHEMA_NAME__LINK, range);
    }
  }
}

最后来完成入口文件 main.js，超链接插件就完成了

// main.js

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

export default class Link extends Plugin {
  static get requires() {
    return [ Editing, ToolbarUI ];
  }
  static get pluginName() {
   return TOOLBAR_NAME__LINK;
  }
}

超链接插件这个例子，主要是介绍 CKEditor 5 中高效开发弹窗表单的一个思路

像弹窗这种独立于 Model 之外的组件，可以直接使用原生 JS 进行开发

掌握这个窍门之后，开发 CKEditor 5 的插件会便捷许多

下一篇博客将用一个图片插件来介绍 CKEditor 5 中如何插入块级元素，以及块级元素的工具栏，to be continue...