迁移自定义插件

如果您为 CKEditor 5 创建并发布了自定义插件，则需要调整它们才能使它们与新的安装方法一起使用。迁移过程略有不同，具体取决于您只想支持新的安装方法，还是还要保持与旧安装方法的向后兼容性。

如果您直接在项目中使用自定义插件，并且不是单独的包，则不需要遵循本指南。在这种情况下，您可以与使用它们的项目一起更新插件。

# 先决条件

在开始之前，请按照通常的升级路径更新您的插件以使用最新版本的 CKEditor 5。这将排除由从旧版本 CKEditor 5 升级引起的任何问题。

# 迁移步骤

# 使用包生成器创建新项目

为了确保所有依赖项都是最新的，并且构建过程是正确的，我们建议您执行以下步骤

1. 按照 包生成器指南 使用包生成器创建新项目。
2. 将您的插件的 src、tests 和 sample 文件夹复制到新项目中。
3. 将特定于您的插件的所有外部 dependencies、devDependencies 和 peerDependencies 重新添加到 package.json 文件中。

运行 CLI 时，系统会询问您是要仅支持新的安装方法，还是要提供与旧安装方法的向后兼容性。选择最适合您需求的选项，但请注意，后者会生成您以后需要更新或删除的额外文件和代码。如果您的插件在您无法控制的项目中使用，并且这些项目可能仍在使用旧的安装方法，例如您的插件是开源的，则应考虑使用旧版选项。

您可以在 自定义插件的版本兼容性 指南中详细了解为新的和旧的安装方法编写的代码之间的区别。

我们在新的包生成器中引入的主要更改是

• 使生成的包成为有效的 ECMAScript 模块，
• 更新构建过程以生成用于新的安装方法的捆绑包，
• 添加新的 eslint 规则以避免常见错误，
• 更新依赖项。

# 在导入中添加缺少的文件扩展名

接下来，根据 JavaScript 模块 (ESM) 的要求，您必须在导入期间将 src、tests 和 sample 文件夹中所有文件的缺少文件扩展名添加到所有文件中。

- import { Plugin } from 'ckeditor5/src/core';
+ import { Plugin } from 'ckeditor5/src/core.js';

-import SomePlugin from './src/someplugin';
+import SomePlugin from './src/someplugin.js';

来自包根目录的导入不应更改。

// ✅
import { Plugin } from '@ckeditor/ckeditor5-core';

如果您运行以下命令，ckeditor5-rules/require-file-extensions-in-imports eslint 规则应该可以解决与缺少文件扩展名相关的大多数（如果不是全部）问题。

npm run lint -- --fix

# 从导入路径中删除 src 文件夹

有一段时间了，我们强烈建议不要从 @ckeditor/ckeditor5-* 包的 src 文件夹导入。相反，您应该从包根目录导入，因为它们提供更好的 TypeScript 支持，并且将来会删除 src 文件夹。从 ckeditor5 包的 src 文件夹导入仍然允许（例如 ckeditor5/src/core.js），因为它对于 DLL 构建支持是必需的。

// ❌
import Plugin from '@ckeditor/ckeditor5-core/src/plugin.js';

// ✅
import { Plugin } from '@ckeditor/ckeditor5-core';

// ✅
import { Plugin } from 'ckeditor5/src/core.js';

请注意，src 文件夹和包根目录之间的导出名称可能不同。在上面的示例中，从 @ckeditor/ckeditor5-core/src/plugin.js 导入的命名 Plugin 将在 @ckeditor/ckeditor5-core 和 ckeditor5/src/core.js 中以相同的名称导出，但这不能保证。在名称不匹配的情况下，您需要相应地修改导入。

还可能存在您从 src 文件夹导入的某些内容没有从包根目录导出的情况。在这种情况下，请在 CKEditor 5 存储库 中创建一个新的问题，以便我们可以考虑添加缺少的导出。

如果您运行以下命令，ckeditor5-rules/allow-imports-only-from-main-package-entry-point eslint 规则将列出您需要更新导入的所有位置。

npm run lint

# 从导入路径中删除 theme 文件夹

