解决 CKEditor 5 React 集成自定义构建版本时出现的渲染失败问题

当在 React 应用中集成通过 CKEditor 5 Online Builder 创建的自定义编辑器时，可能会遇到 `TypeError: Cannot read properties of undefined (reading 'create')` 错误，导致编辑器无法正常渲染。本文旨在深入分析此问题，指出其根源在于 CKEditor 5 的 Watchdog 功能与 React 集成组件之间的冲突，并提供通过配置 `watchdogConfig` 属性来有效解决此问题的专业教程。

问题描述

在使用 CKEditor 5 Online Builder 生成自定义编辑器构建版本，并尝试将其集成到 React 18 应用程序中时，开发者可能会发现编辑器未能成功渲染，并在控制台中看到类似 TypeError: Cannot read properties of undefined (reading 'create') 的错误信息。尽管预构建的经典版或气球版 CKEditor 5 能够正常工作，但自定义版本却遇到了初始化障碍。

典型的集成代码示例如下：

import { CKEditor } from '@ckeditor/ckeditor5-react';
import { Editor } from 'ckeditor5-custom-build/build/ckeditor';

const DashboardPage = () => {
  return (
    <div className='card'>
      <div className='card-body'>
        <div className='mx-auto'>
          <CKEditor
            editor={Editor}
            data="<p>Hello from CKEditor 5!</p>"
            onReady={editor => {
              console.log('Editor is ready to use!', editor);
            }}
            onChange={(event, editor) => {
              // const data = editor.getData();
              // console.log({ event, editor, data });
            }}
            onBlur={(event, editor) => {
              console.log('Blur.', editor);
            }}
            onFocus={(event, editor) => {
              console.log('Focus.', editor);
            }}
          />
        </div>
      </div>
    </div>
  );
}

export default DashboardPage;

同时，项目中使用的 CKEditor 5 相关依赖版本可能如下：

"@ckeditor/ckeditor5-build-balloon": "^38.0.1",
"@ckeditor/ckeditor5-react": "^6.0.0",
"ckeditor5-custom-build": "file:./ckeditor5"

问题根源分析

此 TypeError: Cannot read properties of undefined (reading 'create') 错误通常表明 CKEditor 实例在 React 组件内部未能正确初始化。经过深入研究，问题的核心在于 CKEditor 5 的 Watchdog (看门狗) 功能。

CKEditor 5 的 React 集成 (@ckeditor/ckeditor5-react) 已经内置了其自身的 Watchdog 功能，用于监控编辑器的状态并处理潜在的崩溃。然而，当通过 CKEditor 5 Online Builder 创建自定义构建版本时，如果其中也包含了 Watchdog 功能，就会导致两个 Watchdog 实例同时存在，产生冲突。这种冲突会干扰编辑器核心的初始化流程，使得 editor 对象在尝试调用 create 方法时为 undefined，从而抛出上述类型错误。

CKEditor 官方文档对此有明确说明：“如果您想使用 CKEditor 5 Online Builder，请确保未选择 Watchdog 功能。React 集成组件已将 Watchdog 功能集成到核心中。”这进一步证实了冲突是问题的关键。

解决方案

解决此问题的关键是确保 React 集成组件能够正确管理 Watchdog 功能，避免与自定义构建版本中的 Watchdog 产生冲突。最直接且推荐的方法是在使用 CKEditor 组件时，通过 watchdogConfig 属性明确配置 Watchdog 的行为。

乾坤圈新媒体矩阵管家

新媒体账号、门店矩阵智能管理系统

219

查看详情

通过向 组件添加 watchdogConfig 属性，即使自定义构建中包含了 Watchdog 功能，React 集成也能以受控的方式处理它，从而避免初始化冲突。

以下是更新后的代码示例：

import { CKEditor } from '@ckeditor/ckeditor5-react';
import { Editor } from 'ckeditor5-custom-build/build/ckeditor';

const DashboardPage = () => {
  return (
    <div className='card'>
      <div className='card-body'>
        <div className='mx-auto'>
          <CKEditor
            editor={Editor}
            data="<p>Hello from CKEditor 5!</p>"
            // 关键配置：添加 watchdogConfig 属性
            // 它可以是一个空对象 {}，或者根据需要配置 crashNumberLimit 等参数
            watchdogConfig={ { crashNumberLimit: 10 } }
            onReady={editor => {
              console.log('Editor is ready to use!', editor);
            }}
            onChange={(event, editor) => {
              // const data = editor.getData();
              // console.log({ event, editor, data });
            }}
            onBlur={(event, editor) => {
              console.log('Blur.', editor);
            }}
            onFocus={(event, editor) => {
              console.log('Focus.', editor);
            }}
          />
        </div>
      </div>
    </div>
  );
}

export default DashboardPage;

在上述代码中，watchdogConfig={ { crashNumberLimit: 10 } } 明确告知 React 集成组件如何处理 Watchdog。即使自定义构建版本中包含了 Watchdog，此配置也能使其在 React 环境下得到妥善管理，从而解除冲突，使编辑器能够顺利初始化和渲染。如果不需要特定的 Watchdog 行为配置，也可以简单地设置为 watchdogConfig={ {} }。

最佳实践与注意事项

1. Online Builder 配置优化： 最理想的解决方案是在使用 CKEditor 5 Online Builder 生成自定义构建版本时，就不要选择包含 Watchdog 功能。由于 @ckeditor/ckeditor5-react 已经内置了 Watchdog，自定义构建中再包含它是不必要的，并且容易引发冲突。在构建过程中取消勾选 Watchdog 选项，可以从根本上避免此问题。

2. watchdogConfig 的作用： watchdogConfig 属性不仅用于解决冲突，还允许开发者自定义 Watchdog 的行为，例如设置 crashNumberLimit 来限制编辑器在短时间内可以崩溃的次数。这是一个强大的工具，用于提高编辑器的稳定性。

3. 参考官方示例： 在遇到集成问题时，查阅 CKEditor 5 React 官方仓库中的示例代码（例如 demo-react-18/src/EditorDemo.tsx）是非常有帮助的。官方示例通常展示了最新的、经过验证的集成方式，可以作为调试和学习的宝贵资源。

总结

当使用 CKEditor 5 Online Builder 创建的自定义构建版本在 React 应用中渲染失败，并出现 TypeError: Cannot read properties of undefined (reading 'create') 错误时，根本原因通常是 CKEditor 5 的 Watchdog 功能与 React 集成组件的内置 Watchdog 机制发生冲突。通过在 组件上添加并配置 watchdogConfig 属性，可以有效地解决此问题，确保编辑器能够正确初始化。同时，建议在 Online Builder 中构建自定义版本时，避免包含 Watchdog 功能，以实现更简洁、无冲突的集成。

以上就是解决 CKEditor 5 React 集成自定义构建版本时出现的渲染失败问题的详细内容，更多请关注php中文网其它相关文章！