更新至 CKEditor 5 v29.x

更新 CKEditor 5 安装时，请确保 **所有软件包的版本一致**，以避免错误。

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

# 更新至 CKEditor 5 v29.1.0

发布于 2021 年 8 月 4 日。

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

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

# 匹配器模式 API 更改

从 v29.1.0 开始，Matcher 功能弃用使用 attributes 键值对模式匹配 style 和 class HTML 属性。

Matcher 功能允许使用专用 styles 和 classes 模式匹配样式和类。从 v29.0.0 开始，还可以使用值为 true 的布尔类型来匹配这些属性的每个可能的值。为了避免对使用哪个模式来匹配类和样式感到困惑，我们决定弃用使用 attributes 模式匹配类和样式。

以下是如何更改代码以正确集成 Matcher 功能的新 API 的示例。

// Old code.
new Matcher( {
    name: 'a',
    attributes: {
        'data-custom-attribute-1': /.*/,
        'data-custom-attribute-2': /.*/,
        style: true,
        class: true
    }
} );

// New code.
new Matcher( {
    name: 'a',
    attributes: {
        'data-custom-attribute-1': /.*/,
        'data-custom-attribute-2': /.*/
    },
    styles: true,
    classes: true
} );

# 链接装饰器 API 更改

匹配器模式 API 更改还改进了如何定义链接装饰器（手动装饰器和自动装饰器）。与 Matcher 功能 API 类似，您应该使用 classes 和 styles 属性来定义 style 和 class HTML 属性。

以下是如何更改代码以正确集成链接装饰器 API 更改的示例。

// Old code.
ClassicEditor
    .create( ..., {
        // ...
        link: {
            decorators: {
                addGreenLink: {
                    mode: 'automatic',
                    attributes: {
                        class: 'my-green-link',
                        style: 'color:green;'
                    }
                }
            }
        }
    } )
// New code.
ClassicEditor
    .create( ..., {
        // ...
        link: {
            decorators: {
                addGreenLink: {
                    mode: 'automatic',
                    classes: 'my-green-link',
                    styles: {
                        color: 'green'
                    }
                }
            }
        }
    } )

# 更新至 CKEditor 5 v29.0.0

发布于 2021 年 7 月 7 日。

本迁移指南列出了升级到 CKEditor 5 v29.0.0 时需要您注意的最重要更改，因为这些更改是在 Image 插件和其他一些与图像相关的功能中引入的。

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

要了解图像功能的新编辑器 UI，请访问图像功能指南，特别是

# 内联图像

从 v29.0.0 开始，现有的 Image 插件会加载两个独立的插件：ImageInline 和 ImageBlock，因此默认情况下，它们都包含在所有预定义编辑器版本中。

ImageInline 是一个新引入的插件，它支持嵌套在文本中的内联 <img> 标签（例如，在段落中）。
ImageBlock 保留了 v29.0.0 之前先前 Image 插件的功能。在模型中，它使用 imageBlock 元素（在 v29.0.0 之前称为 image）。

注意：只有在从源代码构建编辑器时，才能仅加载其中一个插件。

# 图像标题

选择图像小部件时，不再自动显示图像标题。现在，您可以使用由 ToggleImageCaptionCommand 执行的 'toggleImageCaption' 工具栏按钮切换其可见性，两者均由 ImageCaption 插件注册。该按钮已添加到所有预定义编辑器版本的默认图像工具栏中。

为了提供有效的 data 输出，您只能将标题添加到块图像中。将标题添加到内联图像将自动将其转换为块图像（用户可以撤消此操作）。

# 图像样式

由于文档中图像的外观取决于图像类型（块/内联），因此 ImageStyle 插件现在负责在这些类型之间切换。因此，我们引入了以下更改。

