在 React 中使用 BlockNote

BlockNote 提供了强大的 React 集成，使得在您的应用中轻松添加丰富的文本编辑功能成为可能。React 绑定提供了声明式 API，能够无缝集成 React 的组件模型和状态管理模式。

关键组件

React 集成主要围绕两个部分：

• useCreateBlockNote - 一个创建和管理编辑器实例的 React Hook
• BlockNoteView - 一个带有完整 UI 的编辑器渲染组件

快速开始

下面是一个在 React 组件中集成 BlockNote 的最简示例：

import React from "react";
import { useCreateBlockNote } from "@blocknote/react";
import { BlockNoteView } from "@blocknote/mantine";
// 或者，你也可以使用 ariakit、shadcn 等。

function MyEditor() {
  const editor = useCreateBlockNote();

  return <BlockNoteView editor={editor} />;
}

这将为您提供一个功能完备的编辑器，具有：

• 文本编辑与格式化
• 块类型（段落、标题、列表等）
• 格式化工具栏
• 用于块操作的侧边菜单

BlockNoteView

<BlockNoteView> 组件用于渲染编辑器。它还提供了许多用于编辑器特定事件的 props。

Props

Hooks

useCreateBlockNote

useCreateBlockNote Hook 用于创建新的 BlockNoteEditor 实例。

declare function useCreateBlockNote(
  options?: BlockNoteEditorOptions,
  deps?: React.DependencyList,
): BlockNoteEditor;

useEditorChange

useEditorChange Hook 用于监听编辑器内容的变化。

declare function useEditorChange(
  callback: (
    editor: BlockNoteEditor,
    ctx: {
      /**
       * 返回发生变化时插入、更新或删除的块。
       */
      getChanges(): BlocksChanged;
    },
  ) => void,
  editor?: BlockNoteEditor,
): BlockNoteEditor;

useEditorSelectionChange

useEditorSelectionChange Hook 用于监听编辑器选择内容的变化。

declare function useEditorSelectionChange(
  /**
   * 编辑器选择变化时调用的回调函数。
   */
  callback: () => void,
  editor?: BlockNoteEditor,
): BlockNoteEditor;

useEditorFocus

useEditorFocus Hook 返回一个布尔值，并在编辑器获得或失去焦点时重新渲染组件。默认情况下，它会跟踪内容区域。传入 includeEditorUI: true 后，当焦点移入编辑器的工具栏、菜单或弹出框时，它仍会保持为 true。

declare function useEditorFocus(
  options?: {
    /**
     * Include focus within the editor's toolbars, menus, and popovers.
     * Defaults to false.
     */
    includeEditorUI?: boolean;
  },
  editor?: BlockNoteEditor,
): boolean;

选项和 editor 参数都是可选的。在 BlockNoteView 内调用时，该 Hook 可以使用上下文中的编辑器。要在焦点变化时运行副作用，请订阅 editor.onFocusChange。

下一步

编辑器现已准备就绪！开始输入，探索工具栏中各种块类型和格式化选项。

在基本编辑器运行后，您可以继续探索：

• 内置块类型 - 了解 BlockNote 编辑器默认支持的内容类型
• 样式与主题 - 自定义编辑器的外观和体验
• 自定义 UI 元素 - 替换默认 UI 组件，真正个性化您的编辑器
• 自定义架构 - 扩展用户可添加到编辑器的内容类型
• 示例 - 浏览由 BlockNote 维护者和社区成员创建的示例库