syncfusion-blazor-blockeditor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Syncfusion Blazor Block Editor

Component Overview

组件概述

The Syncfusion Blazor Block Editor is a powerful, modular content creation component that enables users to build rich, structured documents using customizable blocks. Each block represents a specific content type—headings, paragraphs, lists, tables, images, code blocks, and more—providing a clean, organized editing experience.

Syncfusion Blazor Block Editor是一款功能强大的模块化内容创作组件，允许用户通过可自定义的区块来创建丰富的结构化文档。每个区块代表一种特定的内容类型——标题、段落、列表、表格、图片、代码块等——提供整洁、有序的编辑体验。

Key Features

核心特性

Block-Based Architecture: Create structured content using distinct block types (heading, paragraph, list, table, image, code, quote, callout, divider, toggle)
Intuitive Menus: Slash command menu (
```
/
```
), context menu (right-click), block action menu (hover), and inline toolbar (text selection)
Drag-and-Drop Reordering: Rearrange blocks intuitively by dragging
Undo/Redo Support: Full history management with configurable stack depth
Keyboard Shortcuts: Comprehensive shortcuts for formatting, block creation, and editor operations
Paste Cleanup: Advanced HTML sanitization, style filtering, and tag removal for safe content pasting
Event System: Created, BlockChanged, SelectionChanged, Focus, Blur, and paste lifecycle events
Responsive Design: Adaptive to different screen sizes and viewports
Read-Only Mode: Display-only content without editing capabilities
Custom Styling: CSS class customization and theme integration

基于区块的架构：使用不同的区块类型（标题、段落、列表、表格、图片、代码、引用、提示框、分隔线、折叠块）创建结构化内容
直观菜单：斜杠命令菜单（
```
/
```
）、右键上下文菜单、悬停区块操作菜单、文本选择内嵌工具栏
拖放重排：通过拖拽直观地重新排列区块
撤销/重做支持：具备可配置栈深度的完整历史记录管理
键盘快捷键：用于格式设置、区块创建和编辑器操作的全面快捷键
粘贴清理：高级HTML清理、样式过滤和标签移除功能，确保安全粘贴内容
事件系统：Created、BlockChanged、SelectionChanged、Focus、Blur及粘贴生命周期事件
响应式设计：适配不同屏幕尺寸和视口
只读模式：仅显示内容，不允许编辑
自定义样式：CSS类自定义和主题集成

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

Installation via NuGet (Visual Studio, VS Code, .NET CLI)
Blazor Web App project setup
Service registration and configuration
Import namespaces and add theme resources
Render modes (Server, WebAssembly, Auto)
Basic component initialization
Block configuration and data binding

📄 阅读： references/getting-started.md

通过NuGet安装（Visual Studio、VS Code、.NET CLI）
Blazor Web App项目设置
服务注册与配置
导入命名空间并添加主题资源
渲染模式（Server、WebAssembly、Auto）
基础组件初始化
区块配置与数据绑定

Appearance and Styling

外观与样式

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

Set component width and height
Read-only mode configuration
Custom CSS class application
Responsive design patterns
Theme customization and styling approaches
Style examples and best practices

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

设置组件宽度和高度
只读模式配置
自定义CSS类应用
响应式设计模式
主题自定义与样式方法
样式示例与最佳实践

Editor Menus

编辑器菜单

📄 Read: references/editor-menus.md

Slash command menu (built-in items, customization, events)
Context menu (right-click actions, customization, events)
Block action menu (drag handle actions, customization, events)
Inline toolbar (text formatting options, customization, events)
Menu event handling and filtering
Custom command and menu item creation

📄 阅读： references/editor-menus.md

斜杠命令菜单（内置项、自定义、事件）
上下文菜单（右键操作、自定义、事件）
区块操作菜单（拖拽手柄操作、自定义、事件）
内嵌工具栏（文本格式选项、自定义、事件）
菜单事件处理与过滤
自定义命令和菜单项创建

Built-In Blocks

内置区块

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

