评论概览

评论功能允许您在内容的任何部分添加评论，包括文本和块元素，例如嵌入式媒体或图片。对于多个作者在同一文档上协作，这是一种很好的沟通方式。

# 演示

在下面的编辑器中测试评论功能。选择您需要评论的段落或单词，并使用工具栏按钮 添加评论。使用侧边栏检查现有的评论，并删除评论或评论线程。您还可以解决线程以整理侧边栏并稍后在评论存档下拉菜单中找到它们 .

已评论的内容将被标记为突出显示，并且在侧边栏或内联中会显示相应的评论气泡。评论可以添加、编辑、删除和回复，允许用户直接在富文本编辑器中协作处理同一文档。评论线程可以删除或解决。后者提供了一种归档不再相关的评论的方法，减少混乱并使专注于最重要的反馈变得更容易。用户可以从工具栏访问评论存档，并使用它来查看和恢复已归档的评论（如有必要）。它有助于简化反馈管理流程。评论标记会 与内容一起移动 在剪切和粘贴以及拖放操作中。

评论功能可以与 实时协作 一起使用，也可以用作独立插件，其中评论使用 自定义集成 保存到您的应用程序中。您可以在 这篇专门的博客文章 中了解有关 CKEditor 5 的协作功能及其真实应用的更多信息。

如果要限制用户权限，只允许他们向文档添加评论，但不允许他们直接编辑内容，则还可以使用 仅评论模式。

# 集成

# 用作独立插件

评论插件不需要实时协作即可工作。如果您更喜欢更传统的文档编辑方法，评论可以像任何其他插件一样添加到 CKEditor 5 中。

要了解如何将评论作为独立插件集成，请参考 将评论与您的应用程序集成 指南。

# 与实时协作一起使用

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

# 了解更多

# 配置

评论功能的配置详细信息可以在 CommentsConfig API 参考中找到。

# 带有提及的评论

可以配置 提及功能 以与评论功能一起使用。在这里你可以找到 有关该过程的详细描述。

# 评论标记

评论始终附加到文档中的某个位置。为了确保它们不会丢失，评论插件会向文档添加一些特殊的标记。

• 如果评论在文本中开始/结束，则会添加 <comment-start> 和 <comment-end> 标记。
• 否则，以下属性将添加到元素中
  • data-comment-start-before,
  • data-comment-end-after,
  • data-comment-start-after,
  • data-comment-end-before.

editor.getData( { ignoreResolvedComments: true } );

了解有关 标记到数据转换 的更多信息，以了解您可能期望的数据。

# 可能标记的示例

对文本的评论

<p>They are <comment-start name="b39dd790"></comment-start>awesome<comment-end name="b39dd790"></comment-end>.</p>

对图像的评论

<figure class="image" data-comment-end-after="b39dd790" data-comment-start-before="b39dd790">
    <img src="foo.jpg">
    <figcaption>Image caption.</figcaption>
</figure>

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

如果您需要在没有评论的情况下显示文档数据，您可以简单地从文档数据中删除评论标记。

<p>They are awesome.</p>

但是，在启动编辑器时，请确保在 HTML 中包含评论标记。

<div id="container">
    <div id="editor">
        <p>They are <comment-start name="b39dd790"></comment-start>awesome<comment-end name="b39dd790"></comment-end>.</p>
    </div>
    <div id="sidebar"></div>
</div>

# 评论属性

The comments attributes 是可以设置和使用由围绕评论构建的功能的自定义数据。它们可以用来指示评论的紧急程度或严重程度，将它们归类到主题领域等。您可以使用属性将您的功能数据与其他评论数据一起存储。

comment.setAttribute( 'isImportant', true );

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

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

设置在评论上的属性可以通过 attribute 属性访问。

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

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

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

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

# 评论线程属性

类似地，评论线程属性是可以在围绕评论构建的功能中设置和使用的自定义数据。使用它将您的功能数据与其他评论线程数据一起存储。您还可以使用点表示法将多个值分组到一个对象中。

commentThread.setAttribute( 'customData.isImportant', true );

设置在评论上的属性可以通过 attribute 属性访问。

const isImportant = commentThread.attributes.customData.isImportant;

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

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

无论何时调用 setAttribute() 或 removeAttribute()，attributes 属性都会重新设置，并且可观察对象也会刷新。

# 为什么评论内容没有存储在文档数据中？

请注意，标记只存储评论线程 ID。出于安全原因，它们不包含任何内容。如果您将完整的评论讨论与编辑器内容一起存储，恶意用户可以编辑它，包括其他作者撰写的评论。很难检查保存数据时用户对评论进行了哪些更改。您需要分析文档的全部内容，并将其与以前版本进行比较。考虑到内容和评论都可能同时更改，并且它们混合在一起，确保只引入了授权更改将是一项艰巨的任务。出于这些原因，适配器集成 是推荐的解决方案。

但是，如果您想将内容与评论数据一起保存，请查看 简单的“加载和保存”集成 指南，这应该对您有所帮助。

# 字符限制

出于技术原因，线程中的每个评论都有一个字符限制，设置为 65000 个字符。请注意，评论内容存储在 HTML 格式中，因此 HTML 标签（对用户不可见）会占用一些字符限制。如果超过限制，用户界面将阻止用户提交评论。

# API 概述

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

# 评论注释自定义

评论注释是高度可定制的。请参考 注释自定义 指南以了解更多信息。

# 仅评论模式

您可以以 “仅评论”模式 运行编辑器。在此模式下，用户可以添加、编辑和删除评论，但无法编辑文档内容或以其他方式更改文档数据。

# 多个编辑器的评论

如果您的应用程序在一个页面上显示多个编辑器，您可能想要使用 上下文功能。它将（除其他外）让您在一个侧边栏中显示来自所有编辑器的评论。

# 编辑器外部的评论

评论功能也可以在常规表单字段或 HTML 元素上使用。因此，您可以允许对应用程序的所有元素进行评论，并提供统一的用户体验和界面。查看 编辑器外部的评论 指南以了解更多信息。