CKEditor 5 自定义构建在React应用中渲染失败的调试与解决

本文旨在解决ckeditor 5在线构建器自定义版本在react应用中集成时遇到的`typeerror: cannot read properties of undefined (reading 'create')`错误。该问题通常源于`watchdog`功能冲突，因为react集成包已内置此功能。解决方案是通过`watchdogconfig`属性配置或禁用`watchdog`，确保编辑器正确渲染。

在使用CKEditor 5构建富文本编辑器时，尤其是在React环境中集成通过在线构建器（Online Builder）生成的自定义版本时，开发者可能会遇到编辑器无法正常渲染并抛出TypeError: Cannot read properties of undefined (reading 'create')的错误。尽管CKEditor 5的预构建版本（如classic或balloon）能够顺利运行，但自定义构建版本却可能出现此问题。本文将深入分析此错误的原因并提供详细的解决方案。

错误现象与初步排查

当集成自定义构建的CKEditor 5到React组件中时，控制台可能会出现类似如下的错误信息：

ckeditor.tsx:156  TypeError: Cannot read properties of undefined (reading 'create')
    at to._createEditor (ckeditor.tsx:169:1)
    at Vr._creator (ckeditor.tsx:133:1)
    at editorwatchdog.js:115:1
    at async to._initializeEditor (ckeditor.tsx:151:1)
    at async to.componentDidMount (ckeditor.tsx:102:1)

此错误通常发生在编辑器初始化阶段，表明Editor对象（或其内部的某个关键方法）在被调用时为undefined，导致无法执行create操作。这暗示了编辑器核心模块的加载或初始化存在问题。

初步排查发现，项目结构和代码导入方式似乎正确，例如：

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

const MyEditorComponent = () => {
  return (
    <CKEditor
      editor={Editor}
      data="<p>Hello from CKEditor 5!</p>"
      onReady={editor => {
        console.log('Editor is ready to use!', editor);
      }}
      // ... 其他事件处理
    />
  );
};

并且package.json中的依赖也显示了正确的版本：

"@ckeditor/ckeditor5-build-balloon": "^38.0.1",
"@ckeditor/ckeditor5-react": "^6.0.0",
"ckeditor5-custom-build": "file:./ckeditor5", // 指向本地自定义构建

根本原因分析：Watchdog 功能冲突

问题的核心在于CKEditor 5的watchdog（看门狗）功能与@ckeditor/ckeditor5-react集成包之间的潜在冲突。

根据CKEditor 5的官方文档说明：

瞬映

AI 快速创作数字人视频，一站式视频创作平台，让视频创作更简单。

57

查看详情

"If you want to use the CKEditor 5 online builder, make sure that the watchdog feature is not selected. The React integration comes with the watchdog feature already integrated into the core."

这意味着：

1. @ckeditor/ckeditor5-react 包已内置 Watchdog 功能：React集成库为了提高编辑器的稳定性，已经在其核心中集成了watchdog功能。这个功能负责监控编辑器的状态，并在出现崩溃时尝试自动恢复。
2. 在线构建器可能默认包含 Watchdog：当您通过CKEditor 5在线构建器创建自定义版本时，watchdog功能可能被默认选中并包含在您的自定义构建中。
3. 冲突导致初始化失败：当React集成包尝试初始化一个已经包含watchdog功能的自定义编辑器实例时，可能会因为重复或冲突的watchdog逻辑导致编辑器核心的create方法无法被正确访问或执行，从而抛出TypeError。

解决方案

解决此问题主要有两种方法，推荐第二种（重新构建编辑器）。

方法一：在React组件中配置 watchdogConfig (快速验证)

您可以通过在<CKEditor>组件上添加watchdogConfig属性来显式地配置或调整watchdog的行为，以避免冲突。

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 属性
            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 } } 这是一个示例配置，它允许您控制watchdog在编辑器崩溃多少次后停止尝试恢复。通过提供这个配置，即使自定义构建中包含了watchdog，React集成包也能更好地协调其行为，从而避免初始化冲突。

方法二：从CKEditor 5在线构建器中排除 Watchdog 功能 (推荐)

最根本且推荐的解决方案是确保您的自定义构建本身不包含watchdog功能，因为React集成包已经处理了这一点。

1. 访问CKEditor 5在线构建器：前往 CKEditor 5 Online Builder。
2. 配置构建：在选择所需的插件和功能时，务必取消勾选或确保未选择 "Watchdog" 功能。
3. 重新下载并替换：完成配置后，下载新的自定义构建包。将其解压并替换您项目中现有的ckeditor5-custom-build文件夹。
4. 移除 watchdogConfig (如果已添加)：如果之前为了测试而添加了watchdogConfig属性，现在可以将其从<CKEditor>组件中移除，因为编辑器本身不再包含重复的watchdog逻辑。

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
            onReady={editor => {
              console.log('Editor is ready to use!', editor);
            }}
            // ... 其他事件处理
          />
        </div>
      </div>
    </div>
  );
};

export default DashboardPage;

注意事项与最佳实践

• 查阅官方文档：在集成任何复杂库时，始终优先查阅其官方文档。CKEditor 5的文档非常详尽，是解决问题的最佳资源。
• 理解集成包的作用：@ckeditor/ckeditor5-react不仅仅是一个简单的包装器，它还处理了编辑器的生命周期管理、事件绑定以及错误恢复等逻辑。理解这一点有助于避免不必要的配置冲突。
• 版本兼容性：确保@ckeditor/ckeditor5-react包与您的自定义CKEditor 5构建版本兼容。通常，保持它们在相近的主版本号范围内是安全的。
• 清除缓存：在替换自定义构建文件后，有时需要清除浏览器缓存或重启开发服务器，以确保加载的是最新版本的编辑器代码。

总结

当CKEditor 5自定义构建在React应用中遇到TypeError: Cannot read properties of undefined (reading 'create')错误时，根本原因往往是watchdog功能在自定义构建和@ckeditor/ckeditor5-react集成包之间产生了冲突。通过在React组件中配置watchdogConfig属性，或更推荐地，在CKEditor 5在线构建器中排除watchdog功能，可以有效解决此问题，确保编辑器在React应用中顺利渲染和运行。遵循官方指导并理解集成机制是实现无缝集成的关键。

以上就是CKEditor 5 自定义构建在React应用中渲染失败的调试与解决的详细内容，更多请关注php中文网其它相关文章！