跟踪更改概述

此功能在 CKEditor 5 中启用跟踪更改模式（也称为建议模式）。这样，您可以跟踪不同编辑者所做更改的历史记录，并轻松接受或拒绝这些更改。

这是一个高级功能，您需要在 CKEditor 5 商业许可证的基础上获得该功能的许可证。联系我们，以获取满足您需求的报价。

您也可以注册CKEditor 高级功能 30 天免费试用来测试该功能。

# 演示

您可以在下面的编辑器中测试跟踪更改功能。使用工具栏下拉菜单来启用更改跟踪，以及批量接受或拒绝建议。使用侧边栏操作单个更改。

此演示展示了一组有限的功能。请访问功能丰富的编辑器示例，以查看更多功能的实际应用。

在此模式下，用户所做的更改将在内容中标记，并在侧边栏中显示为建议。用户可以接受或拒绝建议。建议气泡将随后关闭，更改不再标记。

建议注释可以显示在侧边栏中，也可以显示为内联气泡。请访问显示模式指南，了解如何配置显示模式。为评论指定的模式也会设置为跟踪更改。

此示例会根据屏幕大小自动切换显示模式。调整窗口大小并观察编辑器如何改变其外观。

除了阅读本指南之外，我们还鼓励您阅读专门的博客文章，其中比较了跟踪更改与修订历史记录，以及另一篇讨论CKEditor 5 的协作功能及其现实生活中的应用的博客文章。

# 集成

# 用作独立插件

跟踪更改功能不需要实时协作即可工作。如果您更喜欢传统的文档编辑方法，则可以像添加其他插件一样将跟踪更改添加到 CKEditor 5 中。

要了解如何将跟踪更改集成到独立插件中，请参阅将跟踪更改与您的应用程序集成指南。

# 与实时协作一起使用

如果您使用实时协作功能，请参阅实时协作功能集成指南。

# 了解更多

在编辑器中运行跟踪更改功能后，您可能需要了解有关它的更多信息。请在下面找到有关它如何工作、如何配置、自定义和扩展以最佳方式适合您的应用程序的信息。

# 配置

跟踪更改功能的配置可以在 TrackChangesConfig API 参考中找到。

# 建议标记

建议总是附加到文档中的某个位置。为了确保建议不会丢失，跟踪更改插件会向文档添加一些特殊的标记。

如果建议在文本中开始/结束，则会添加<suggestion-start> 和 <suggestion-end> 标签，
否则，会向元素添加以下属性：
- data-suggestion-start-before,
- data-suggestion-end-after,
- data-suggestion-start-after,
- data-suggestion-end-before.

此外，<suggestion-td> 标签用于表格单元格，将建议粘贴到表格单元格中，以将旧内容（原始内容）与新内容（粘贴的内容）分开。

详细了解标记到数据转换以了解您可以期望获得哪些数据。

可能的标记示例

用“ice-cream”替换“chocolate”

<p>
    I like
    <suggestion-start name="insertion:e8ghd7:e390dk"></suggestion-start>ice-cream<suggestion-end name="insertion:e8ghd7:e390dk"></suggestion-end>
    <suggestion-start name="deletion:ejd853:e390dk"></suggestion-start>chocolate<suggestion-end name="deletion:ejd853:e390dk"></suggestion-end>.
</p>

插入图片

<figure class="image" data-suggestion-end-after="insertion:e1f0810:eohfu9" data-suggestion-start-before="insertion:e1f0810:eohfu9">
    <img src="foo.jpg">
    <figcaption>Image caption.</figcaption>
</figure>

添加粗体

<p>
    This is
    <suggestion-start name="attribute:bold|ci1tcnk0lkep:ekeij:e3404"></suggestion-start>
    <strong>important</strong>
    <suggestion-end name="attribute:bold|ci1tcnk0lkep:ekeij:e3404"></suggestion-end>
    .
</p>

将包含文本“New”的表格单元格粘贴到包含文本“Old”的表格单元格中

<td ...>
    <suggestion-td data-suggestion-end-after="insertion:..." data-suggestion-start-before="insertion:...">
        <p>New</p>
    </suggestion-td>
    <suggestion-td data-suggestion-end-after="deletion:..." data-suggestion-start-before="deletion:...">
        <p>Old</p>
    </suggestion-td>
