迁移到新的安装方法

在本指南中，我们将探讨 CKEditor 5 v42.0.0 中引入的新的安装方法。这些方法通过减少可能的安装路径数量并消除旧方法的大多数限制，使 CKEditor 5 的使用变得更加容易。迁移到特定安装方法的迁移指南的链接可以在左侧的目录中找到或在移动设备上左上角的主菜单按钮下以及本文档的末尾。

让我们首先将新的安装方法与旧方法进行比较，以更好地了解发生了哪些变化。

# 旧版安装方法

在 42.0.0 版之前，安装 CKEditor 5 的方法有很多，每种方法都有自己的限制和怪癖，使其在某些情况下难以或无法使用。我们也很难在不使文档过于复杂的情况下正确记录所有可能的设置，因为这些设置彼此之间差异很大。

以下是一个代码示例，展示了使用旧版安装方法的可能设置之一

// webpack.config.js
const path = require( 'path' );
const { CKEditorTranslationsPlugin } = require( '@ckeditor/ckeditor5-dev-translations' );
const { styles } = require( '@ckeditor/ckeditor5-dev-utils' );

module.exports = {
    entry: './src/index.js',
    output: {
        path: path.resolve( __dirname, 'dist' ),
        filename: 'bundle.js'
    },
    plugins: [
        new CKEditorTranslationsPlugin( {
            language: 'en'
        } )
    ],
    module: {
        rules: [
            {
                test: /ckeditor5-[^/\\]+[/\\]theme[/\\]icons[/\\][^/\\]+\.svg$/,
                use: [ 'raw-loader' ]
            },
            {
                test: /ckeditor5-[^/\\]+[/\\]theme[/\\].+\.css$/,
                use: [
                    {
                        loader: 'style-loader',
                        options: {
                            injectType: 'singletonStyleTag',
                            attributes: {
                                'data-cke': true
                            }
                        }
                    },
                    'css-loader',
                    {
                        loader: 'postcss-loader',
                        options: {
                            postcssOptions: styles.getPostCssConfig( {
                                themeImporter: {
                                    themePath: require.resolve( '@ckeditor/ckeditor5-theme-lark' )
                                },
                                minify: true
                            } )
                        }
                    }
                ]
            }
        ]
    }
};

// src/index.js
import { ClassicEditor } from '@ckeditor/ckeditor5-editor-classic';
import { Essentials } from '@ckeditor/ckeditor5-essentials';
import { Bold, Italic } from '@ckeditor/ckeditor5-basic-styles';
import { Paragraph } from '@ckeditor/ckeditor5-paragraph';
import { Mention } from '@ckeditor/ckeditor5-mention';
import { FormatPainter } from '@ckeditor/ckeditor5-format-painter';
import { SlashCommand } from '@ckeditor/ckeditor5-slash-command';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ Essentials, Bold, Italic, Paragraph, Mention, FormatPainter, SlashCommand ],
        toolbar: [ /* ... */ ],
        licenseKey: '<LICENSE_KEY>',

        // This value must be kept in sync with the language defined in webpack.config.js.
        language: 'en'
    } );

将 webpack 配置显示在旧版安装方法示例中可能看起来很奇怪，但这对于处理翻译、CSS 和 SVG 文件来说是必要的。如果您想使用 TypeScript，此设置可能会更加复杂。

# 新的安装方法

在新的安装方法中，我们将可能的路径数量减少到两种：npm 包和浏览器构建。与以前不同的是，这两种方法不再需要您添加数十个单独的包或 JavaScript 包来启动和运行编辑器。相反，您可以从 ckeditor5 包中导入编辑器和我们所有开源插件，以及从 ckeditor5-premium-features 中导入高级功能。您也不需要担心特定的 webpack 或 Vite 配置，因为新的安装方法旨在开箱即用地与任何现代捆绑程序或 JavaScript 元框架（如 Next.js）一起使用。

# npm 包

如果您使用的是模块捆绑程序（如 Vite 或 webpack）或其中一个流行的 JavaScript 元框架，那么新的 npm 包是安装 CKEditor 5 的推荐方法。

以下是在使用开源和商业功能以及翻译时新的 npm 设置的样子

import { ClassicEditor, Essentials, Bold, Italic, Paragraph, Mention } from 'ckeditor5';
import { FormatPainter, SlashCommand } from 'ckeditor5-premium-features';

