支持的协作功能

从 Word 导入转换器支持 Word 的协作功能，即评论和修订。评论功能允许您对所选内容添加注释，而修订功能允许您在内容中提出更改建议，例如删除、插入或替换所选内容的一部分。

这两个功能也由 CKEditor 5 实现，因此请确保阅读 CKEditor 5 评论 和 CKEditor 5 修订 指南以了解更多信息。

请注意，尽管从 Word 导入转换器会生成与 CKEditor 5 协作功能兼容的内容，但它与技术无关，可以在您的最终集成中使用，只要它支持相同的格式。

从本指南中了解这些是如何转换为 HTML 属性并由 CKEditor 5 支持的。

# 评论

评论是 Word 的一项高级功能，从 Word 导入功能支持该功能，并与 CKEditor 5 评论 完全兼容。您可以通过选择一些内容并从功能区的“插入”选项卡中选择“新建评论”选项来添加评论，或者只是使用右键单击所选内容打开的上下文菜单来添加评论。

从 Word 导入通过生成与 CKEditor 5 兼容的 HTML 并返回评论定义来完全保留评论，这些定义可以通过使用 从 Word 导入 CKEditor 5 插件 或实现自定义评论集成来进行集成。

要使用 REST API 启用评论转换，请在请求主体中传递有关 用户 ID 和 collaboration_features.comments 属性的信息。

const config = {
    collaboration_features: {
        user_id: 'user-id',
        comments: true
    }
};

以上屏幕截图中显示的简单评论将返回的示例负载如下所示

{
  "html": "<p><comment-start name=\"thread-id\"></comment-start>Hello, World!<comment-end name=\"thread-id\"></comment-end></p>",
  "comment_threads": [
    {
      "thread_id": "thread-id",
      "is_resolved": false,
      "comments": [
        {
          "author": "John",
          "content": "<p>Comment 1</p>",
          "created_at": "2022-09-19T15:05:00Z",
          "is_resolved": false,
        },
        {
          "author": "Neil",
          "content": "<p>Comment 2</p>",
          "created_at": "2022-09-19T15:05:00Z",
          "is_resolved": false,
        }
      ]
    }
  ]
}

comment_threads JSON 属性包含在文档中找到的所有评论的完整列表，按评论线程 ID 分组。每个评论包含以 HTML 格式的评论内容以及有关评论原始 author 的信息。

评论功能由 CKEditor 5 完全支持，只需启用 CKEditor 5 评论 和 从 Word 导入 插件即可。

# 已解决的评论

在 Word 中解决评论是一种表明已解决特定评论且不再成为问题的方式。要解决评论，用户只需右键单击它并选择“解决评论”。然后，该评论将变灰，并将在其旁边显示一个复选标记。

从 Word 导入会在返回的负载中返回有关已解决评论的信息。is_resolved 属性指示用户是否已解决评论。此属性可以在评论线程和单个评论中找到。只有当线程中的所有评论都被标记为已解决时，评论线程才会被视为已解决。

已解决的评论由 CKEditor 5 评论 功能支持。

# 评论样式

默认情况下，将保留应用于评论的所有样式。如果您想限制转换期间应用的评论格式，formatting.comments 将派上用场。

该选项可以使用以下值之一

• full - 默认值，启用所有评论样式，
• basic - 仅保留粗体、斜体、下划线和删除线样式，
• none - 将不保留任何样式。

const config = {
    collaboration_features: {
        user_id: 'user-id',
        comments: true
    },
    formatting: {
        comments: 'basic'
    }
};

# 修订

修订是另一项高级功能，它也与 CKEditor 5 修订 兼容。要在 Word 中开始跟踪更改，请从功能区中选择“审阅”选项卡，然后启用“修订”选项。之后，对文档进行的任何更改都将被跟踪。

目前，从 Word 导入支持文本插入和删除，包括表格、列表和图像内的更改。

此外，当部分内容移动到文档中的不同位置时，Word 文档可以包含移动建议。这些建议由一对相应的删除和插入建议表示，简化了它们的整体结构，而不会丢失任何信息。

要使用 REST API 启用修订转换，请在请求主体中传递有关 用户 ID 和 collaboration_features.track_changes 属性的信息。

const config = {
    collaboration_features: {
        user_id: 'user-id',
        track_changes: true
    }
};

简单建议将返回的示例负载

{
  "html": "<p>Hello, <suggestion-start name=\"suggestion-id:user-id\"></suggestion-start>World!<suggestion-end name=\"suggestion-id:user-id\"></suggestion-end></p>",
  "suggestions": [
    {
        "id": "suggestion-id",
        "type": "insertion",
        "author": "John",
        "created_at": "2022-09-19T15:05:00Z"
    }
  ]
}

suggestions JSON 属性包含在文档中找到的所有建议的完整列表。每个建议包含应用于建议定义和 HTML 内容的建议的唯一 ID、建议的类型 (insertion/deletion) 以及有关建议原始 author 的信息。

修订功能由 CKEditor 5 完全支持，只需启用 CKEditor 5 修订 和 从 Word 导入 插件即可。

# 时区

Word 修订功能不支持建议创建日期的 UTC 格式。为了正确计算它们，我们使用通过 config.timezone 提供给转换器的时区数据 (在 API 文档中阅读有关此配置选项的更多信息)。

# 已知限制

• 对跟踪表格和列表等 HTML 块元素对这些元素文本内容的更改的支持有限。
• 不支持格式化建议，例如将粗体应用于文本或将段落更改为列表。

# 禁用修订

如果文档包含一些建议，但修订功能被 collaboration_features.track_changes 配置选项禁用，则所有修订都将被视为已应用。例如，如果用户有一个包含文本插入建议的文档，则该文本将被应用于 HTML 作为常规文本。删除建议的工作方式相同 - 如果一些内容被建议删除，它将从 HTML 中删除。

这种行为确保在转换过程中尽可能少地丢失内容，确保即使您没有启用修订功能，您仍然可以充分利用从 Word 导入转换器。

# 协作作者和用户

请注意，从 Word 导入的作者（也可见于 CKEditor 5 中作为用户）直接从 .docx 文件加载。它们与 Cloud Services 中创建的用户不同。

Word 文档可以由第三方作者操作，如果它们自动连接到 Cloud Services 用户，可能会构成潜在的安全威胁。因此，CKEditor 5 协作功能确保评论或建议的作者仅用于显示目的。实际连接到 CKEditor 5 协作功能的用户是登录到 Cloud Services 的用户。

让我们考虑以下情况：有一个在 CKE5 中编辑的文档，其中包含一些评论。该文档被导出到 Word，然后重新导入到 CKEditor 5。在这种情况下，评论作者和 Cloud Services 用户之间的连接将丢失，因为 CKEditor 5 无法仅根据提供的 Word 文件来猜测哪个用户是评论的作者。