相同的规则适用于 @ckeditor/ckeditor5-* 包中的 theme 文件夹。如果您需要使用此文件夹中的图标，则可能可以从包根目录导入它们。

// ❌
import undo from '@ckeditor/ckeditor5-core/theme/icons/undo.svg';

console.log( undo );

// ✅
import { icons } from '@ckeditor/ckeditor5-core';

console.log( icons.undo );

如果您运行以下命令，ckeditor5-rules/allow-imports-only-from-main-package-entry-point eslint 规则将列出您需要更新导入的所有位置。

npm run lint

# 将导入更新到 ckeditor5 包

如果您在包生成器 CLI 中选择了仅支持新的安装方法，则需要将所有导入从 ckeditor5/src/* 和 @ckeditor/ckeditor5-* 更新到 ckeditor5。

- import { Plugin } from 'ckeditor5/src/core.js';
- import { ButtonView } from 'ckeditor5/src/ui.js';
+ import { Plugin, ButtonView } from 'ckeditor5';

如果您运行以下命令，ckeditor5-rules/no-legacy-imports eslint 规则将列出您需要更新导入的所有位置。

npm run lint

# 运行 eslint

运行 npm run lint 命令以查看是否有任何剩余的问题需要修复。

# 生成并验证捆绑包

更新所有导入后，是时候构建并验证用于新的安装方法的捆绑包了。

1. 使用以下命令构建插件。它将创建 dist 文件夹，其中包含用于新的安装方法的插件捆绑包。

   npm run prepare
   

2. 检查 dist/index.js 文件顶部的导入。

   • 如果您选择了仅支持新的安装方法，则您应该只看到来自 ckeditor5（而不是来自 ckeditor5/src/*）以及可选的其他外部依赖项的导入。

   • 如果您选择了提供与旧安装方法的向后兼容性，则您应该看到 CKEditor 导入被重写为以 /dist/index.js 结尾。例如，从 ckeditor5/src/core.js 导入的应该被重写为 @ckeditor/ckeditor5-core/dist/index.js。如果您使用过任何外部依赖项，您也可能会看到来自它们的导入，但它们不应被修改。

3. 对 dist/browser/index.js 文件重复上述步骤，但这一次您应该只看到来自 ckeditor5 或 ckeditor5-premium-features 的导入。所有其他导入，包括外部依赖项，都应该与插件捆绑在一起

如果您在第二步或第三步中看到未明确提及的导入，请检查这些导入在源代码中的来源，以及它们是否已根据上述迁移步骤进行了更新。如果是这种情况，并且生成的捆绑包中的导入仍然不正确，请在 CKEditor 5 存储库 中创建一个新的问题。

# 如何在新安装方法中使用您的插件？

您的插件在新安装方法中的使用方式取决于您是否选择了仅支持新的安装方法，还是还要提供与旧安装方法的向后兼容性。

如果您只支持新的安装方法

• 可以从包根目录导入代码。
• 如果您的插件包含样式，则可以使用包名称后跟 /index.css（import '<PLUGIN_NAME>/index.css'）导入它们。
• 如果您的插件提供翻译，则可以使用包名称后跟 /translations/<LANGUAGE>.js（import '<PLUGIN_NAME>/translations/<LANGUAGE>.js'）导入它们。

// Importing the plugin code.
import { /* Plugin code */ } from '<PACKAGE_NAME>';

// Optionally importing the styles.
import '<PACKAGE_NAME/index.css';

// Optionally importing the translations.
import pluginTranslations from '<PACKAGE_NAME>/translations/<LANGUAGE>.js';

如果您决定提供与旧安装方法的向后兼容性，则可以使用包名称后跟 /dist/index.js 导入代码。样式和翻译的导入方式与上面相同。

// Importing the plugin code.
import { /* Plugin code */ } from '<PACKAGE_NAME>/dist/index.js';

// Optionally importing the styles.
import '<PACKAGE_NAME/index.css';

// Optionally importing the translations.
import pluginTranslations from '<PACKAGE_NAME>/translations/<LANGUAGE>.js';

/dist/index.js 路径部分将在将来删除，届时对旧安装方法的支持也将被删除。