Heading blocks (levels 1-4)
Paragraph blocks
List types (bullet, numbered, checklist)
Table blocks
Code blocks
Image/media blocks
Quote and callout blocks
Toggle (collapsible) blocks
Divider blocks
Block nesting and hierarchy

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

标题区块（1-4级）
段落区块
列表类型（项目符号、编号、复选框）
表格区块
代码区块
图片/媒体区块
引用和提示框区块
折叠（可展开/收起）区块
分隔线区块
区块嵌套与层级

Drag-Drop and Undo-Redo

拖放与撤销/重做

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

Enable/disable drag-and-drop
Single and multiple block dragging
Undo/redo keyboard shortcuts
Configure undo/redo stack depth
History management and state tracking
Drag operation visual feedback

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

启用/禁用拖放
单个和多个区块拖拽
撤销/重做键盘快捷键
配置撤销/重做栈深度
历史记录管理与状态跟踪
拖拽操作视觉反馈

Events and Interactions

事件与交互

📄 Read: references/events-and-interactions.md

Created event (initialization)
BlockChanged event (structural changes)
SelectionChanged event (text selection)
Focus and Blur events (editor state)
Keyboard shortcuts (content editing, block creation, block management, general operations)
Custom keyboard shortcut configuration (KeyConfig)
Event handler patterns and examples

📄 阅读： references/events-and-interactions.md

Created事件（初始化）
BlockChanged事件（结构变更）
SelectionChanged事件（文本选择）
Focus和Blur事件（编辑器状态）
键盘快捷键（内容编辑、区块创建、区块管理、常规操作）
自定义键盘快捷键配置（KeyConfig）
事件处理程序模式与示例

Content Handling

内容处理

📄 Read: references/content-handling.md

Getting and setting block content
Content model structure (BlockModel, ContentModel)
Paste cleanup configuration (AllowedStyles, DeniedTags, KeepFormat, PlainText)
PasteCleanupStarting and PasteCleanupCompleted events
Security best practices (XSS prevention)
Content validation patterns

📄 阅读： references/content-handling.md

获取和设置区块内容
内容模型结构（BlockModel、ContentModel）
粘贴清理配置（AllowedStyles、DeniedTags、KeepFormat、PlainText）
PasteCleanupStarting和PasteCleanupCompleted事件
安全最佳实践（XSS防护）
内容验证模式

Labels and Mentions

标签与提及

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

