HTML 嵌入

HTML 嵌入功能允许您在内容中嵌入任何 HTML 代码段。该功能旨在为想要直接与 HTML 片段交互的更高级用户使用。

# 演示

使用以下编辑器中的 HTML 嵌入工具栏按钮 来查看插件的实际操作。单击编辑器下方的“预览编辑器数据”按钮以预览编辑器内容，包括嵌入的 HTML。

# 其他功能信息

此功能允许您嵌入任何 HTML 代码，并绕过 CKEditor 5 的过滤机制。您可以使用它来使用 CKEditor 5 不支持的 HTML 片段来丰富 CKEditor 5 生成的内容。

以下是一些您可以使用 HTML 嵌入功能嵌入的内容示例

• 分析代码（通常需要嵌入 <script> 元素）。
• 社交页面小部件（也需要嵌入 <script> 元素）。
• 通过 <iframe> 元素可嵌入的内容。
• HTML 媒体元素，如 <audio> 和 <video>。
• 由外部工具生成的 HTML 代码段（例如，报告或图表）。
• 需要组合使用丰富的 HTML 和脚本的交互式内容。

我们建议您使用 媒体嵌入 功能来处理此功能支持的可嵌入媒体。您可以使用 HTML 嵌入功能来处理其余内容。

# 安装

在 安装编辑器 后，将功能添加到您的插件列表和工具栏配置中

import { ClassicEditor, HtmlEmbed } from 'ckeditor5';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ HtmlEmbed, /* ... */ ],
        toolbar: [ 'htmlEmbed', /* ... */ ],
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# 配置

# 内容预览

默认情况下，该功能配置为不显示 HTML 代码段的预览。您可以通过将 config.htmlEmbed.showPreviews 选项设置为 true 来启用预览。

但是，通过显示嵌入的 HTML 代码段的预览，您会让系统用户面临在编辑器中执行恶意 JavaScript 代码的风险。因此，强烈建议您插入一些 HTML 清理器，它会在呈现其预览之前从创建的代码段中删除恶意代码。您可以通过定义 config.htmlEmbed.sanitizeHtml 选项来插入清理器。

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ HtmlEmbed, /* ... */ ],
        toolbar: [ 'htmlEmbed', /* ... */ ],
        htmlEmbed: {
            showPreviews: true,
            sanitizeHtml: ( inputHtml ) => {
                // Strip unsafe elements and attributes, for example:
                // the `<script>` elements and `on*` attributes.
                const outputHtml = sanitize( inputHtml );

                return {
                    html: outputHtml,
                    // true or false depending on whether the sanitizer stripped anything.
                    hasChanged: true
                };
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

目前，该功能不会执行 <script> 标记，因此需要执行 JavaScript 来生成预览的内容将不会显示在编辑器中。但是，其他 JavaScript 代码（例如，在 on* 观察者和 src="javascript:..." 属性中使用的代码）将被执行。您仍然需要启用清理器。

在下一节中阅读有关安全方面的更多信息。

# 安全

如果您将 HTML 嵌入功能配置为 显示内容预览，则用户插入 HTML 嵌入小部件中的 HTML 将被渲染回给用户。**如果 HTML 按原样渲染，浏览器将在您网站的上下文中执行这些 HTML 代码段中包含的任何 JavaScript 代码。**

这反过来又是一个明显的安全风险。用户提供的 HTML 可能是从恶意网站错误复制的。它也可能以其他方式最终出现在用户的剪贴板中（因为它通常会被复制和粘贴）。

您可以指示一些高级用户永远不要从不可信来源粘贴 HTML 代码。但是，在大多数情况下，强烈建议您通过将 HTML 嵌入功能配置为使用 HTML 清理器，并根据需要设置严格的内容安全策略 (CSP) 规则来保护系统。

# 清理器

config.htmlEmbed.sanitizeHtml 选项允许插入外部清理器。

您可以使用的一些流行的 JavaScript 库包括 sanitize-html 和 DOMPurify。

这些库的默认设置通常会去除所有潜在的恶意内容，包括来自可信来源的<iframe>、<video>或类似元素和 JavaScript 代码。您可能需要调整其设置以满足您的需求。

# CSP

除了使用清理器之外，您还可以使用内置的浏览器机制，称为内容安全策略。通过使用 CSP，您可以让浏览器知道执行 JavaScript 代码和包含其他资源（例如样式表、图像和字体）的允许来源和方式。

# 相关功能

CKEditor 5 支持更广泛的嵌入和代码功能，包括

• 媒体嵌入 – 将可嵌入的媒体（例如 YouTube 或 Vimeo 视频和推文）插入您的富文本内容中。
• 代码块 – 插入更长、多行的预格式化代码列表，并分配编程语言。
• 通用 HTML 支持 – 启用其他专用 CKEditor 5 插件不支持的 HTML 功能（元素、属性、类、样式）。

# 通用 API

HtmlEmbed插件注册

• UI 按钮组件 ('htmlEmbed')。
• 由 HtmlEmbedCommand 实现的 'htmlEmbed' 命令。

您可以使用 editor.execute() 方法执行命令

// Inserts an empty HTML embed.
editor.execute( 'htmlEmbed' );

// Inserts an HTML embed with some initial content.
editor.execute( 'htmlEmbed', '<b>Initial content</b>.' );

// Updates the content of a selected HTML embed.
editor.execute( 'htmlEmbed', '<b>New content.</b>' );

# 贡献

该功能的源代码在 GitHub 上提供，网址为 https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-html-embed。