CKEditor 生态系统文档
Search
Contribute to this guide
首页/CKEditor 5/更新

guide更新到 CKEditor 5 v35.x

更新 CKEditor 5 安装时，确保**所有包的版本都相同**，以避免错误。

对于自定义构建，您可以尝试删除package-lock.json或yarn.lock文件（如果适用）并在重新构建编辑器之前重新安装所有包。为了获得最佳效果，请确保您使用最新的包版本。

# 更新到 CKEditor 5 v35.2.0

于 2022 年 10 月 5 日发布。

有关 35.2.0 版本中引入的所有更改的完整列表，请参阅CKEditor 5 v35.2.0 的发行说明。

以下是升级到 CKEditor 5 v35.2.0 时需要您注意的最重要更改。

# 介绍外部评论

在此版本中，我们引入了外部评论和建议。目前，它们由从 Word 导入功能使用。但是，将来其他功能也可能会使用它们。

外部评论和建议会显示其内容、作者姓名和来自外部来源（如 Word 文档）提供的日期。

即使您不打算使用从 Word 导入功能，我们也建议您遵循本迁移指南。如果您将来决定使用外部评论或建议，这将使您的集成做好准备。

# 保存外部评论和建议数据

此信息仅适用于使用**异步**协作功能的集成。

外部评论和建议的外部数据保存在新添加的@external属性中。它是一个包含两个字段的对象：authorName（String）和createdAt（Date）。

评论和建议的其他属性和属性以常规方式使用。authorId属性设置为执行导入的操作员。

外部数据显示在 UI 中，但未经身份验证（因为它来自外部来源）。因此，在保存外部评论和建议时，引入一些安全措施非常重要

  • @external属性应为只读，并且仅在创建评论或建议时才可设置。
  • 如果设置了@external属性，其他评论和建议属性（如content）也应为只读。

此信息仅适用于使用自定义注释视图或模板的集成。

由于外部评论和建议中的数据未经身份验证，因此我们添加了一个标签，告知用户某个项目来自外部来源。

这将更改CommentView模板和SuggestionThreadView模板。标签添加到这些模板的末尾。检查新的模板以查看此更改是否影响您的自定义视图。

# 评论输入编辑器现在按需加载

此信息仅适用于依赖评论输入编辑器的自定义功能。

评论输入编辑器现在按需初始化（首次将评论视图聚焦时），而不是在渲染时初始化。

如果您的自定义功能以某种方式依赖评论输入编辑器，您可能需要更新它。

此信息仅适用于创建自己的 Annotation 实例的自定义功能。

现在，定位编辑器可编辑区域内的标记或 DOM 元素的 Annotation 实例必须手动注册。您需要使用 EditorAnnotations#registerAnnotation() 来执行此操作，以提供注释和编辑器之间的正确焦点跟踪。

// Before:
const annotation = new Annotation( ... );
editor.plugins.get( 'Annotations' ).add( annotation );

// After:
const annotation = new Annotation( ... );
editor.plugins.get( 'EditorAnnotations' ).registerAnnotation( annotation );
editor.plugins.get( 'Annotations' ).add( annotation );

# 图标路径已更改

除了其他更改之外，一些图标已在项目中移动。如果您使用调用这些图标的自定义 UI 元素，请观察这些更改。

  • bold图标已移至@ckeditor/ckeditor5-core包。
  • paragraph图标已移至@ckeditor/ckeditor5-core包。

其余导入路径保持不变（/theme/icons/）。

# 更新到 CKEditor 5 v35.1.0

于 2022 年 8 月 31 日发布。

有关 35.1.0 版本中引入的所有更改的完整列表，请参阅CKEditor 5 v35.1.0 的发行说明。

以下是升级到 CKEditor 5 v35.1.0 时需要您注意的最重要更改。

# 提供 Alt+F10 和 Esc 键之间编辑根和工具栏的辅助导航的 API 的更改

此信息仅适用于从头开始使用 Editor 和 EditorUI 类作为构建块来开发自定义编辑器创建者的集成者。

  • 允许导航的enableToolbarKeyboardFocus()帮助程序已删除。要恢复此功能，请改用 addToolbar 方法。
  • 可编辑元素现在自动添加到 主焦点跟踪器 中。您不应该单独添加它们。

