[分享]CKEditor 5 如何自定义菜单栏图标？

CKEditor 5 菜单栏自定义图标：突破藩篱，打造个性化编辑器在使用 CKEditor 5 这款强大的富文本编辑器时，你是否也曾为菜单栏无法直接添加自定义图标而苦恼？官方文档对此语焉不详，简单的 ...

CKEditor 5 菜单栏自定义图标：突破藩篱，打造个性化编辑器

在使用 CKEditor 5 这款强大的富文本编辑器时，你是否也曾为菜单栏无法直接添加自定义图标而苦恼？官方文档对此语焉不详，简单的 icon 属性设置似乎毫无作用，自定义注入 SVG 的尝试也以失败告终。

事实上，CKEditor 5 默认配置确实存在局限性，菜单栏项仅支持文本显示，并未提供直接设置图标的选项。但是，这并不意味着我们束手无策。借助 CKEditor 5 灵活的插件机制，我们可以突破这一藩篱，实现自定义图标功能，打造真正个性化的编辑器界面。

插件扩展：为 CKEditor 5 注入自定义图标的强大武器

CKEditor 5 的插件系统赋予了开发者极大的自由度，允许我们扩展其核心功能，满足各种定制化需求。因此，要实现菜单栏自定义图标功能，我们需要创建自定义插件。

1. 创建自定义插件：扩展菜单栏功能

首先，我们需要创建一个 JavaScript 文件，编写自定义插件代码。该插件主要完成以下任务：

• 扩展 menuItem schema： 默认情况下，menuItem schema 不包含 icon 属性，我们需要对其进行扩展，允许设置自定义图标。

• 监听菜单初始化事件： 为了在菜单加载完成后添加图标，我们需要监听编辑器 UI 初始化完成事件。

• 遍历菜单项并添加图标： 当菜单初始化完成后，我们需要遍历所有菜单项，找到设置了 icon 属性的项，并将对应的图标添加到菜单项的 HTML 中。

以下是一个简单的自定义插件示例代码：

class MenuIcon extends Plugin {
  init() {
    const editor = this.editor;
    const schema = editor.model.schema;

    // 扩展 menuItem schema，允许设置 icon 属性
    schema.extend('menuItem', {
      allowAttributes: ['icon']
    });

    // 监听编辑器 UI 初始化完成事件
    this.listenTo(editor.ui, 'ready', () => {
      this.addIconsToMenu();
    });
  }

  addIconsToMenu() {
    const editor = this.editor;
    const menuItems = editor.ui.componentFactory.names();

    // 遍历所有菜单项
    for (const itemName of menuItems) {
      const menuItem = editor.ui.componentFactory.create(itemName);

      // 判断菜单项是否设置了 icon 属性
      if (menuItem.hasOwnProperty('icon') && menuItem.icon) {
        // 获取图标路径或 SVG 代码
        const icon = menuItem.icon;

        // 将图标添加到菜单项
        menuItem.element.innerHTML = `<span class="custom-icon">${icon}</span>${menuItem.labelView.element.outerHTML}`;
      }
    }
  }
}

2. 注册并配置插件：将自定义插件集成到 CKEditor 5

创建好插件代码后，我们需要在 CKEditor 5 初始化时注册并配置该插件。

在 CKEditor 5 初始化代码中，我们需要进行以下修改：

• 引入自定义插件文件： 使用 <script> 标签引入我们创建的自定义插件 JavaScript 文件。

• 将插件添加到 plugins 数组： 在 CKEditor 5 配置对象中，将自定义插件类添加到 plugins 数组中。

• 在菜单配置中设置 icon 属性： 在 toolbar 或 menu 配置项中，为需要添加图标的菜单项设置 icon 属性，该属性值可以是图标路径或 SVG 代码。

以下是一个简单的 CKEditor 5 初始化代码示例：

ClassicEditor
  .create( document.querySelector( '#editor' ), {
    // ...其他配置项...

    // 引入自定义插件
    plugins: [ MenuIcon, ... ], 

    // 工具栏配置
    toolbar: {
      items: [ 'custom' ]
    },

    // 菜单配置
    menu: {
      custom: {
        icon: '<svg>...</svg>', // 使用 SVG 代码
        title: 'Custom',
        items: "..."
      }
    }
  } )
  .then( ... )
  .catch( ... );

3. 添加样式：确保图标正确显示

为了确保图标在菜单栏中正确显示，我们需要添加一些 CSS 样式，用于控制图标的大小、位置和颜色。

以下是一个简单的 CSS 样式示例：

.ck-editor__main .ck-menubar .custom-icon {
  display: inline-block;
  width: 16px;
  height: 16px;
  margin-right: 5px;
}

.ck-editor__main .ck-menubar .custom-icon svg {
  width: 100%;
  height: 100%;
  fill: currentColor;
}

最佳实践：让代码更优雅、更易维护

上述解决方案已经可以实现自定义图标功能，但为了提高代码可维护性和可读性，我们可以进行一些优化：

• 将图标 SVG 代码存储在单独的文件中： 将 SVG 代码存储在独立的 .svg 文件中，并使用 JavaScript 动态加载，可以提高代码可读性，方便维护和更新图标。

• 将插件代码封装成一个独立的模块： 将自定义插件代码封装成一个独立的 JavaScript 模块，使用模块化的方式组织代码，可以提高代码复用性，方便在其他项目中使用。

• 提供更丰富的配置选项： 可以为自定义插件提供更丰富的配置选项，例如图标大小、颜色、自定义 CSS 类名等，以满足更多个性化需求。

总结：个性化定制，释放 CKEditor 5 的无限潜能

通过自定义插件，我们成功突破了 CKEditor 5 默认配置的局限，实现了在菜单栏中添加自定义图标的功能。这种方法灵活、可控，能够满足各种定制化需求，帮助你打造独一无二的编辑器界面。

常见问题解答

1. 为什么我的图标没有显示出来？

   • 确保已正确引入自定义插件 JavaScript 文件和 CSS 样式文件。

   • 检查 icon 属性设置是否正确，路径或 SVG 代码是否有效。

   • 检查浏览器开发者工具，查看是否存在错误信息。

2. 如何修改图标的大小和颜色？

   • 可以通过 CSS 样式来修改图标的大小和颜色，例如使用 width、height 和 fill 属性。

3. 如何使用自定义的 CSS 类名？

   • 可以在自定义插件中添加配置选项，允许用户设置自定义 CSS 类名，然后在 CSS 文件中定义该类名的样式。

4. 如何动态加载 SVG 图标？

   • 可以使用 JavaScript 的 fetch API 或 XMLHttpRequest 对象动态加载 SVG 文件，然后将 SVG 代码插入到 icon 属性中。

5. 还有其他方法可以实现自定义图标吗？

   • 可以考虑使用 CKEditor 5 的其他 API，例如 editor.ui.view.toolbar 和 editor.ui.view.menubar 来操作菜单栏，但这种方法相对复杂，需要对 CKEditor 5 的内部结构有更深入的了解。

希望本文能够帮助你解决 CKEditor 5 菜单栏自定义图标问题，并为你提供一些有用的技巧和建议。