</td>

请注意，如果您的应用程序过滤 HTML 内容（例如，为了防止 XSS），请确保在将内容保存到数据库中时保留建议标签和属性。建议标记对于进一步的编辑会话是必需的。

# 建议属性

建议属性是与建议一起存储的附加数据，并由其他功能使用。您也可以使用它们设置和读取自定义功能所需的自定义数据，这些自定义功能围绕建议构建。

suggestion.setAttribute( 'isImportant', true );

您可以使用点表示法将多个值分组到一个对象中。

suggestion.setAttribute( 'customData.type', 'image' );
suggestion.setAttribute( 'customData.src', 'foo.jpg' );

可以通过attribute 属性访问设置在建议上的属性。

const isImportant = suggestion.attributes.isImportant;
const type = suggestion.attributes.customData.type;

您还可以观察attributes 属性或将其他属性绑定到它。

myObj.bind( 'customData' ).to( suggestion, 'attributes', attributes => attributes.customData );

每当调用setAttribute() 或 removeAttribute() 时，attributes 属性都会重新设置，并且可观察对象也会刷新。使用这些操作会在适配器中触发update 方法。

# 保存不带建议的数据

如果您需要获取包含所有已接受或已放弃建议的编辑器数据，请参阅专用指南。

# 保存带有建议突出显示的数据

默认情况下，editor.getData() 返回的数据包含建议的标记，如上所述。它不提供在数据中直观显示建议突出显示的标记（类似于它们在编辑器中的显示方式）。

可以使用传递给editor.getData() 的showSuggestionHighlights 选项更改编辑器输出。当设置此选项时，编辑器输出将返回建议，类似于它们在编辑器中的显示方式。

editor.getData( { showSuggestionHighlights: true } );

将返回

<p>
    <span class="ck-suggestion-marker ck-suggestion-marker-formatInline">
        Foo
    </span>
    bar
</p>

使用showSuggestionHighlights 选项生成的结果数据不能用于加载编辑器数据（它不能传递给editor.setData()）！

此功能应用于预览目的，例如，可以与导出到 PDF 功能一起使用。

导出到 PDF 功能可以与建议突出显示集成，如下所示

{
    exportPdf: {
        // More configuration of the Export to PDF.
 		// ...
        dataCallback: editor => editor.getData( {
            showSuggestionHighlights: true
        } )
    }
}

# 强制启用跟踪更改模式

如果您希望默认启用跟踪更改，请执行trackChanges 命令，该命令切换跟踪更改模式。它应该在编辑器实例初始化后完成。

ClassicEditor
    .create( document.querySelector( '#editor' ), {
       // Editor's configuartion.
 		// ...
    } )
    .then( editor => {
        editor.execute( 'trackChanges' );
    } )
    .catch( error => console.error( error ) );

您可以禁用trackChanges 命令，以防止开启或关闭跟踪更改。例如，当某个特定用户只被授权在给定文档中创建建议时，这将很有用。您可以通过调用Command#forceDisabled() 来禁用该命令。

ClassicEditor
        .create( document.querySelector( '#editor' ), {
            // Editor's configuartion.
 			// ...
        } )
        .then( editor => {
            editor.execute( 'trackChanges' );

            editor.commands.get( 'trackChanges' ).forceDisabled( 'suggestionsMode' );
        } )
        .catch( error => console.error( error ) );

要阻止用户接受或放弃建议，请禁用负责这些操作的命令。

ClassicEditor
        .create( document.querySelector( '#editor' ), {
        	// Editor's configuartion.
 			// ...
        } )
        .then( editor => {
          editor.execute( 'trackChanges' );

          editor.commands.get( 'trackChanges' ).forceDisabled( 'suggestionsMode' );
          editor.commands.get( 'acceptSuggestion' ).forceDisabled( 'suggestionsMode' );
          editor.commands.get( 'acceptAllSuggestions' ).forceDisabled( 'suggestionsMode' );
          editor.commands.get( 'discardAllSuggestions' ).forceDisabled( 'suggestionsMode' );
          editor.commands.get( 'discardSuggestion' ).forceDisabled( 'suggestionsMode' );
        } )
        .catch( error => console.error( error ) );