一组新的按钮可用于管理图像类型和外观。
您可以将 ImageStyle 插件提供的按钮分组到下拉菜单中。
- 提供了几个默认下拉菜单。
- 在编辑器配置中，您可以声明一个自定义下拉菜单。
默认块图像样式的名称已从 full 更改为 block（因为内联图像的默认样式称为 inline），这些图像的默认内容样式保持不变。按钮标签也已更改，现在显示为 居中图像，以反映图像的实际外观。如果您自定义了块图像的默认外观，则可以通过修改现有图像样式来更改按钮标签。

config.image.styles 的格式已更改。您必须使用 options 数组包装样式列表。详细了解 image.styles 配置。

// Before v29.0.0.
Editor.create( document.querySelector( '#editor' ), {
    ...
    image: {
        styles: [ 'inline', 'full', 'side' ]
    }
} );

// Since v29.0.0.
Editor.create( document.querySelector( '#editor' ), {
    ...
    image: {
        styles: {
            options: [ 'inline', 'block', 'side' ]
        }
    }
} );

imageStyle 的格式已更改。它现在必须提供有关支持特定样式的图像类型的信息。详细了解 ImageStyleOptionDefinition。

// Before v29.0.0.
Editor.create( document.querySelector( '#editor' ), {
    ...
    image: {
        styles: [ {
            name: 'alignLeft',
            title: 'Left aligned image',
            icon: objectLeft,
            className: 'image-style-align-left'
        } ]
    }
} );

// Since v29.0.0.
Editor.create( document.querySelector( '#editor' ), {
    ...
    image: {
        styles: {
            options: [ {
                name: 'alignLeft',
                title: 'Left aligned image',
                icon: objectLeft,
                // Image types (names of the model elements) supporting this style.
                modelElements: [ 'imageBlock', 'imageInline' ],
                className: 'image-style-align-left'
            } ]
        }
    }
} );

还对 ImageStyle 插件 API 做了一些更改。
- 在图像样式实用程序模块中
  - defaultIcons 已重命名为 DEFAULT_ICONS。
  - defaultStyles 已重命名为 DEFAULT_OPTIONS。
  - normalizeImageStyles() 函数已从公共 API 中删除。
- ImageStyleCommand#defaultStyle 和 ImageStyleCommand#styles 已从公共 API 中删除。

在 v29.0.0 之前，没有 ImageStyle 和 ImageToolbar 插件的自定义编辑器版本是可能的。仅支持块图像，并且用户在选择图像时会添加标题。

从 v29.0.0 开始，图像样式和工具栏允许用户选择图像类型（内联或块），并通过可配置按钮提供添加或删除块图像标题的方法。

如果缺少任何一个功能，用户体验将下降，这使得图像工具栏配置变得至关重要。

预配置编辑器版本默认附带 ImageStyle 和 ImageToolbar 插件（以及配置）。此信息主要针对在集成中使用自定义编辑器版本的开发人员。

我们推荐以下配置之一作为图像工具栏的最小设置。

用于结构化内容编辑（默认情况下在经典、气球、气球块和内联编辑器版本中实现）。

Editor.create( document.querySelector( '#editor' ), {
    ...
    image: {
        toolbar: [
            'imageStyle:inline',
            'imageStyle:block',
            'imageStyle:side',
            '|',
            'toggleImageCaption',
            'imageTextAlternative'
        ]
    }
} );

用于文档式编辑（默认情况下在解耦文档版本中实现）。

Editor.create( document.querySelector( '#editor' ), {
    ...
    image: {
        toolbar: [
            'toggleImageCaption',
            'imageStyle:inline',
            // A dropdown containing `alignLeft` and `alignRight` options.
            'imageStyle:wrapText',
            // A dropdown containing `alignBlockLeft`, `block` (default) and  `alignBlockRight` options.
            'imageStyle:breakText'
        ]
    }
} );

请参阅图像功能指南，详细了解图像工具栏的配置。

# 插入图像

从 v29.0.0 版本开始，在文本中间插入（包括粘贴、拖放）图像将不再拆分文本，前提是 ImageInline 插件已加载（默认）。如果您在集成中更喜欢旧的行为，可以在 ImageInsert 插件配置中指定。