UserModel for mentioning users (@mentions)
LabelItemModel for tagging content (#labels)
BlockEditorLabel component configuration
MentionContentSettings and LabelContentSettings
Implementing collaborative mentions and labels
Practical workflow examples and patterns

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

用于提及用户的UserModel（@提及）
用于内容标记的LabelItemModel（#标签）
BlockEditorLabel组件配置
MentionContentSettings和LabelContentSettings
实现协作式提及和标签
实用工作流示例与模式

Advanced Methods

高级方法

📄 Read: references/advanced-methods.md

GetSelectedBlocksAsync() - Retrieve selected blocks
SelectAllBlocksAsync() - Select all blocks programmatically
FocusInAsync() / FocusOutAsync() - Manage editor focus
PrintAsync() - Print editor content
EnableToolbarItemsAsync() / DisableToolbarItemsAsync() - Control toolbar availability
Advanced workflow patterns and use cases

📄 阅读： references/advanced-methods.md

GetSelectedBlocksAsync() - 获取选中的区块
SelectAllBlocksAsync() - 以编程方式选中所有区块
FocusInAsync() / FocusOutAsync() - 管理编辑器焦点
PrintAsync() - 打印编辑器内容
EnableToolbarItemsAsync() / DisableToolbarItemsAsync() - 控制工具栏可用性
高级工作流模式与用例

Advanced Features

高级特性

📄 Read: references/advanced-features.md

WebAssembly integration and considerations
Performance optimization strategies
Custom block type implementation
Accessibility features (WCAG compliance)
Auto-save and state persistence patterns
Common troubleshooting scenarios

📄 阅读： references/advanced-features.md

WebAssembly集成与注意事项
性能优化策略
自定义区块类型实现
无障碍特性（WCAG合规）
自动保存与状态持久化模式
常见故障排除场景

Quick Start Example

快速入门示例

razor

@using Syncfusion.Blazor.BlockEditor

@rendermode InteractiveAuto

<div id="container" style="height: 500px; width: 100%;">
    <SfBlockEditor @bind-Blocks="blockData" EnableDragAndDrop="true">
        <BlockEditorCommandMenu></BlockEditorCommandMenu>
        <BlockEditorContextMenu Enable="true"></BlockEditorContextMenu>
        <BlockEditorActionMenu Enable="true"></BlockEditorActionMenu>
        <BlockEditorInlineToolbar Enable="true"></BlockEditorInlineToolbar>
        <BlockEditorPasteCleanup AllowedStyles="@(new string[] { "font-weight", "font-style", "text-decoration" })"
                                 DeniedTags="@(new string[] { "script", "iframe" })">
        </BlockEditorPasteCleanup>
    </SfBlockEditor>
</div>

@code {
    private List<BlockModel> blockData = new List<BlockModel>
    {
        new BlockModel
        {
            BlockType = BlockType.Heading,
            Properties = new HeadingBlockSettings { Level = 1 },
            Content = new List<ContentModel>
            {
                new ContentModel { ContentType = ContentType.Text, Content = "Welcome to Block Editor" }
            }
        },
        new BlockModel
        {
            BlockType = BlockType.Paragraph,
            Content = new List<ContentModel>
            {
                new ContentModel { ContentType = ContentType.Text, Content = "Start typing or use / to add new blocks..." }
            }
        }
    };
}

razor

@using Syncfusion.Blazor.BlockEditor

@rendermode InteractiveAuto

<div id="container" style="height: 500px; width: 100%;">
    <SfBlockEditor @bind-Blocks="blockData" EnableDragAndDrop="true">
        <BlockEditorCommandMenu></BlockEditorCommandMenu>
        <BlockEditorContextMenu Enable="true"></BlockEditorContextMenu>
        <BlockEditorActionMenu Enable="true"></BlockEditorActionMenu>
        <BlockEditorInlineToolbar Enable="true"></BlockEditorInlineToolbar>
        <BlockEditorPasteCleanup AllowedStyles="@(new string[] { "font-weight", "font-style", "text-decoration" })"
                                 DeniedTags="@(new string[] { "script", "iframe" })">
        </BlockEditorPasteCleanup>
    </SfBlockEditor>
</div>

@code {
    private List<BlockModel> blockData = new List<BlockModel>
    {
        new BlockModel
        {
            BlockType = BlockType.Heading,
            Properties = new HeadingBlockSettings { Level = 1 },
            Content = new List<ContentModel>
            {
                new ContentModel { ContentType = ContentType.Text, Content = "Welcome to Block Editor" }
            }
        },
        new BlockModel
        {
            BlockType = BlockType.Paragraph,
            Content = new List<ContentModel>
            {
                new ContentModel { ContentType = ContentType.Text, Content = "Start typing or use / to add new blocks..." }
            }
        }
    };
}

Common Patterns

常见模式

Pattern 1: Event-Driven Content Tracking

模式1：事件驱动的内容跟踪

Monitor document changes in real-time for auto-save or logging:

razor

<SfBlockEditor BlockChanged="@OnBlockChanged" 
               SelectionChanged="@OnSelectionChanged">
</SfBlockEditor>

@code {
    private void OnBlockChanged(BlockChangedEventArgs args)
    {
        // Auto-save, track changes, update UI
    }

    private void OnSelectionChanged(SelectionChangedEventArgs args)
    {
        // Update toolbar state based on selection
    }
}

实时监控文档变更，用于自动保存或日志记录：

razor

<SfBlockEditor BlockChanged="@OnBlockChanged" 
               SelectionChanged="@OnSelectionChanged">
</SfBlockEditor>

@code {
    private void OnBlockChanged(BlockChangedEventArgs args)
    {
        // 自动保存、跟踪变更、更新UI
    }

    private void OnSelectionChanged(SelectionChangedEventArgs args)
    {
        // 根据选择内容更新工具栏状态
    }
}

Pattern 2: Read-Only Preview Mode

模式2：只读预览模式

Display finalized content without editing:

razor

<SfBlockEditor @bind-Blocks="blockData" ReadOnly="true">
</SfBlockEditor>

显示最终内容，不允许编辑：

razor

<SfBlockEditor @bind-Blocks="blockData" ReadOnly="true">
</SfBlockEditor>

Pattern 3: Custom Keyboard Shortcuts

模式3：自定义键盘快捷键

Override default shortcuts for application-specific commands:

razor

<SfBlockEditor KeyConfig="@customShortcuts">
</SfBlockEditor>

@code {
    private Dictionary<string, string> customShortcuts = new()
    {
        { "Bold", "alt+b" },
        { "Italic", "alt+i" }
    };
}

覆盖默认快捷键，适配应用特定命令：

razor

<SfBlockEditor KeyConfig="@customShortcuts">
</SfBlockEditor>

@code {
    private Dictionary<string, string> customShortcuts = new()
    {
        { "Bold", "alt+b" },
        { "Italic", "alt+i" }
    };
}

Pattern 4: Secure Paste with Content Filtering

模式4：带内容过滤的安全粘贴

Control paste behavior for safety and consistency:

razor

<BlockEditorPasteCleanup AllowedStyles="@allowedStyles"
                         DeniedTags="@deniedTags"
                         PlainText="false">
</BlockEditorPasteCleanup>

@code {
    private string[] allowedStyles = { "font-weight", "font-style" };
    private string[] deniedTags = { "script", "iframe", "object" };
}

控制粘贴行为，确保安全性和一致性：

razor

<BlockEditorPasteCleanup AllowedStyles="@allowedStyles"
                         DeniedTags="@deniedTags"
                         PlainText="false">
</BlockEditorPasteCleanup>

@code {
    private string[] allowedStyles = { "font-weight", "font-style" };
    private string[] deniedTags = { "script", "iframe", "object" };
}

Key Properties

核心属性

Property	Type	Default	Purpose
`Blocks`	`List<BlockModel>`	Empty	The content blocks bound to the editor
`Width`	`string`	"100%"	Editor container width
`Height`	`string`	"auto"	Editor container height
`ReadOnly`	`bool`	false	Enable/disable read-only mode
`EnableDragAndDrop`	`bool`	true	Enable/disable block dragging
`UndoRedoStack`	`int`	30	Maximum undo/redo history depth
`CssClass`	`string`	""	Custom CSS classes for styling
`KeyConfig`	`Dictionary<string, string>`	Default shortcuts	Custom keyboard shortcuts

属性	类型	默认值	用途
`Blocks`	`List<BlockModel>`	空	绑定到编辑器的内容区块
`Width`	`string`	"100%"	编辑器容器宽度
`Height`	`string`	"auto"	编辑器容器高度
`ReadOnly`	`bool`	false	启用/禁用只读模式
`EnableDragAndDrop`	`bool`	true	启用/禁用区块拖拽
`UndoRedoStack`	`int`	30	最大撤销/重做历史记录深度
`CssClass`	`string`	""	用于样式的自定义CSS类
`KeyConfig`	`Dictionary<string, string>`	默认快捷键	自定义键盘快捷键

Common Use Cases

常见用例

Blog Platform: Create a rich blog editor with headings, images, and formatting
Document Management: Build document creators for articles and reports
Knowledge Base: Implement structured content editors for documentation
Content Preview: Display finalized documents in read-only mode
Form Builder: Use blocks to create dynamic form templates
Email Templates: Create email templates with customizable blocks
Proposal Builder: Generate professional proposals with block-based structure

博客平台：创建包含标题、图片和格式设置的富博客编辑器
文档管理：构建用于文章和报告的文档创作工具
知识库：为文档系统实现结构化内容编辑器
内容预览：以只读模式显示最终文档
表单构建器：使用区块创建动态表单模板
邮件模板：创建带可自定义区块的邮件模板
提案构建器：生成具备区块化结构的专业提案