syncfusion-react-blockeditor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Syncfusion React Block Editor in React

React中的Syncfusion React Block Editor

Component Overview

组件概述

The Syncfusion React BlockEditorComponent is a powerful block-based rich text editor that allows users to create, edit, and format content using a modern block architecture. Each piece of content (paragraphs, headings, lists, tables, code snippets) is a discrete, manageable block.

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

Key Capabilities

核心功能

The BlockEditorComponent provides:

Block-based architecture - Content structured as discrete, reorderable blocks
Built-in block types - Paragraphs, headings, lists, tables, code, callouts, quotes, collapsible sections
Intuitive menus - Slash commands, context menus, inline toolbars
Drag-and-drop - Reorder blocks easily with visual handles
Content export - Export as JSON, HTML, or plain text
Accessibility - WCAG 2.1 compliant with keyboard navigation and screen reader support
Customization - Custom styling, themes, RTL support, globalization

BlockEditorComponent提供以下功能：

基于区块的架构 - 内容以独立、可重新排序的区块形式组织
内置区块类型 - 段落、标题、列表、表格、代码、提示框、引用、可折叠区域
直观菜单 - 斜杠命令、上下文菜单、内联工具栏
拖拽功能 - 通过可视化手柄轻松重新排序区块
内容导出 - 支持导出为JSON、HTML或纯文本格式
无障碍访问 - 符合WCAG 2.1标准，支持键盘导航和屏幕阅读器
自定义配置 - 自定义样式、主题、RTL支持、全球化适配

Documentation Navigation Guide

文档导航指南

Getting Started

快速开始

📄 Read: references/getting-started.md

Installation and npm package setup
Basic component implementation
CSS imports and theme configuration
Creating your first block editor
Setting initial content with blocks

📄 阅读： references/getting-started.md

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

Built-in Block Types

内置区块类型

📄 Read: references/built-in-blocks.md

Block type reference (Paragraph, Heading, List, Table, Code, Quote, Callout)
Nested block types (CollapsibleHeading, CollapsibleParagraph)
Block indentation and CSS class styling
Content configuration and properties

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

区块类型参考（段落、标题、列表、表格、代码、引用、提示框）
嵌套区块类型（可折叠标题、可折叠段落）
区块缩进与CSS类样式
内容配置与属性

Menus and Commands

菜单与命令

📄 Read: references/block-editor-menus.md

Slash command menu customization
Context menu configuration
Inline toolbar setup
Menu events and filtering
Block actions and shortcuts

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

斜杠命令菜单自定义
上下文菜单配置
内联工具栏设置
菜单事件与过滤
区块操作与快捷键

Drag-Drop and Content Management

拖拽与内容管理

📄 Read: references/drag-drop-and-content.md

Drag-and-drop block reordering (
```
enableDragAndDrop
```
)
Content insertion and nesting
Drag events (
```
blockDragStart
```
,
```
blockDragging
```
,
```
blockDropped
```
)
Programmatic block movement

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

拖拽重新排序区块（
```
enableDragAndDrop
```
）
内容插入与嵌套
拖拽事件（
```
blockDragStart
```
,
```
blockDragging
```
,
```
blockDropped
```
）
程序化移动区块

Mentions and Labels

提及与标签

📄 Read: references/mentions-and-labels.md

```
users
```
prop and
```
UserModel
```
interface for
```
@mention
```
feature
```
labelSettings
```
prop and
```
LabelItemModel
```
interface for label feature
```
ContentType.Mention
```
/
```
ContentType.Label
```
inline content

IMentionContentSettings

ILabelContentSettings

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

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

IMentionContentSettings

ILabelContentSettings

Methods and API

方法与API

📄 Read: references/methods-and-api.md

Block management methods (add, remove, update, move)
Selection and cursor control
Data export/import (JSON, HTML)
Content formatting and rendering

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

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

Styling and Appearance

样式与外观

📄 Read: references/styling-and-appearance.md

