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

guide更新至 CKEditor 5 v26.x

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

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

# 更新至 CKEditor 5 v26.0.0

发布日期：2021 年 3 月 3 日。

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

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

# 软性要求

虽然 允许扩展版本，在不重新构建捆绑包的情况下添加额外的插件（这个概念也称为 “DLL”），但我们不得不分离某些插件集。这导致了“软性要求”的引入。

以前，每个插件都有其直接要求，编辑器会在加载插件之前自动加载这些要求。这些插件是在插件类的 static get() {} 回调中以插件构造函数（依赖项）的形式指定的。

从 v26.0.0 版本开始，并非所有插件都可以被其他插件直接导入。但是，插件可以通过从 static get() {} 返回字符串来定义它需要另一个插件（例如，名为 'Foo'）。这告诉编辑器您必须在构建之前（通过 Editor.builtinPlugins）或创建新编辑器实例时（例如，通过 config.plugins）提供此类插件。

因此，在升级到 26.0.0 版本时，您可能会遇到 plugincollection-soft-required 错误。这告诉您现在缺少一些依赖项，您需要提供它们。

# 已知软性要求列表

  • 在使用 CloudServicesUploadAdapter 或 EasyImage 功能时，请将 CloudServices 添加到编辑器插件中。
  • 在使用 EasyImage 功能时，请将 Image 和 ImageUpload 添加到编辑器插件中。
  • 在使用 CKFinder 功能时，请将 CKFinderUploadAdapter、Image 和 Link 功能添加到编辑器插件中。
  • 在使用 Title 功能时，请将 Paragraph 添加到编辑器插件中。
  • 在使用 List 功能时，请将 Paragraph 添加到编辑器插件中。
  • 在使用 LinkImage 功能时，请将 Image 添加到编辑器插件中。
  • 在使用 ExportPdf 或 ExportWord 功能时，请将 CloudServices 添加到编辑器插件中。

# 升级方法

以前，当您通过 config.plugins 将插件直接传递给 Editor.create() 时，您的设置如下

import ClassicEditor from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';
import EssentialsPlugin from '@ckeditor/ckeditor5-essentials/src/essentials';
import UploadAdapterPlugin from '@ckeditor/ckeditor5-adapter-ckfinder/src/uploadadapter';
import AutoformatPlugin from '@ckeditor/ckeditor5-autoformat/src/autoformat';
import BoldPlugin from '@ckeditor/ckeditor5-basic-styles/src/bold';
import ItalicPlugin from '@ckeditor/ckeditor5-basic-styles/src/italic';
import BlockQuotePlugin from '@ckeditor/ckeditor5-block-quote/src/blockquote';
import EasyImagePlugin from '@ckeditor/ckeditor5-easy-image/src/easyimage';
import HeadingPlugin from '@ckeditor/ckeditor5-heading/src/heading';
import ImagePlugin from '@ckeditor/ckeditor5-image/src/image';
import ImageCaptionPlugin from '@ckeditor/ckeditor5-image/src/imagecaption';
import ImageStylePlugin from '@ckeditor/ckeditor5-image/src/imagestyle';
import ImageToolbarPlugin from '@ckeditor/ckeditor5-image/src/imagetoolbar';
import LinkPlugin from '@ckeditor/ckeditor5-link/src/link';
import ListPlugin from '@ckeditor/ckeditor5-list/src/list';
import ParagraphPlugin from '@ckeditor/ckeditor5-paragraph/src/paragraph';

ClassicEditor
    .create( document.querySelector( '#editor'), {
        plugins: [
            EssentialsPlugin,
            AutoformatPlugin,
            BoldPlugin,
            ItalicPlugin,
            BlockQuotePlugin,
            HeadingPlugin,
            ImagePlugin,
            ImageCaptionPlugin,
            ImageStylePlugin,
            ImageToolbarPlugin,
            EasyImagePlugin,
            ImageUploadPlugin,
            LinkPlugin,
            ListPlugin,
            ParagraphPlugin
        ],
        toolbar: [
            'heading',
            'bold',
            'italic',
            'link',
            'bulletedList',
            'numberedList',
            'uploadImage',
            'blockQuote',
            'undo',
            'redo'
        ],
        image: {
            toolbar: [
                'imageStyle:full',
                'imageStyle:side',
                '|',
                'imageTextAlternative'
            ]
        }
    } )
    .then( editor => {
        console.log( editor );
    } )
    .catch( error => {
        console.error( error );
    } );

