更新至 CKEditor 5 v37.x

# 更新至 CKEditor 5 v37.0.0

发布日期：2023 年 4 月 5 日。

有关 37.0.0 版本中引入的所有更改的完整列表，请参阅CKEditor 5 v37.0.0 的发行说明.

以下是升级至 CKEditor 5 v37.0.0 时需要您注意的最重要更改。

# 将 Node.js 的最小版本提升至 16.x

Node.js 14 于 2023 年 4 月结束长期支持。因此，从 v37.0.0 版本开始，CKEditor 5 所需的 Node.js 最小版本将为 16。

# TypeScript 类型定义

从 37.0.0 版本开始，CKEditor 5 提供原生 TypeScript 类型，因此不再需要社区类型。为了解决这个问题，可能需要将社区类型替换为软件包提供的原生类型。以下是如何操作：

1. 删除社区类型

   • 删除任何使用的@types/ckeditor__ckeditor5-*软件包。
   • 删除您在项目中进行的任何类型增强。

   例如

   // typings/types.d.ts
   
   declare module 'ckeditor5/src/core' {
       export * from 'ckeditor__ckeditor5-core';
   }
   
   declare module 'ckeditor5/src/ui' {
       export * from 'ckeditor__ckeditor5-ui';
   }
   

2. 将社区类型替换为原生类型

   • 更新任何导入语句，使用原生类型代替社区类型。
   • 更新任何引用社区类型的代码，使用原生类型。
   • 确保所有导入都来自软件包入口点，而不是模块路径。

   例如

   // Instead of:
   import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
   
   // Do:
   import { Plugin } from 'ckeditor5';
   

3. 调整您的tsconfig.json以包含至少

   {
       "compilerOptions": {
           "lib": [
               "DOM",
               "DOM.Iterable"
           ],
           "module": "es6",
           "target": "es2019",
           "moduleResolution": "node"
       }
   }
   

   您可以为项目选择其他选项，但不能保证它们有效。

4. 测试您的项目

   • 确保更改没有引入任何新的错误或问题。
   • 验证项目是否按预期运行。

感谢我们的社区迄今为止提供的类型！

# 评论存档

CKEditor 5 v37.0.0 引入了评论存档功能。您将在下面找到有关该功能的说明以及在可能影响某些集成的重大更改发生的情况下进行迁移的提示。

如果您想比较差异，则先前编辑器版本 (36.0.1) 的文档 仍然可用。

# 一般说明

• 默认情况下启用评论存档，您无法关闭它。
• 您需要将commentsArchive按钮添加到工具栏才能访问评论存档面板。
• 评论注释中的 UI 已更改。删除和编辑按钮已移至下拉菜单。添加了一个用于解决评论线程的新按钮。
• 已解决的评论线程的标记仍然保留在文档数据中。这允许重新打开（删除“已解决”状态）评论线程。如果它们的关联标记仍然存在于内容中，则可以重新打开评论线程。
• 从文档中删除评论内容时，相关的评论线程将被解决并移至存档。
• 在使用Context和多个编辑器实例的集成中，每个编辑器实例仅在其评论存档面板中显示其自身的评论线程。
• 在引入评论存档之前删除的评论线程不会显示在存档中。
• 撤消功能不再撤消创建或删除评论线程。
• 撤消功能不再撤消解决或重新打开评论线程。

# 重大更改

# 异步协作集成

这涉及使用评论功能但不进行实时协作并提供其集成的应用程序。

# “加载和保存”集成

您需要存储评论线程的额外数据，并在添加评论数据时将其传递给CommentsRepository#addCommentThread()。确保您正确存储了新属性：resolvedBy、resolvedAt、context和attributes。根据您的集成，这可能需要对数据库进行更改。

# 适配器集成

评论线程成为实际的数据实体，具有您需要保存在数据库中的属性。这需要对适配器进行更改，并且根据您的集成，可能需要对数据库进行更改。

在评论适配器中需要新的方法

• addCommentThread()
• updateCommentThread()
• resolveCommentThread()
• reopenCommentThread()
• removeCommentThread() - 现在是必需的（之前是可选的）。

此外，您还应该更新getCommentThread()以解析为包含新评论线程属性的对象：resolvedBy、resolvedAt、context和attributes。

您还可以查看评论适配器的更新 API 文档。

# 自定义视图和模板

这涉及自定义评论和评论线程视图和模板的应用程序。

许多 CSS 规则已更改，因此请确保您的自定义视图正确显示。此外，评论注释现在可能显示在从工具栏访问的评论存档下拉菜单中。这意味着您的自定义视图可能会受到新 CSS 规则（最重要的是 CSS 重置规则）的影响。确保您的自定义视图在评论存档下拉菜单中正确显示。

由于引入了评论存档，评论和评论线程视图和模板已发生重大更改。这些更改可能与您的自定义视图或模板不兼容。查看以下内容

• CommentThreadView 模板.
• CommentView 模板.
• 更新的自定义模板和自定义视图指南。
• CommentThreadView 引入了resolveButton，它触发一个新的resolveCommentThread事件。如果您有完全自定义的线程视图（直接继承自BaseCommentThreadView），请实现一个 UI 元素，该元素将在CommentThreadView上触发此事件。

最后，我们引入了一种特殊的评论类型，“系统评论”。它看起来像一个简单的评论，并显示系统消息，例如“评论线程已解决”（显示在已解决的评论线程中）。这些评论使用CommentView（或定义的自定义视图）创建。系统评论的#isSystemComment属性设置为true。您可以使用它来识别系统评论并提供必要的自定义（例如，系统评论不应具有操作按钮）。系统评论接收临时评论模型。系统评论模型的attributes属性设置为一个空对象。确保您的自定义评论视图正确处理系统评论。

# 编辑器外部的评论

这涉及在编辑器外部使用评论功能的应用程序。

您需要处理 API 中的新事件、属性和更改。查看编辑器外部的评论的更新指南，并将其与您当前的集成进行比较。

值得注意的更改包括但不限于

• 处理新的CommentsRepository事件：resolveCommentThread和reopenCommentThread。
• CommentsRepository#openNewCommentThread()调用中的新context和isResolvable参数。

目前，对于编辑器外部的评论，已解决的评论线程不会显示在存档面板中。