请记住，'suggestionsMode' 标识符可用于稍后使用Command#clearForceDisabled() 启用命令。

# 标记样式

与 CKEditor 5 生态系统中的所有内容一样，我们使用了CSS 变量，让开发者可以自定义 UI 元素（例如建议标记）的设计。您可以使用.css 文件覆盖这些属性，或将自定义内容直接放置在页面的<head> 部分中，但在这种情况下，您需要使用比:root 更具体的 CSS 选择器（例如<body>）。

查看颜色表以了解可自定义颜色的完整列表。您也可以浏览 CKEditor 5 中的其他文件，这些文件包含 CSS 变量。

您可以在此处找到用于跟踪更改功能的默认 CSS 变量。

:root {
    /* You can override the design of suggestion markers in the content. */

    /* Variables responsible for suggestions for text: */
    --ck-color-suggestion-marker-insertion-border: hsla(128, 71%, 40%, .35);
    --ck-color-suggestion-marker-insertion-border-active: hsla(128, 71%, 25%, .5);
    --ck-color-suggestion-marker-insertion-background: hsla(128, 71%, 65%, .35);
    --ck-color-suggestion-marker-insertion-background-active: hsla(128, 71%, 50%, .5);

    --ck-color-suggestion-marker-deletion-border: hsla(345, 71%, 40%, .35);
    --ck-color-suggestion-marker-deletion-border-active: hsla(345, 71%, 25%, .5);
    --ck-color-suggestion-marker-deletion-background: hsla(345, 71%, 65%, .35);
    --ck-color-suggestion-marker-deletion-background-active: hsla(345, 71%, 50%, .5);
    --ck-color-suggestion-marker-deletion-stroke: hsla(345, 71%, 20%, .5);

    --ck-color-suggestion-marker-format-border: hsla(191, 90%, 40%, .4);
    --ck-color-suggestion-marker-format-border-active: hsla(191, 90%, 40%, .65);

    /* Variables responsible for the left border of the suggestion boxes in the sidebar: */
    --ck-color-comment-box-border: hsl(55, 98%, 48%);
    --ck-color-suggestion-box-deletion-border: hsl(345, 62%, 60%);
    --ck-color-suggestion-box-insertion-border: hsl(128, 62%, 60%);
    --ck-color-suggestion-box-format-border: hsl(191, 62%, 60%);

    /* Variables responsible for the styling of suggestions for widgets: */
    --ck-color-suggestion-widget-insertion-background: hsla(128, 71%, 65%, .05);
    --ck-color-suggestion-widget-insertion-background-active: hsla(128, 71%, 50%, .07);
    --ck-color-suggestion-widget-deletion-background: hsla(345, 71%, 65%, .05);
    --ck-color-suggestion-widget-deletion-background-active: hsla(345, 71%, 45%, .07);
    --ck-color-suggestion-widget-format-background: hsla(191, 90%, 40%, .09);
    --ck-color-suggestion-widget-format-background-active: hsla(191, 90%, 40%, .16);

    --ck-color-suggestion-widget-th-insertion-background: hsla(128, 71%, 65%, .1);
    --ck-color-suggestion-widget-th-insertion-background-active: hsla(128, 71%, 50%, .12);
    --ck-color-suggestion-widget-th-deletion-background: hsla(345, 71%, 65%, .1);
    --ck-color-suggestion-widget-th-deletion-background-active: hsla(345, 71%, 45%, .12);
}

# API 概述

查看跟踪更改 API 文档以获取有关跟踪更改 API 的详细信息。熟悉 API 可能有助于您理解代码片段。

# 建议注释自定义

建议注释是高度可自定义的。请参阅注释自定义指南以了解更多信息。

# 与自定义功能集成

如果您提供自己的插件，您可能需要将这些自定义功能与跟踪更改模式集成。

我们每天都在努力使我们的文档保持完整。您是否发现过时信息？是否有缺失的内容？请通过我们的问题跟踪器报告。

随着 42.0.0 版本的发布，我们重新编写了大部分文档以反映新的导入路径和功能。感谢您的反馈，帮助我们确保文档的准确性和完整性。