根据上面的列表（或您升级软件包时抛出的错误），您可以检查是否需要添加

  • ImageUpload，因为您使用的是 EasyImage，
  • CloudServices，因为您使用的是 EasyImage。

升级后，设置应如下所示

import ClassicEditor from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';
import EssentialsPlugin from '@ckeditor/ckeditor5-essentials/src/essentials';
import UploadAdapterPlugin from '@ckeditor/ckeditor5-adapter-ckfinder/src/uploadadapter';
import AutoformatPlugin from '@ckeditor/ckeditor5-autoformat/src/autoformat';
import BoldPlugin from '@ckeditor/ckeditor5-basic-styles/src/bold';
import ItalicPlugin from '@ckeditor/ckeditor5-basic-styles/src/italic';
import BlockQuotePlugin from '@ckeditor/ckeditor5-block-quote/src/blockquote';
import EasyImagePlugin from '@ckeditor/ckeditor5-easy-image/src/easyimage';
import HeadingPlugin from '@ckeditor/ckeditor5-heading/src/heading';
import ImagePlugin from '@ckeditor/ckeditor5-image/src/image';
import ImageCaptionPlugin from '@ckeditor/ckeditor5-image/src/imagecaption';
import ImageStylePlugin from '@ckeditor/ckeditor5-image/src/imagestyle';
import ImageToolbarPlugin from '@ckeditor/ckeditor5-image/src/imagetoolbar';
import LinkPlugin from '@ckeditor/ckeditor5-link/src/link';
import ListPlugin from '@ckeditor/ckeditor5-list/src/list';
import ParagraphPlugin from '@ckeditor/ckeditor5-paragraph/src/paragraph';

// ADDED
import ImageUploadPlugin from '@ckeditor/ckeditor5-image/src/imageupload';
import CloudServicesPlugin from '@ckeditor/ckeditor5-cloud-services/src/cloudservices';

ClassicEditor
    .create( document.querySelector( '#editor'), {
        plugins: [
            EssentialsPlugin,
            AutoformatPlugin,
            BoldPlugin,
            ItalicPlugin,
            BlockQuotePlugin,
            HeadingPlugin,
            ImagePlugin,
            ImageCaptionPlugin,
            ImageStylePlugin,
            ImageToolbarPlugin,
            EasyImagePlugin,
            ImageUploadPlugin,
            LinkPlugin,
            ListPlugin,
            ParagraphPlugin,

            // ADDED
            ImageUploadPlugin,
            CloudServicesPlugin
        ],
        toolbar: [
            'heading',
            'bold',
            'italic',
            'link',
            'bulletedList',
            'numberedList',
            'uploadImage',
            'blockQuote',
            'undo',
            'redo'
        ],
        image: {
            toolbar: [
                'imageStyle:full',
                'imageStyle:side',
                '|',
                'imageTextAlternative'
            ]
        }
    } )
    .then( editor => {
        console.log( editor );
    } )
    .catch( error => {
        console.error( error );
    } );

# macOS 的按键

从 v26.0.0 版本开始，KeystrokeHandler 不再像以前那样在 macOS 上自动绑定到 Ctrl 和 Cmd 键。相反，它会将 Ctrl 键转换为 Cmd 键，只处理此按键。

例如，注册的按键 Ctrl+A 现在在 macOS 上将转换为 Cmd+A。要阻止按键的转换，请使用强制修饰符：Ctrl!+A（注意感叹号）。

# 统一按钮和命令命名约定

按钮和命令的命名约定已过审并统一，以最大限度地保持一致性，并提供符合实际情况的合理规则。

所有按钮都遵循 动词 + 名词（例如，insertTable、selectAll）或 名词（例如，bold、mediaEmbed）约定。

命令比较棘手，因为可能的名称组合比按钮更多。对于命令，正确的名称通常应以 操作 开头，后跟 功能 名称（例如，checkTodoList、insertTable）。

工具栏按钮名称更改（之前 → 之后）

  • imageUpload → uploadImage
  • imageResize → resizeImage
  • imageInsert → insertImage
  • imageResize:* → resizeImage:*

命令名称更改（之前 → 之后）

  • imageInsert → insertImage
  • imageUpload → uploadImage
  • imageResize → resizeImage
  • forwardDelete → deleteForward
  • todoListCheck → checkTodoList

TodoListCheckCommand 模块已移至 CheckTodoListCommand。

ImageInsertCommand 模块已移至 InsertImageCommand。

ImageResizeCommand 模块已移至 ResizeImageCommand。

ImageUploadCommand 模块已移至 UploadImageCommand。

旧名称仍然可用作别名。