CKEditor 生态系统文档
Search
Contribute to this guide
首页/CKEditor 5/入门

guideReact 富文本多根编辑器钩子

npm version

此页面重点介绍在 React 应用程序中使用多根编辑器的用法。如果你想使用其他类型的编辑器，可以在 本指南 中找到更多信息。

自此软件包的 6.2.0 版本起，React 中的多根编辑器得到支持。

与 默认集成 不同，我们准备了基于钩子和新的 React 机制的多根编辑器集成。

# 快速入门

本指南假设你已经拥有一个 React 项目。如果你想创建一个新的项目，可以使用 Vite CLI。它允许你使用模板创建和自定义项目。例如，你可以使用 TypeScript 支持设置项目。

安装 CKEditor 5 WYSIWYG 编辑器软件包用于 React 和 多根编辑器类型。

npm install ckeditor5 @ckeditor/ckeditor5-react

在你的项目中使用 useMultiRootEditor 钩子

// App.jsx / App.tsx

import { MultiRootEditor, Bold, Essentials, Italic, Paragraph } from 'ckeditor5';
import { useMultiRootEditor } from '@ckeditor/ckeditor5-react';

import 'ckeditor5/ckeditor5.css';

const App = () => {
    const editorProps = {
        editor: MultiRootEditor,
        data: {
            intro: '<h1>React multi-root editor</h1>',
            content: '<p>Hello from CKEditor&nbsp;5 multi-root!</p>'
        },
        config: {
            plugins: [ Essentials, Bold, Italic, Paragraph ],
            toolbar: {
                items: [ 'undo', 'redo', '|', 'bold', 'italic' ]
            },
        }
    };

    const {
        editor,
        toolbarElement,
        editableElements,
        data,
        setData,
        attributes,
        setAttributes
    } = useMultiRootEditor( editorProps );

    return (
        <div className="App">
            <h2>Using CKEditor&nbsp;5 multi-root editor in React</h2>

            { toolbarElement }

            { editableElements }
        </div>
    );
}

export default App;

# 钩子属性

useMultiRootEditor 钩子支持以下属性

  • editor: MultiRootEditor (必需) – 要使用的 MultiRootEditor 构造函数。
  • data: Object – 创建的编辑器的初始数据。请参阅 获取和设置数据 指南。
  • rootsAttributes: Object – 创建的编辑器的初始根属性。
  • config: Object – 编辑器配置。请参阅 配置 指南。
  • disabled: Boolean – 如果将此属性设置为 true，则 MultiRootEditor 将切换到只读模式。
  • disableWatchdog: Boolean – 如果设置为 true，则 看门狗功能 将被禁用。默认情况下，它设置为 false。
  • watchdogConfig: WatchdogConfig – 配置对象，用于 看门狗功能。
  • isLayoutReady: Boolean – 当设置为 false 时，延迟编辑器创建的属性。它在设置为 true 时开始多根编辑器的初始化。在使用 CKEditor 5 注释或存在列表时很有用。
  • disableTwoWayDataBinding: Boolean – 允许禁用编辑器状态和 data 对象之间的双向数据绑定机制，以提高编辑器效率。默认值为 false。
  • onReady: Function – 在编辑器准备就绪并带有 MultiRootEditor 实例时调用。如果发生错误，此回调也会在组件重新初始化后调用。
  • onChange: Function – 当编辑器数据发生更改时调用。请参阅 editor.model.document#change:data 事件。
  • onBlur: Function – 当编辑器失去焦点时调用。请参阅 editor.editing.view.document#blur 事件。
  • onFocus: Function – 当编辑器获得焦点时调用。请参阅 editor.editing.view.document#focus 事件。
  • onError: Function – 当编辑器在初始化期间或运行时崩溃时调用。它接收两个参数：错误实例和错误详细信息。
    错误详细信息是一个包含两个属性的对象
    • phase: 'initialization'|'runtime' – 通知错误发生的时间（在编辑器或上下文初始化期间，或初始化之后）。
    • willEditorRestart: Boolean – 如果设置为 true，编辑器组件将重新启动自身。

编辑器事件回调（onChange、onBlur、onFocus）接收两个参数

  1. 一个 EventInfo 对象。
  2. 一个 MultiRootEditor 实例。

# 钩子值

useMultiRootEditor 钩子返回以下值

  • editor – 创建的编辑器实例。
  • toolbarElement – 包含工具栏的 ReactElement。它可以在应用程序中的任何位置呈现。
  • editableElements – 描述编辑器根目录的 ReactElements 数组。在分离现有根目录或添加新根目录后，此数组会更新。
  • data – 编辑器数据的当前状态。在每次编辑器更新后，它都会更新。请注意，如果通过传递 disableTwoWayDataBinding 属性禁用了双向绑定，则不应使用它。
  • setData – 用于更新编辑器数据的函数。
  • attributes – 编辑器属性的当前状态。在每次编辑器属性更新后，它都会更新。请注意，如果通过传递 disableTwoWayDataBinding 属性禁用了双向绑定，则不应使用它。
  • setAttributes – 用于更新编辑器属性的函数。

# 上下文功能

useMultiRootEditor 钩子还支持 上下文功能，如主要 React 集成 指南中所述。

但是，由于多根编辑器解决了上下文功能的大多数用例，请考虑是否需要使用它。

# 双向数据绑定

默认情况下，双向数据绑定已启用。这意味着在编辑器中进行的每一次更改都会自动应用到 useMultiRootEditor 钩子返回的 data 对象中。此外，如果你想更改或设置编辑器中的数据，你可以简单地使用钩子提供的 setData 方法。它在属性方面的工作方式相同——钩子提供 attributes 对象和 setAttributes 方法来更新它们。它确保如果你想使用或保存编辑器的状态，这些对象始终是最新的。

双向数据绑定可能会导致大型编辑器内容出现性能问题。在这种情况下，建议在使用 useMultiRootEditor 钩子时将 disableTwoWayDataBinding 属性设置为 true 来禁用它。当禁用此功能时，如果需要，你需要手动处理数据同步。

实现此目的的推荐方法是基于利用 自动保存插件。第二种方法涉及提供 onChange 回调，该回调在每次编辑器更新时调用。

# 如何？

# 将编辑器与协作插件一起使用

我们提供了一些 现成的集成，它们具有与 React 应用程序中的多根功能的协作编辑功能

不必在上述示例的基础上构建应用程序，但它们应该可以帮助你入门。

# 贡献和报告问题

React 富文本编辑器组件的源代码在 GitHub 上的 https://github.com/ckeditor/ckeditor5-react 中提供。