之前:

import { EditorUI } from 'ckeditor5/src/core';

export default class MyEditorUI extends EditorUI {
    // ...

    init() {
        const view = this.view;
        const editableElement = view.editable.element;
        const toolbarViewInstance = this.view.toolbar;

        // ...

        this.setEditableElement( 'editableName', editableElement );

        this.focusTracker.add( editableElement );

        enableToolbarKeyboardFocus( {
            // ...

            toolbar: toolbarViewInstance
        } );

        // ...
    }
}

之后:

import { EditorUI } from 'ckeditor5/src/core';
// Or `import { EditorUI } from 'ckeditor5/src/ui';` if you update to v36.x;

export default class MyEditorUI extends EditorUI {
    // ...

    init() {
        const view = this.view;
        const editableElement = view.editable.element;
        const toolbarViewInstance = this.view.toolbar;

        // ...

        // Note: You should not add the editable element to the focus tracker here.
        // This is handled internally by the EditorUI#setEditableElement() method.
        this.setEditableElement( 'editableName', editableElement );

        // Note: Add the toolbar to enable Alt+F10 navigation.
        // The rest (e.g. the Esc key handling) is handled by the EditorUI#setEditableElement() method.
        this.addToolbar( toolbarViewInstance );

        // ...
    }
}

# 删除 TooltipView 类并更改工具提示系统

此更改不会影响配置核心 UI 组件的工具提示的集成，例如 tooltip。

从 v35.1.0 开始，TooltipView UI 组件已从 ckeditor5-ui 包中删除。相反，基于data-cke-tooltip-* DOM 元素属性的新工具提示 API 可用。

您的集成可能会创建TooltipView的实例，并以类似的方式将它们注入 DOM 中

// ❌ Old tooltip API.
import { TooltipView } from 'ckeditor5/src/ui';

const tooltip = new TooltipView();

tooltip.text = 'Tooltip text';
tooltip.position = 'sw';
tooltip.render();

DOMElementThatNeedsTooltip.appendChild( tooltip.element );

/* ❌ Old tooltip API. */
.dom-element-that-needs-tooltip:hover .ck-tooltip {
    visibility: visible;
    opacity: 1;
}

如果是这种情况，您现在应该使用data-cke-tooltip-*属性，并让编辑器的内置 TooltipManager 处理其余工作

// ✅ New tooltip API.
DOMElementThatNeedsTooltip.dataset.ckeTooltipText = 'Tooltip text';
DOMElementThatNeedsTooltip.dataset.ckeTooltipPosition = 'sw';

您无需担心在 CSS 中显示和隐藏自定义工具提示。TooltipManager将在用户将鼠标移动到或将焦点移至具有data-cke-tooltip-*属性的 DOM 元素时附加工具提示。有关更多信息，请参阅 TooltipManager API。

# UI 中颜色调色板的更改

在此版本中，我们进行了一些更改，以提高 UI 的可访问性和对比度。由于我们了解某些集成可能更喜欢编辑器之前的样式，因此我们准备了一个 CSS 代码段，您可以使用它将其恢复。

为了获得最佳效果，请在主编辑器样式表之后设置下面列出的自定义属性。有关更多信息，请查看 主题定制指南。

:root {
    --ck-color-base-border: 						hsl(0, 0%, 77%);
    --ck-color-base-action: 						hsl(104, 44%, 48%);
    --ck-color-base-active: 						hsl(208, 88%, 52%);
    --ck-color-base-active-focus:					hsl(208, 88%, 47%);
    --ck-color-focus-border-coordinates: 			208, 79%, 51%;
    --ck-color-focus-outer-shadow: 					hsl(207, 89%, 86%);

    --ck-color-button-default-hover-background: 	hsl(0, 0%, 90%);
    --ck-color-button-default-active-background: 	hsl(0, 0%, 85%);
    --ck-color-button-default-active-shadow: 		hsl(0, 0%, 75%);

    --ck-color-button-on-background: 				hsl(0, 0%, 87%);
    --ck-color-button-on-hover-background: 			hsl(0, 0%, 77%);
    --ck-color-button-on-active-background: 		hsl(0, 0%, 73%);
    --ck-color-button-on-active-shadow: 			hsl(0, 0%, 63%);
    --ck-color-button-on-disabled-background: 		hsl(0, 0%, 87%);
    --ck-color-button-on-color:						var(--ck-color-text);

    --ck-color-button-action-hover-background: 		hsl(104, 44%, 43%);
    --ck-color-button-action-active-background: 	hsl(104, 44%, 41%);
    --ck-color-button-action-active-shadow: 		hsl(104, 44%, 36%);

    --ck-color-switch-button-off-background:		hsl(0, 0%, 69%);
    --ck-color-switch-button-off-hover-background:	hsl(0, 0%, 64%);
    --ck-color-switch-button-on-hover-background: 	hsl(104, 44%, 43%);

    --ck-color-input-border: 						hsl(0, 0%, 78%);
    --ck-color-input-disabled-border: 				hsl(0, 0%, 78%);

    --ck-color-list-button-on-background: 			var(--ck-color-base-active);
    --ck-color-list-button-on-background-focus: 	var(--ck-color-base-active-focus);

    --ck-color-toolbar-background: 					var(--ck-color-base-foreground);
}