# 图像工具

图像工具现在由 ImageUtils 插件包装。

// Before v29.0.0.
import { isImage } from './utils';

const selectedElement = editor.model.document.selection.getSelectedElement();

if ( isImage( selectedElement ) ) {
    // ...
}

// Since v29.0.0.
// ...
const imageUtils = this.editor.plugins.get( 'ImageUtils' );
const selectedElement = editor.model.document.selection.getSelectedElement();

if ( imageUtils.isImage( selectedElement ) ) {
    // ...
}

The insertImage() 函数

不再需要 model 模型实例来运行。
允许 Selectable 作为第二个参数（之前只接受 Position）。
支持可选的 imageType 参数来强制插入图像的类型。

// Before v29.0.0.
import { insertImage } from './utils';

const src = 'path/to/image.jpg';
const model = ths.editor.model;
const selection = model.document.selection;
const position = model.createPositionAt( selection.getSelectedElement() );

insertImage( model, { src }, position );

// Since v29.0.0.
const src = 'path/to/image.jpg';
const selection = this.editor.model.document.selection;
const imageUtils = this.editor.plugins.get( 'ImageUtils' );
const imageType = 'imageBlock';

imageUtils.insertImage( { src }, selection, imageType );

The isImage() 函数识别内联图像和块图像（之前只识别块图像）。
有两个新的助手：isBlockImageView() 和 isInlineImageView().

我们从公共 API 中删除了以下助手

getSelectedImageWidget(),
getViewImgFromWidget(),
isImageAllowed(),
isImageWidget(),
toImageWidget()

# `EasyImage` 插件

The EasyImage 插件不再自动导入 Image 插件作为依赖项。这允许单独使用它，与 ImageBlock 或 ImageInline 结合使用，而无需加载另一个插件。

这种解耦对基于预定义构建或使用 CKEditor 5 Builder 的集成没有影响。

但是，对于从源代码构建编辑器的集成 build the editor from source，这意味着要使 Easy Image 正确工作，必须单独导入 Image 插件（或 ImageBlock 或 ImageInline 插件）。

import EasyImage from '@ckeditor/ckeditor5-easy-image/src/easyimage';
import Image from '@ckeditor/ckeditor5-image/src/image';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ EasyImage, Image, ... ],
        toolbar: [ 'uploadImage', ... ],

        // ...
    } )
    .then( ... )
    .catch( ... );

查看 CKEditor 5 中有关图像的全面安装指南，了解更多信息。

# `CKFinder` 插件

The CKFinder 插件不再自动导入 Image 插件作为依赖项。这允许单独使用它，与 ImageBlock 或 ImageInline 结合使用，而无需加载另一个插件。

这种解耦对基于预定义构建或使用 CKEditor 5 Builder 的集成没有影响。

但是，对于从源代码构建编辑器的集成 build the editor from source，这意味着要使 CKFinder 正确工作，必须单独导入 Image 插件（或 ImageBlock 或 ImageInline 插件）。

import CKFinder from '@ckeditor/ckeditor5-ckfinder/src/ckfider';
import Image from '@ckeditor/ckeditor5-image/src/image';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ CKFinder, Image, ... ],
        toolbar: [ 'uploadImage', ... ],
        ckfinder: {
            // Feature configuration.
        }
    } )
    .then( ... )
    .catch( ... );

查看 CKEditor 5 中有关图像的全面安装指南，了解更多信息。

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

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

更新至 CKEditor 5 v29.x

# 更新至 CKEditor 5 v29.1.0

# 匹配器模式 API 更改

# 链接装饰器 API 更改

# 更新至 CKEditor 5 v29.0.0

# 内联图像

# 图像标题

# 图像样式

# 图像工具栏

# 插入图像

# 图像工具

# EasyImage 插件

# CKFinder 插件

# `EasyImage` 插件

# `CKFinder` 插件