合并字段

合并字段是视觉上不同的占位符元素，您可以将其放在内容中以标记应插入实际值的位置。 非常适合创建文档模板和其他类型的个性化内容。

该功能高度可定制，提供文本和块占位符、预览模式，并与我们的文档导出和导入插件集成。

下面介绍了该功能的典型用例。 选择最适合您需求的设置。

# 模板编辑

最常见的用例是创建文档、电子邮件、发票和其他类型的个性化内容的模板。

用户可以通过多种方式插入预先配置的合并字段元素之一

• 从工具栏下拉菜单 中，
• 从菜单栏中的“插入”→“合并字段”中，
• 或者通过键入左大括号 ({{ 默认情况下)，然后从列表中选择一个合并字段。

要启用此用例，只需配置合并字段定义并向工具栏添加按钮。

您可以在本指南的“配置”部分了解更多有关配置该功能的信息。

# 预览模式

通过定义示例预览数据集来增强模板创建体验。

当用户准备模板时，他们将能够切换到数据预览模式。 在此模式下，合并字段标签将被替换为从所选数据集中获取的值。 这样，用户将更好地了解实际的最终内容可能是什么样子。

默认的初始预览模式为“标签”。当提供其他预览模式的数据时，可以使用工具栏下拉菜单 或通过菜单栏（“视图”→“合并字段预览”）切换预览模式。

# 仅数据设置

编辑器可以配置为始终显示合并字段值，而不是显示标签，并且没有办法切换它。用户将像以前一样将合并字段插入内容中，但他们将始终看到定义的数据。

当您想使用先前准备好的模板在特定数据集（例如客户数据）的上下文中创建具体的內容片段时，此设置非常完美，您可以在此过程中对其进行编辑以进一步个性化内容。

即使从头开始，使用这种配置中的合并字段也很有用！用户可以避免输入错误，并方便地访问正确的值，同时创建的文档始终保持最新，以防相关数据集发生变化。

要启用此用例，请使用功能配置提供数据集，设置初始预览模式并禁用其他预览模式。

除了提供数据集外，您还可以为合并字段定义默认值。当数据集缺少给定合并字段的值时，将使用默认值。此外，还会显示一个错误指示器，以使用户意识到可能存在问题。当您无法保证数据集始终完整时，这很有用。

# 安装

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

import { ClassicEditor, Mention } from 'ckeditor5';
import { MergeFields } from 'ckeditor5-premium-features';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ MergeFields, Mention, /* ... */ ],

        // Provide the license key (see explanation below).
        licenseKey: '<YOUR_LICENSE_KEY>',

        // ...
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# 激活功能

要使用此高级功能，您需要使用正确的凭据激活它。有关详细信息，请参考 许可证密钥和激活 指南。

# 配置

为了最大限度地利用合并字段功能，必须对其进行适当配置。某些选项（例如前缀和后缀或预览模式）具有合理的默认设置，但至少定义可用的合并字段列表至关重要。

# 合并字段定义

要使合并字段出现在编辑器 UI 中，您必须在 mergeFields.definitions 属性中指定它们。

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        mergeFields: {
            definitions: [
                {
                    id: 'guestName',
                    label: 'Guest name', // Optional.
                    defaultValue: 'Guest' // Optional.
                },
                {
                    id: 'guestSpecialOffersBox',
                    label: 'Special offers', // Optional.
                    type: 'block', // Optional.
                    height: '150' // Optional.
                },
                // More merge field definitions.
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

合并字段 ID 是唯一必需的值，它用于编辑器返回的文档数据中。它可以包含字母、数字和 _、.、- 特殊字符。

如果定义了合并字段标签，它将显示在编辑器中。如果没有，则使用 ID 代替。

自定义（未定义）合并字段 也可插入文档中。

在 演示的演示 中使用“源代码编辑”功能，以查看编辑器输出的示例。

# 合并字段类型

该功能支持两种不同类型的合并字段

1. 典型的内联文本合并字段，最常被文本数据替换。例如，客户姓名或发票号码。
2. 块合并字段，它代表一个更大的内容片段，被任意 HTML 结构替换。例如，一行包含显示畅销产品的框或电子邮件页脚。

您可以使用 type 属性定义合并字段类型。可能的值为：'text'（默认）和 'block'。

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        mergeFields: {
            definitions: [
                {
                    id: 'guestAddress',
                    type: 'block',
                    label: 'Guest address' // Optional.
                },
                // More merge field definitions.
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

在编辑器中，文本合并字段被视为文本。它们只能放置在允许文本的地方，可以格式化，也可以是链接。块合并字段的行为类似于其他块级小部件，只能放置在允许块的地方。

对于块合并字段，可以配置它们应该占据多少垂直空间。这使得更容易直观地了解实际内容的外观，或预测分页符。使用 height 属性设置它（默认情况下为 150px）。请注意，此设置仅在未显示给定合并字段的数据时使用。在预览模式下，合并字段高度将取决于合并字段内容。

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        mergeFields: {
            definitions: [
                {
                    id: 'guestAddress',
                    type: 'block',
                    height: '100', // In pixels. Defaults to 150.
                    label: 'Guest address' // Optional.
                },
                // More merge field definitions.
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

在文档数据方面，块合并字段不会包装在任何 HTML 结构中。假设合并字段将被某个块级 HTML 结构替换。请参阅下面的示例文档数据

    <p>
        See the order details below.
    </p>
    {{orderDetails}}
    <p>
        <!-- Further content. -->
    </p>

# 分组合并字段

为了更好地在下拉菜单中组织合并字段，您可以将定义划分为组。

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        mergeFields: {
            definitions: [
                {
                    groupId: 'guest',
                    groupLabel: 'Guest',
                    definitions: [
                        {
                            id: 'guestName',
                            label: 'Guest name',
                            defaultValue: 'Guest'
                        },
                        {
                            id: 'guestTitle',
                            label: 'Guest title',
                            defaultValue: 'Ms./Mr.'
                        },
                        // More merge field definitions
                        // inside the "Guest" group.
                    ]
                },
                // More merge field groups.
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# 前缀和后缀

该 mergeFields.prefix 和 mergeFields.suffix（用于指示合并字段的开始和结束的字符组合）也可以配置。定义的值将返回到编辑器输出中。

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        // Use different kind of brackets for merge fields indicators.
        mergeFields: {
            prefix: '[[',
            suffix: ']]'
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

默认的合并字段括号为 {{ 和 }}。以下字符允许在前后缀中使用：'"`!#%:;=@{}~$()*+/?[\]^|。此外，它们不能超过 8 个字符。

注意：前缀和后缀必须不同。

注意：存储在文档数据中的括号不会在您更改 prefix 或 suffix 配置后自动更新。更改将仅影响新插入的合并字段。此外，旧的合并字段将无法识别，并将显示为纯文本。如果您需要更改括号配置，您还应该处理迄今为止在您的应用程序中创建的所有文档的文档数据。

# 预览模式

预览模式会更改合并字段在编辑器区域中的显示方式。为了预览目的，编辑器可以显示合并字段标签（或 ID），也可以显示数据值。

要能够更改预览模式，您需要定义 合并字段默认值 或 数据集（稍后描述）。

# 可用的预览模式

使用 mergeFields.previewModes 配置选项来指定哪些预览模式应供用户使用。它应指定为三个可能值的任何组合

• “标签”视图（'$labels' 值） - 显示标签（或 ID，如果未指定）。
• “默认值”视图（'$defaultValues'） - 显示默认值（如果指定）。
• 所有配置的数据集（'$dataSets'） - 显示选定数据集的值。

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        mergeFields: {
            // The user will be allowed only to switch between defined data sets,
            // and the merge fields will always display the data related to one of
            // the defined data sets. If there is only one data set, the user will
            // be forced to see the data from that set and will not be able to switch.
            previewModes: [ '$dataSets' ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

注意：必须至少定义一个选项。

注意：如果只提供一种预览模式（即传递的值为 [ '$labels' ] 或 [ '$defaultValues' ]，或者 [ '$dataSets' ] 且只定义了一个数据集），则不会将“合并字段预览”按钮添加到“视图”菜单中。

# 初始预览模式

该 mergeFields.initialPreviewMode 选项指定加载编辑器时应激活哪个预览模式。默认情况下，将显示合并字段标签。

传递的值可以是以下之一：'$labels'、'$defaultValues' 或定义的数据集的 ID 之一。

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        mergeFields: {
            // ID of a data set (see an example below).
            initialPreviewMode: '158673'
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

注意：初始预览模式也必须指定为 可用的预览模式 之一。否则，将抛出错误。

# 数据集

要能够预览合并字段中相应位置的数据，您必须定义至少一个 数据集。数据集应根据定义的合并字段 ID 定义值。如果某些值不可用，则将使用合并字段的默认值（如果已定义）。

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        mergeFields: {
            dataSets: [
                {
                    id: '158673',
                    label: 'David Lee',
                    values: {
                        guestName: 'David Lee',
                        guestTitle: 'Mr.'
                        // Other values in this data set.
                    }
                },
                // More data sets.
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# 在合并字段值中使用 HTML 标签

可以在合并字段值中使用 HTML 代码，无论是在默认值还是数据集值中。

默认情况下，此行为被禁用，合并字段值将被视为纯文本（HTML 标签将被编码）。要启用 HTML 合并字段值

• 将 config.mergeFields.previewHtmlValues 配置标志设置为 true，
• 在 config.mergeFields.sanitizeHtml 属性中提供 HTML 净化函数。

强烈建议您提供 HTML 净化函数.

如果您启用 HTML 合并字段值，当用户切换到预览模式时，分配给合并字段的 HTML 将按原样呈现。因此，**浏览器将在您网站的上下文中执行包含在此 HTML 中的任何 JavaScript 代码**。如果合并字段值来自无法完全信任的外部来源（例如，用户在应用程序的其他部分提供它们），这可能会导致安全漏洞。

如果您没有提供净化函数，将向控制台记录一个警告。

您可以提供您自己的自定义净化函数，或者使用其中一个流行的 JavaScript 库，例如 sanitize-html 和 DOMPurify。

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

# 集成

# 编辑器数据输出

合并字段由 editor.getData() 返回，以指定的前缀和后缀括起来的合并字段 ID 表示，例如：<p>尊敬的 {{guestTitle}} {{guestName}}</p>。这是用于表示合并字段的行业标准格式，便于用实际数据替换合并字段。

在 演示的演示 中使用“源代码编辑”功能，以查看编辑器输出的示例。

注意：切换预览模式以显示数据集值 **不会** 影响编辑器输出。在大多数常规情况下，您始终希望保存包含合并字段占位符的文档数据，而不是值。数据替换应该在需要时发生在您的应用程序逻辑中。

# 包含填充的合并字段的数据输出

在某些情况下，获取用实际数据替换合并字段的文档数据可能很有用。

您可以将值作为选项传递给 editor.getData() 调用

const data = editor.getData( {
    mergeFieldsData: {
        guestName: 'Joe Doe',
        guestTitle: 'Mr.'
    }
} );

编辑器将使用这些值来代替给定的合并字段。

如果未指定给定合并字段的数据，将使用默认数据表单 ([PREFIX][MERGE_FIELD_ID][SUFFIX]，例如 {{guestName}})。

最有可能的是，您希望保存用当前预览的数据集中的值替换合并字段的数据

const mergeFieldsEditing = editor.plugins.get( 'MergeFieldsEditing' );

const mergeFieldsData = mergeFieldsEditing.getDataSetValues(
    mergeFieldsEditing.previewMode, true
);

const data = editor.getData( { mergeFieldsData } );

# 自定义合并字段

编辑器将 **将与合并字段模式匹配的每一段文本转换为合并字段元素**。此行为目前无法关闭。

请注意，从编辑器输出的角度来看，与合并字段匹配的文本是否被编辑器识别无关紧要，因为定义的合并字段和自定义合并字段在编辑器输出中以相同的方式表示。

可以通过以下方式将自定义合并字段添加到编辑器内容中：

• 键入合并字段模式，例如键入 {{myMergeField}}，
• 加载包含未在 合并字段定义 中指定的合并字段的文档数据（包括以前存在的合并字段定义后来从配置中删除的情况），
• 粘贴包含与合并字段模式匹配的文本的外部内容。

自定义合并字段将像一个仅定义了 ID 的合并字段一样。

# 文档导出插件

使用 导出到 Word 或 导出到 PDF 功能来处理包含合并字段的文档会产生不同的结果，具体取决于当前的 预览模式。导出功能将遵循“所见即所得”逻辑。

当在“标签”预览模式下使用导出时

• 导出的 Word 文档将包含 Word 文档合并字段（它将被导出为“模板”文档）。
• 导出的 PDF 文件将包含默认数据表单中的合并字段 [PREFIX][MERGE_FIELD_ID][SUFFIX]，例如 {{guestName}}）。

当预览默认值或数据集值时使用导出，合并字段将被相应的值替换，如编辑器区域中预览的那样。

# 从 Word 导入

从 Word 导入功能将识别 Word 文档合并字段，并将其无缝转换为编辑器合并字段。

# 将合并字段与模板一起使用

合并字段可以与模板功能一起使用。使用“插入模板” 下拉菜单将模板添加到编辑器中。

# 通用 API

The MergeFields 插件注册

• The 'insertMergeField' 和 'previewMergeFields' 工具栏和菜单栏按钮。
• The 'mergeFieldsData' 选项用于 getData() 方法（有关详细信息，请参阅 包含填充的合并字段的数据输出 部分）。