syncfusion-react-blockeditor

React 中的 Syncfusion React Block Editor

组件概述

Syncfusion React BlockEditorComponent 是一款功能强大的基于块的富文本编辑器，用户可以通过现代化的块架构创建、编辑和设置内容格式。每段内容（段落、标题、列表、表格、代码片段）都是独立且易于管理的块。

核心功能

BlockEditorComponent 提供：

• 基于块的架构 - 内容以独立且可重新排序的块为结构
• 内置块类型 - 段落、标题、列表、表格、代码、提示框、引用、可折叠部分
• 直观的菜单 - 斜杠命令、上下文菜单、行内工具栏
• 拖放功能 - 使用可视化手柄轻松重新排列块
• 内容导出 - 导出为 JSON、HTML 或纯文本
• 无障碍访问 - 符合 WCAG 2.1 标准，支持键盘导航和屏幕阅读器
• 自定义 - 自定义样式、主题、RTL 支持、全球化
• 协作编辑 - 由 Yjs 提供支持的实时多用户编辑，支持用户状态和远程光标、文档版本历史记录和快照管理

文档导航指南

入门指南

📄 阅读： references/getting-started.md

• 安装和 npm 包设置
• 基本组件实现
• CSS 导入和主题配置
• 创建第一个块编辑器
• 使用块设置初始内容

内置块类型

📄 阅读： references/built-in-blocks.md

• 块类型参考（段落、标题、列表、表格、代码、引用、提示框）
• 嵌套块类型（CollapsibleHeading、CollapsibleParagraph）
• 块缩进和 CSS 类样式
• 内容配置和属性

菜单和命令

📄 阅读： references/block-editor-menus.md

• 斜杠命令菜单自定义
• 配置包含表格和链接选项的上下文菜单
• 设置支持转换、代码、链接和颜色的行内工具栏
• 块操作菜单自定义和工具提示
• 菜单事件和筛选

拖放和内容管理

📄 阅读： references/drag-drop-and-content.md

• 拖放式块重新排序（enableDragAndDrop）
• 内容插入和嵌套
• 拖动事件（blockDragStart、blockDragging、blockDropped）
• 以编程方式移动块

提及和标签

📄 阅读： references/mentions-and-labels.md

• 用于 @mention 功能的 users 属性和 UserModel 接口
• 用于标签功能的 labelSettings 属性和 LabelItemModel 接口
• ContentType.Mention / ContentType.Label 行内内容
• IMentionContentSettings / ILabelContentSettings

方法和 API

📄 阅读： references/methods-and-api.md

• 块管理方法（添加、移除、更新、移动）
• 选择和光标控制
• 数据导出/导入（JSON、HTML）
• 内容格式设置和渲染

样式和外观

📄 阅读： references/styling-and-appearance.md

• CSS 主题设置和导入
• 使用 --sf CSS 变量以及 Block Editor CSS 类/ID 自定义主题
• 使用自定义 CSS 类设置块样式
• 排版和格式选项
• 深色模式和响应式设计
• 使用 Syncfusion Theme Studio 创建完全自定义的主题

高级功能

📄 阅读： references/advanced-features.md

• 粘贴清理和内容净化
• 撤销/重做功能
• 键盘快捷键自定义
• 只读模式配置
• XSS 防护和 HTML 净化
• RTL 支持和国际化

协作编辑

📄 阅读： references/collaborative-editing.md

• 快速入门指南：使用 y-websocket 和 WebSocket 服务进行实时协作的 6 步设置
• 设置 Vite React Block Editor、安装 Yjs 依赖项，并在端口 1234 上创建 WebSocket 服务
• 创建 collaboration.ts 配置文件，其中包含共享的 Yjs 文档、适配器和提供程序
• 由 Yjs 提供支持的实时协作编辑（基于 CRDT 的同步与冲突解决）
• 注入 Collaboration 和 VersionHistory 模块
• collaborationSettings 属性（provider、adapter、enableAwareness、versionHistory）
• 选择 Yjs 提供程序（y-websocket、y-webrtc、y-indexeddb、Hocuspocus、Liveblocks、PartyKit）
• 用户状态、远程光标和文本选择覆盖层（enableAwareness）
• 通过 users 和 currentUserId 配置当前用户
• 基于房间的协作，使用基于 URL 哈希的房间管理
• 版本历史：创建、列出、重命名、还原、比较、导出和导入快照
• 通过 IVersionStorage 接口和 IndexedDBVersionStorage 实现自定义快照存储
• 版本历史事件：snapshotCreated、snapshotRestored