import coreTranslations from 'ckeditor5/translations/pl.js';
import premiumFeaturesTranslations from 'ckeditor5-premium-features/translations/pl.js';

import 'ckeditor5/ckeditor5.css';
import 'ckeditor5-premium-features/ckeditor5-premium-features.css';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ Essentials, Bold, Italic, Paragraph, Mention, FormatPainter, SlashCommand ],
        toolbar: [ /* ... */ ],
        licenseKey: '<LICENSE_KEY>',
        translations: [
            coreTranslations,
            premiumFeaturesTranslations
        ]
    } );

# 浏览器构建

如果您不想使用模块捆绑程序构建 JavaScript，浏览器构建是使用 CKEditor 5 的一种好方法。浏览器构建可用作 JavaScript 模块，并可以使用 <script type="module"> 标签直接在浏览器中加载。

以下与上面的相同编辑器设置，但使用浏览器构建

<link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/43.3.0/ckeditor5.css" />
<link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5-premium-features/43.3.0/ckeditor5-premium-features.css" />

<script type="importmap">
{
    "imports": {
        "ckeditor5": "https://cdn.ckeditor.com/ckeditor5/43.3.0/ckeditor5.js",
        "ckeditor5/": "https://cdn.ckeditor.com/ckeditor5/43.3.0/",
        "ckeditor5-premium-features": "https://cdn.ckeditor.com/ckeditor5-premium-features/43.3.0/ckeditor5-premium-features.js",
        "ckeditor5-premium-features/": "https://cdn.ckeditor.com/ckeditor5-premium-features/43.3.0/"
    }
}
</script>

<script type="module">
import { ClassicEditor, Essentials, Bold, Italic, Paragraph, Mention } from 'ckeditor5';
import { FormatPainter, SlashCommand } from 'ckeditor5-premium-features';

import coreTranslations from 'ckeditor5/translations/pl.js';
import premiumFeaturesTranslations from 'ckeditor5-premium-features/translations/pl.js';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ Essentials, Bold, Italic, Paragraph, Mention, FormatPainter, SlashCommand ],
        toolbar: [ /* ... */ ],
        licenseKey: '<LICENSE_KEY>',
        translations: [
            coreTranslations,
            premiumFeaturesTranslations
        ]
    } );
</script>

在某些环境中，您可能无法使用导入映射或 JavaScript 模块。在这种情况下，您可以使用 UMD 构建。这些注册全局变量，您可以在脚本中使用它们。以下与上面的相同设置，但使用 UMD 构建

<!-- Style sheets -->
<link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/43.3.0/ckeditor5.css" />
<link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5-premium-features/43.3.0/ckeditor5-premium-features.css" />

<!-- Scripts -->
<script src="https://cdn.ckeditor.com/ckeditor5/43.3.0/ckeditor5.umd.js"></script>
<script src="https://cdn.ckeditor.com/ckeditor5-premium-features/43.3.0/ckeditor5-premium-features.umd.js"></script>

<!-- Translations -->
<script src="https://cdn.ckeditor.com/ckeditor5/43.3.0/translations/pl.umd.js"></script>
<script src="https://cdn.ckeditor.com/ckeditor5-premium-features/43.3.0/translations/pl.umd.js"></script>

<script>
const { ClassicEditor, Essentials, Bold, Italic, Paragraph, Mention } = CKEDITOR;
const { FormatPainter, SlashCommand } = CKEDITOR_PREMIUM_FEATURES;

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ Essentials, Bold, Italic, Paragraph, Mention, FormatPainter, SlashCommand ],
        toolbar: [ /* ... */ ],
        licenseKey: '<LICENSE_KEY>'
    } );
</script>

# 新增功能？

与旧版安装方法相比，这两个示例中有一些突出的内容

所有内容都只从 ckeditor5 和 ckeditor5-premium-features 包中导入。在浏览器中，这是使用导入映射完成的，它将包名称映射到构建 URL。
CSS 文件从 JavaScript 文件中单独导入，这可以提高性能，并让您可以更轻松地自定义或删除默认的编辑器样式。
翻译被导入为 JavaScript 对象，并传递给编辑器实例，而不是使用依赖于全局状态的副作用导入（import '...'）。
您不再需要维护 CKEditor 5 特定的 webpack 或 Vite 配置，并且可以使用任何现代捆绑程序或 JavaScript 元框架来使用 CKEditor 5。

