syncfusion-blazor-blockeditor

Syncfusion Blazor Block Editor

组件概述

Syncfusion Blazor Block Editor 是一款功能强大的模块化内容创作组件，用户可以使用可自定义的块创建内容丰富、结构清晰的文档。每个块都代表一种特定的内容类型——标题、段落、列表、表格、图像、代码块等，带来简洁、有条理的编辑体验。

主要功能

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

文档和导航指南

入门指南

📄 阅读： references/getting-started.md

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

外观和样式

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

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

编辑器菜单

📄 阅读： references/editor-menus.md

• 斜杠命令菜单（内置项、自定义和事件）
• 上下文菜单（右键操作、自定义和事件）
• 块操作菜单（拖动手柄操作、自定义和事件）
• 内联工具栏（文本格式选项、自定义、事件和可选项——转换、内联代码、链接）
• 菜单事件处理和筛选
• 创建自定义命令和菜单项

内置块

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

• 标题块（级别 1-4）
• 段落块
• 列表类型（项目符号、编号、检查清单）
• 表格块
• 代码块
• 图像/媒体块（imageSettings 属性、调整大小配置、图像上传）
• 引用和提示框块
• 折叠块（可折叠）
• 分隔线块
• 块嵌套和层级结构

拖放和撤销/重做

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

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

事件和交互

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

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

内容处理

📄 阅读： references/content-handling.md

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

标签和提及

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

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

高级方法

📄 阅读： references/advanced-methods.md

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

高级功能

📄 阅读： references/advanced-features.md

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

快速入门示例

@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 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..." }
            }
        }
    };
}

常见模式

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

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

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

模式 2：只读预览模式

显示已定稿的内容，不允许编辑：

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

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

为应用程序专属命令覆盖默认快捷键：

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

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

模式 4：通过内容筛选实现安全粘贴

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

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

@code {
    private string[] deniedTags = { "script", "iframe", "object" };
}

关键属性

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

常见用例

1. 博客平台：创建支持标题、图片和格式设置的富文本博客编辑器
2. 文档管理：构建用于创建文章和报告的文档创建工具
3. 知识库：为文档实现结构化内容编辑器
4. 内容预览：以只读模式显示已定稿的文档
5. 表单构建器：使用块创建动态表单模板
6. 电子邮件模板：创建包含可自定义块的电子邮件模板
7. 提案构建器：通过基于块的结构生成专业提案