无障碍功能

📄 阅读： references/accessibility.md

• 符合 WCAG 2.1 标准
• 键盘导航模式
• 屏幕阅读器支持和 ARIA 属性
• 焦点管理
• 色彩对比度和视觉指示器

快速入门示例

import { BlockEditorComponent } from '@syncfusion/ej2-react-blockeditor';
import { BlockModel, ContentType } from '@syncfusion/ej2-react-blockeditor';
import '@syncfusion/ej2-react-blockeditor/styles/material.css';

function App() {
  // Define initial blocks
  const blocksData: BlockModel[] = [
    {
      id: 'block-1',
      blockType: 'Heading',
      properties: { level: 1 },
      content: [
        {
          contentType: ContentType.Text,
          content: 'Welcome to Block Editor'
        }
      ]
    },
    {
      id: 'block-2',
      blockType: 'Paragraph',
      content: [
        {
          contentType: ContentType.Text,
          content: 'This is your first paragraph. Click the "+" button to add more blocks.'
        }
      ]
    }
  ];

  return (
    <BlockEditorComponent
      id="block-editor"
      blocks={blocksData}
    />
  );
}

export default App;

常见模式

1. 以编程方式添加块

const editorRef = React.useRef<BlockEditorComponent>(null);

const addNewBlock = () => {
  const newBlock: BlockModel = {
    blockType: 'Paragraph',
    content: [
      {
        contentType: ContentType.Text,
        content: 'New paragraph block'
      }
    ]
  };
  
  editorRef.current?.addBlock(newBlock);
};

2. 处理菜单项选择

const commandMenuSettings = {
  itemSelect: (args) => {
    console.log('Selected command:', args.command.label, args.command.id);
    // Handle custom actions based on selected command
  }
};

3. 将内容导出为 JSON

const exportContent = () => {
  const jsonContent = editorRef.current?.getDataAsJson();
  console.log('Exported content:', jsonContent);
};

4. 启用只读模式

<BlockEditorComponent
  id="block-editor"
  blocks={blocksData}
  readOnly={true}
/>

主要属性

⚠️ BlockEditor API 中不存在属性 toolbarSettings、containerCssClass 和 showBlockHandle，不得使用。

属性	类型	描述
id	string	组件的唯一标识符
blocks	BlockModel[]	定义内容的块对象数组
readOnly	boolean	启用只读模式（默认值：false）
width	string | number	编辑器容器的宽度（默认值：'100%'）
height	string | number	编辑器容器的高度
commandMenuSettings	CommandMenuSettingsModel	自定义斜杠命令（/）菜单
contextMenuSettings	ContextMenuSettingsModel	配置右键上下文菜单
inlineToolbarSettings	InlineToolbarSettingsModel	配置文本选中时显示的内联工具栏
blockActionMenuSettings	BlockActionMenuSettingsModel	配置块操作（⋮）菜单
transformSettings	TransformSettingsModel	配置块类型转换菜单
imageBlockSettings	ImageBlockSettingsModel	配置图像上传和渲染
codeBlockSettings	CodeBlockSettingsModel	配置代码块语言
pasteCleanupSettings	PasteCleanupSettingsModel	控制粘贴内容的清理行为
users	UserModel[]	用于 @mention 功能和协作状态的用户列表，包含头像颜色
labelSettings	LabelSettingsModel	标签功能的标签项和触发字符
enableDragAndDrop	boolean	启用/禁用拖放排序（默认值：true）
undoRedoStack	number	撤销/重做历史记录的最大步数
keyConfig	{ [key: string]: string }	自定义键盘快捷键映射
locale	string	本地化语言代码（默认值：'en-US'）
blockChanged	EmitType<BlockChangedEventArgs>	块内容更改时触发
collaborationSettings	CollaborationSettingsModel	配置使用 Yjs 提供程序、状态感知和版本历史的实时协作
currentUserId	string	当前用户的唯一标识符，用于协作和光标识别

常见用例

内容管理系统 - 构建支持块式编辑、自定义块类型和内容导出的 CMS

文档编辑器 - 创建支持协作编辑、格式设置、模板和版本控制的文档编辑器

记事应用 - 实现支持嵌套、标签和搜索功能的个人笔记应用

博客编辑器 - 让博客作者能够使用丰富的格式设置、媒体嵌入和预览功能进行写作

知识库 - 构建包含组织有序的块、搜索和关联引用的内部文档

调查问卷/表单构建器 - 创建支持条件块和响应收集的动态调查问卷

---