我们上面介绍的设置是您将项目迁移到新的安装方法时应该追求的目标。

# 功能比较

以下是新的 npm 和 CDN 构建以及旧版安装方法中可用功能的直观比较

安装方法	新方法		旧方法
安装方法	npm	CDN	预定义	自定义	DLL
无需构建步骤	❌	✅	✅	❌	✅
可以与任何现代捆绑程序一起使用	✅	❌	✅	❌	❌
允许添加插件	✅	✅	❌	✅	✅
样式自定义	✅	✅	❌	⚠️ ^[2]	❌
图标自定义	⚠️ ^[1]	⚠️ ^[1]	❌	✅	❌
不依赖于全局状态	✅	✅	❌	❌	❌
提供编辑器和内容专用的样式表	✅	✅	❌	❌	❌
样式表与 JavaScript 分开	✅	✅	❌	⚠️^[3]	❌
可以优化以减少捆绑包大小	✅	❌	❌	✅	✅

[1] 自定义图标的支持计划在未来的版本中推出。有关更多信息，请参阅此GitHub 问题。
[2] 样式自定义通过 webpack 配置部分支持。
[3] CSS 可以使用自定义 webpack 配置与 JavaScript 分开。

# 旧版安装方法的停用和弃用时间线

随着 42.0.0 版的发布，我们决定弃用旧的 CKEditor 5 设置方法。v42.0.0 中引入的新体验远远优于以前。

但是，我们了解到迁移到新的设置，即使很容易，也需要规划和工作分配。我们宁愿不阻止任何人因已弃用的更新路径而无法接收错误修复和改进。因此，我们将根据下面给出的时间表支持所有现有方法。

# 预定义构建和自定义构建的弃用

“webpack-first”的设置方法，或提供预定义的编辑器而没有扩展它们的可能性，将一直支持到2025 年第一季度（3 月）结束。

我们将在该日期停用的内容

将删除预定义构建、超级构建和自定义构建的文档。
不再发布预定义构建包的新版本到 npm。
在此日期之后发布的 npm 包的新版本将不会包含 src 目录。将无法从这些目的地导入文件，因为 dist 将成为主文件夹。
弃用 @ckeditor/ckeditor5-dev-translations 包，因为它将不再需要。
我们将更新我们的环境以针对 ES2022（或更高版本），从而放弃对 webpack 4 的支持。

# DLL 的弃用

这是我们提供的用于在浏览器端动态创建编辑器及其配置的高级设置方法。由于现在我们的浏览器构建中提供了开箱即用的功能，因此此方法也将被弃用。由于 DLL 在复杂的 CMS 中使用，因此此弃用时间线明显更长。

DLL 将一直支持到2025 年底。

我们将在该日期停用的内容

将删除 DLL 的文档。
在此日期之后发布的 npm 包的新版本将不会包含 build 目录。将无法从这些目的地导入文件。

如果您担心上述任何内容，请与我们的支持团队联系或通过GitHub 问题跟踪器通知我们。我们乐意讨论时间线或您可能需要我们支持的潜在情况。

# 从旧版安装方法迁移

要将您的项目迁移到新的安装方法，您可以按照以下说明进行操作。

首先，如果您维护任何 CKEditor 5 自定义插件作为单独的包，无论是在单仓库设置中还是发布到 npm，您都需要迁移它们

迁移自定义插件.

其次，根据您使用的旧版安装方法，继续迁移您的项目。

最后，如果您使用我们的 React、Vue 或 Angular 集成，您也需要更新它们

将 @ckeditor/ckeditor5-react 包更新到 ^8.0.0 版本。请参考包的变更日志，因为在此版本中引入了微小的破坏性更改。
将 @ckeditor/ckeditor5-vue 包更新到 ^6.0.0 版本。
将 @ckeditor/ckeditor5-angular 包更新到 ^8.0.0 版本。

如果您在迁移过程中遇到任何问题，请参考此包含常见错误的 GitHub 问题。如果您的问题未列在那里，请随时在我们的GitHub 存储库中打开一个新问题。

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

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