CKEditor 5：实现全页HTML编辑与标签保留指南

CKEditor 5中全页HTML编辑的挑战

在ckeditor 5中，默认情况下，编辑器被设计为处理html文档的片段，即通常是

这是一个测试段落。

在CKEditor 5中加载后，可能只剩下：

这是一个测试段落。

这种行为对于大多数内容管理场景是合理的，但在某些特定需求下，例如需要编辑整个HTML页面模板时，就成为了一个障碍。对于CKEditor 4的用户来说，这可能与之前的fullPage: true配置项有所不同，导致一些困惑。

立即学习“前端免费学习笔记（深入）”；

常见的尝试与误区

在尝试解决这个问题时，开发者可能会尝试以下几种方法，但它们通常无法直接解决根级标签的保留问题：

1. 使用 GeneralHtmlSupport 插件并配置为允许所有标签和属性： GeneralHtmlSupport 插件主要用于允许在编辑区域（通常是内部）使用自定义的HTML标签、属性和类，例如非标准的
   元素或自定义样式。它对之外的、等标签无效。
2. 替换 HtmlDataProcessor 为 XmlDataProcessor： 这种尝试可能导致更多问题，例如HTML特有的自闭合标签（如
   ）和实体（如 ）无法正确解析，从而引入新的错误。
3. 修改 DomConverter 的 preElements 或 unsafeElements 列表： DomConverter 负责视图层和数据层之间的DOM转换，但直接修改其配置通常无法改变编辑器对整个文档结构的根本处理逻辑。这些属性更多地影响特定元素的渲染和安全性，而非文档的整体解析范围。

这些尝试虽然在某些场景下有用，但对于保留、

和等文档结构标签而言，并非正确的解决方案。

解决方案：启用 FullPage 插件

CKEditor 5 针对全页HTML编辑提供了专门的解决方案，即 FullPage 插件。该插件的设计目的就是为了允许编辑器完整地加载、编辑和保存整个HTML文档，包括、

和标签及其内部的所有内容。

要启用此功能，您需要在CKEditor 5的构建配置中引入并声明 FullPage 插件。

步骤一：导入 FullPage 插件


GitHub Copilot
GitHub AI编程工具，实时编程建议
下载

首先，确保从 @ckeditor/ckeditor5-html-support 模块中导入 FullPage 插件。

import { GeneralHtmlSupport, FullPage } from '@ckeditor/ckeditor5-html-support';
// ... 其他插件导入

步骤二：在 builtinPlugins 中包含 FullPage

接下来，将 FullPage 插件添加到您的编辑器构建配置的 Editor.builtinPlugins 数组中。

// Plugins to be included in the build.
Editor.builtinPlugins = [
    // ... 其他核心插件，例如 Essentials, SourceEditing
    FullPage,           // 声明 FullPage 插件以启用全页HTML编辑
    GeneralHtmlSupport, // 如果还需要支持自定义HTML标签/属性，也应包含此插件
    SourceEditing       // 允许查看和编辑HTML源码
];

完整的编辑器配置示例：

以下是一个包含 FullPage 插件的CKEditor 5解耦文档编辑器（DecoupledDocumentEditor）的配置示例：

/* 导入所需的插件 */
import { DecoupledDocumentEditor } from '@ckeditor/ckeditor5-editor-decoupled';
import { Essentials } from '@ckeditor/ckeditor5-essentials';
import { GeneralHtmlSupport, FullPage } from '@ckeditor/ckeditor5-html-support';
import { SourceEditing } from '@ckeditor/ckeditor5-source-editing';
// ... 其他您需要的插件

class Editor extends DecoupledDocumentEditor {
  // 可以在这里添加自定义逻辑，但对于FullPage功能通常不需要覆盖构造函数
}

// 插件列表，用于构建编辑器
Editor.builtinPlugins = [
    Essentials,
    FullPage,           // 启用全页HTML编辑功能
    GeneralHtmlSupport, // 允许在编辑区域内使用更广泛的HTML标签和属性
    SourceEditing       // 提供HTML源码编辑视图
    // ... 其他插件
];

// 编辑器实例化
DecoupledDocumentEditor
    .create( /* 初始HTML内容 */, {
        language: 'zh', // 根据需要配置语言
        htmlSupport: {
            allow: [
                { // 允许所有HTML标签、属性、类和样式，通常与GeneralHtmlSupport配合使用
                    name: /.*/,
                    attributes: true,
                    classes: true,
                    styles: true
                }
            ]
        },
        updateSourceElementOnDestroy: true // 销毁编辑器时更新源元素内容
    })
    .then(editor => {
        // 编辑器创建成功后的处理逻辑
        console.log('CKEditor 5 已成功创建并支持全页HTML编辑。');
        // 将工具栏和编辑区域附加到DOM
        // this.options.toolbarArea.append( editor.ui.view.toolbar.element );
        // this.options.textArea.append(editor.ui.getEditableElement());
    })
    .catch(error => {
        console.error('CKEditor 5 创建失败:', error);
    });

FullPage 与 GeneralHtmlSupport 的区别：

• FullPage 插件： 专注于处理整个HTML文档结构，确保、和等根级标签及其内容（包括,
• GeneralHtmlSupport 插件： 专注于允许在编辑区域（通常是内部）使用更广泛的HTML标签、属性、类和样式。例如，如果您想在段落中插入自定义的标签或带有特定data-*属性的
  ，则需要GeneralHtmlSupport。它改变了编辑器处理HTML“内容”的“灵活性”。

  两者可以同时使用，以实现既能编辑整个文档结构，又能灵活控制文档内容的需求。

  注意事项与总结

  1. 插件依赖： 确保您的CKEditor 5构建中包含了 FullPage 插件。如果使用自定义构建，需要手动将其添加到 builtinPlugins 数组。
  2. 源码模式： 启用 SourceEditing 插件将允许用户在源码模式下直接查看和编辑完整的HTML内容，这对于验证 FullPage 插件是否正常工作非常有帮助。
  3. 内容管理： 当启用全页HTML编辑时，请注意编辑器将处理包括中的元数据、样式和脚本链接。在内容管理系统（CMS）中集成时，需要考虑这些头部信息如何与CMS的整体页面结构协同工作，以避免冲突或重复。
  4. 数据安全： 允许编辑整个HTML文档可能会增加潜在的安全风险，尤其是在不信任的用户输入场景中。请确保对用户提交的内容进行适当的验证和清理。

  通过简单地引入 FullPage 插件，CKEditor 5就能轻松实现对整个HTML文档的编辑和保存，解决了根级标签被移除的问题。这是处理复杂HTML模板或需要对页面结构有完全控制的应用程序的关键功能。