CSS theming and imports
Block styling with custom CSS classes
Typography and formatting options
Dark mode and responsive design

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

CSS主题与导入
使用自定义CSS类设置区块样式
排版与格式化选项
深色模式与响应式设计

Advanced Features

高级功能

📄 Read: references/advanced-features.md

Paste cleanup and content sanitization
Undo/redo functionality
Keyboard shortcut customization
Read-only mode configuration
XSS protection and HTML sanitization
RTL support and internationalization

📄 阅读： references/advanced-features.md

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

Accessibility

无障碍访问

📄 Read: references/accessibility.md

WCAG 2.1 compliance
Keyboard navigation patterns
Screen reader support and ARIA attributes
Focus management
Color contrast and visual indicators

📄 阅读： references/accessibility.md

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

Quick Start Example

快速入门示例

tsx

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;

tsx

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;

Common Patterns

常见模式

1. Add a Block Programmatically

1. 程序化添加区块

tsx

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);
};

tsx

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. Handle Menu Item Selection

2. 处理菜单项选择

tsx

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

tsx

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

3. Export Content as JSON

3. 将内容导出为JSON

tsx

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

tsx

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

4. Enable Read-Only Mode

4. 启用只读模式

tsx

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

tsx

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

Key Props

核心属性

⚠️ Props
toolbarSettings
,
containerCssClass
, and
showBlockHandle
do not exist in the BlockEditor API and must not be used.

Prop	Type	Description
`id`	`string`	Unique identifier for the component
`blocks`	`BlockModel[]`	Array of block objects defining content
`readOnly`	`boolean`	Enable read-only mode (default: `false` )
`width`	`string \| number`	Width of the editor container (default: `'100%'` )
`height`	`string \| number`	Height of the editor container
`commandMenuSettings`	`CommandMenuSettingsModel`	Customize slash command (/) menu
`contextMenuSettings`	`ContextMenuSettingsModel`	Configure right-click context menu
`inlineToolbarSettings`	`InlineToolbarSettingsModel`	Configure inline text selection toolbar
`blockActionMenuSettings`	`BlockActionMenuSettingsModel`	Configure block action (⋮) menu
`transformSettings`	`TransformSettingsModel`	Configure block type transform menu
`imageBlockSettings`	`ImageBlockSettingsModel`	Configure image upload and rendering
`codeBlockSettings`	`CodeBlockSettingsModel`	Configure code block languages
`pasteCleanupSettings`	`PasteCleanupSettingsModel`	Control paste sanitization behavior
`users`	`UserModel[]`	User list for `@mention` feature
`labelSettings`	`LabelSettingsModel`	Label items and trigger char for label feature
`enableDragAndDrop`	`boolean`	Enable/disable drag-and-drop reordering (default: `true` )
`undoRedoStack`	`number`	Max number of undo/redo history steps
`keyConfig`	`{ [key: string]: string }`	Custom keyboard shortcut mappings
`locale`	`string`	Localization language code (default: `'en-US'` )
`blockChanged`	`EmitType<BlockChangedEventArgs>`	Fires when block content changes

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

属性	类型	描述
`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>`	区块内容变更时触发

Common Use Cases

常见应用场景

Content Management System - Build a CMS with block-based editing, custom block types, and content export

Document Editor - Create a collaborative document editor with formatting, templates, and version control

Note-Taking App - Implement a personal notes app with nesting, tagging, and search capabilities

Blog Editor - Enable blog authors to write with rich formatting, media embeds, and preview

Knowledge Base - Build internal documentation with organized blocks, search, and linked references

Survey/Form Builder - Create dynamic surveys with conditional blocks and response capture

内容管理系统 - 构建具备基于区块的编辑功能、自定义区块类型和内容导出的CMS

文档编辑器 - 创建带有格式化、模板和版本控制的协作式文档编辑器

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

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

知识库 - 构建具备有序区块、搜索和关联引用的内部文档系统

调查问卷/表单构建器 - 创建带有条件区块和响应收集功能的动态调查问卷