# 重命名 BalloonPanelView 的属性

BalloonPanelView的静态属性已重命名。

BalloonPanelView.arrowVerticalOffset静态属性现在为arrowHeightOffset，BalloonPanelView.arrowHorizontalOffset现在为arrowSideOffset。

# 更新到 CKEditor 5 v35.0.0

于 2022 年 8 月 3 日发布。

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

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

# 编辑器销毁后，源元素不会自动更新

CKEditor 5 的最新版本更改了编辑器销毁后（调用 `editor.destroy()` 时）源元素的默认行为。以前，源元素会使用来自 `editor.getData()` 的输出进行更新。现在，源元素在编辑器销毁后将变为空，不再更新。

但是，此行为是可配置的。您可以使用 updateSourceElementOnDestroy 配置选项来启用它。

ClassicEditor
    .create( sourceElement, {
        // ...
        updateSourceElementOnDestroy: true
    } );

根据您使用的插件，在配置中启用 updateSourceElementOnDestroy 选项可能会带来一些安全隐患。虽然编辑视图是安全的，但数据输出中可能存在一些不安全的内容，因此仅当您知道自己在做什么时才启用此选项。在使用 Markdown、通用 HTML 支持和 HTML 嵌入功能时要格外小心。

由于持续的无障碍改进，下拉菜单 UI 组件 的默认行为已更改。从现在开始，默认情况下，在从下拉菜单中选择一个选项后（无论是通过鼠标还是键盘），焦点将自动移到下拉按钮上。

在焦点应该移回编辑区域的场景中，需要覆盖下拉菜单组件的此默认行为。“标题”下拉菜单就是这种情况。选择其中一个选项应该会导致焦点返回到编辑区域，而不是按钮。

您可以通过在下拉菜单的 execute 事件 上使用侦听器来自定义此行为，例如：

// Option 1.
// If the `execute` event is delegated to the dropdown, one listener can handle both:
// executing the command (assuming the dropdown executes it) and focusing the editor editing view.
dropdownView.on( 'execute', () => {
    editor.execute( 'myCommand' );
    editor.editing.view.focus();
} );

// Option 2.
// Otherwise, a dedicated listener may need to be added.
buttonInsideADropdown.on( 'execute', () => {
    editor.execute( 'myCommand' );
} );

dropdownView.on( 'execute', () => {
    editor.editing.view.focus();
} );

# GitHub 上现在有 TypeScript 代码（以及它如何影响您的构建）

从 v35.0.0 开始，第一个 CKEditor 5 包（即：@ckeditor/ckeditor5-utils）是在 TypeScript 中开发的。这是迁移到 TypeScript 的第一步。

# 它会影响谁

它只会在您直接从 Git 存储库（GitHub）中使用 源代码 时影响您。如果您通过任何其他渠道（npm、CDN、ZIP 等）使用它，此更改对您来说是透明的，因为我们只发布了 JavaScript 代码。

# 它将如何影响您

例如，如果您碰巧拥有一个自定义的 CKEditor 5 构建，该构建从 Git 存储库安装其依赖项，则需要更新您的 webpack 配置以支持 TypeScript 代码。

您可以在此提交 中找到如何更改配置的灵感（此提交在我们构建中进行了讨论的更改）。