syncfusion-aspnetcore-blockeditor

Syncfusion ASP.NET Core Block Editor 控件

概述

这是一份全面的指南，介绍如何在 ASP.NET Core 应用程序中使用 Razor Tag Helpers 实现 Syncfusion EJ2 Block Editor。内容涵盖设置、块配置、内容操作、事件，以及创建基于块的文档编辑器的最佳实践。

Syncfusion Block Editor 是一款多功能的块式内容编辑器，用户可以使用独立的内容块创建和编辑结构化文档。主要功能包括：

• 多种块类型：段落、标题（1-4 级）、列表（项目符号、编号、待办清单）、代码、表格、图像、引言、提示框等
• 嵌套结构：支持可折叠标题、引言和带有子块的提示框
• 丰富的编辑器菜单：斜杠命令、上下文菜单、行内工具栏和块操作菜单
• 拖放：可无缝调整块的顺序，并提供视觉反馈
• 内容清理：内置粘贴清理功能，并可配置要拒绝的标签
• 键盘快捷键：提供丰富的快捷键，用于格式设置、创建块和管理块
• 撤销/重做：可配置的撤销/重做堆栈（默认 30 个操作）
• 国际化：支持多语言和 RTL 布局
• 事件：丰富的事件系统，可监控用户交互和内容更改
• 响应式设计：自适应 UI，可在桌面和移动设备上使用
• 协同编辑：借助 Yjs CRDT 框架实时进行多人文档编辑，支持远程光标感知、用户在线状态跟踪和版本历史管理

文档与导航指南

入门指南

📄 阅读： references/getting-started.md

• 安装和程序包设置
• 基本的 BlockEditor 实现
• CSS 导入和主题选择
• 创建第一个 Block Editor 实例
• 设置初始块内容

内置块

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

• 块类型概览（段落、标题、列表、代码、表格、嵌入等）
• 块属性（id、blockType、content、indent）
• 嵌套块类型（CollapsibleHeading、CollapsibleParagraph、Quote、Callout）
• 父子关系和层级结构
• 展开状态控制和占位符
• CSS 类自定义和模板

Block Editor 菜单

📄 阅读： references/blockeditor-menus.md

• 行内工具栏配置和事件
• 块操作菜单自定义
• 用于快速插入块的斜杠命令（/）
• 上下文菜单配置
• 工具栏按钮和格式操作

拖放与内容

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

• 启用拖放功能
• 通过拖动调整块的顺序
• 多选和移动块
• 拖动操作期间的视觉反馈
• 插入内容和设置块位置

方法与 API

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

• 块管理：addBlock、removeBlock、moveBlock、updateBlock、getBlock、getBlockCount
• 选择与光标：setSelection、setCursorPosition、getSelectedBlocks、getRange、selectRange、selectBlock、selectAllBlocks
• 焦点管理：focusIn、focusOut
• 格式设置：executeToolbarAction、enableToolbarItems、disableToolbarItems
• 数据导出：getDataAsJson、getDataAsHtml、renderBlocksFromJson、parseHtmlToBlocks、print
• 各类方法的实用示例

样式与外观

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

• CSS 主题选项（Material、Bootstrap、Fluent、Tailwind、Fabric 主题）
• 块级样式和 cssClass 属性
• 排版选项（粗体、斜体、下划线、删除线）
• 缩进和嵌套块样式
• 占位文本自定义
• 深色模式支持和自定义主题

高级功能

📄 阅读： references/advanced-features.md

• 粘贴清理和内容净化（禁止的标签）
• 保留格式和纯文本模式
• 撤销/重做功能和堆栈配置
• 键盘快捷键和自定义
• 适用于只读编辑器的只读模式
• XSS 防护和 HTML 净化器
• RTL（从右到左）支持
• 全球化和多语言本地化

协作编辑

📄 阅读： references/collaborative-editing.md

• 通过集成 Yjs provider 实现实时多人文档编辑
• 配置协作适配器和 provider（y-websocket、y-webrtc、Hocuspocus、Liveblocks、PartyKit）
• 通过 enableAwareness 显示用户状态和远程光标
• 通过 avatarBgColor 跟踪活跃用户并配置用户信息
• 通过快照管理版本历史，支持还原、比较、导出和导入操作
• 快照生命周期事件（snapshotCreated、snapshotRestored）
• 开发和生产部署的最佳实践
• 协作问题排查

快速入门示例

基本块编辑器设置

步骤 1：安装 NuGet 包

Install-Package Syncfusion.EJ2.AspNet.Core

步骤 2：在 _ViewImports.cshtml 中注册

@addTagHelper *, Syncfusion.EJ2

步骤 3：在 _Layout.cshtml 中添加 CSS 和脚本

<head>
    <link rel="stylesheet" href="https://cdn.syncfusion.com/ej2/dist/ej2.min.css" />
</head>
<body>
    @RenderBody()
    
    <script src="https://cdn.syncfusion.com/ej2/dist/ej2.min.js"></script>
    <ejs-scripts></ejs-scripts>
    
    @RenderSection("Scripts", required: false)
</body>

步骤 4：在视图中创建块编辑器

@using Syncfusion.EJ2.BlockEditor

<div id='blockeditor-container'>
    <ejs-blockeditor id="block-editor" blocks="@ViewBag.BlocksData"></ejs-blockeditor>
</div>

<style>
    #blockeditor-container {
        margin: 20px auto;
    }
</style>

步骤 5：在控制器中配置块

using Syncfusion.EJ2.BlockEditor;

public class BlockModel
{
    public string id { get; set; }
    public string blockType { get; set; }
    public object properties { get; set; }
    public List<object> content { get; set; }
}

public IActionResult Index()
{
    var blocks = new List<BlockModel>
    {
        new BlockModel
        {
            id = "heading-1",
            blockType = "Heading",
            properties = new { level = 1 },
            content = new List<object>
            {
                new { contentType = "Text", content = "Welcome to Block Editor" }
            }
        },
        new BlockModel
        {
            id = "paragraph-1",
            blockType = "Paragraph",
            content = new List<object>
            {
                new { contentType = "Text", content = "Start creating your content with blocks!" }
            }
        }
    };
    
    ViewBag.BlocksData = blocks;
    return View();
}

常见模式

模式 1：动态添加新块

var blockEditorObj = ej.base.getInstance(document.getElementById('block-editor'), ejs.blockeditor.BlockEditor);

const newBlock = {
    id: 'new-paragraph',
    blockType: 'Paragraph',
    content: [
        {
            contentType: "Text",
            content: 'This is a newly added block'
        }
    ]
};

// Add after a specific block
blockEditorObj.addBlock(newBlock, 'existing-block-id', true);

模式 2：嵌套的可折叠结构

new BlockModel
{
    blockType = "CollapsibleHeading",
    content = new List<object>
    {
        new { contentType = "Text", content = "Section Title" }
    },
    properties = new
    {
        level = 1,
        isExpanded = true,
        children = new List<BlockModel>
        {
            new BlockModel
            {
                blockType = "Paragraph",
                content = new List<object>
                {
                    new { contentType = "Text", content = "Hidden content goes here" }
                }
            }
        }
    }
}

模式 3：配置粘贴清理

<ejs-blockeditor id="block-editor">
    <e-blockeditor-pastesettings 
        deniedTags="@(new string[] { "script", "iframe", "form" })"
        keepFormat="true">
    </e-blockeditor-pastesettings>
</ejs-blockeditor>

模式 4：自定义斜杠命令

var commandMenuItems = new List<object>
{
    new 
    {
        id = "timestamp",
        groupHeader = "Actions",
        label = "Insert Timestamp",
        iconCss = "e-icons e-schedule"
    },
    new 
    {
        id = "separator",
        type = "Divider",
        groupHeader = "Utility",
        label = "Insert Divider",
        iconCss = "e-icons e-divider"
    }
};

ViewBag.CommandMenuItems = commandMenuItems;

模式 5：用于显示的只读编辑器

<ejs-blockeditor id="block-editor" 
                 readOnly="true" 
                 blocks="@ViewBag.BlocksData">
</ejs-blockeditor>

关键属性

属性	类型	描述	默认值
id	string	Block Editor 实例的唯一标识符	-
blocks	List	初始块内容	[]
height	string	编辑器高度（px、vh、%）	auto
width	string	编辑器宽度（px、%）	100%
readOnly	bool	启用只读模式	false
cssClass	string	用于设置样式的自定义 CSS 类	-
enableDragAndDrop	bool	启用块拖放	true
enableRtl	bool	启用从右到左布局	false
locale	string	本地化区域设置（例如 "de"、"es"）	"en"
undoRedoStack	int	撤销/重做步数	30
keyConfig	object	键盘快捷键配置	默认快捷键

常见用例

1. 博客文章编辑器 - 创建包含标题、段落、列表、代码片段和图片的结构化博客编辑器
2. 知识库 - 使用可折叠区段和嵌套内容构建分层文档
3. 新闻简报模板生成器 - 使用预定义块设计电子邮件模板
4. 内容管理系统 - 管理模块化内容，并通过拖放重新排序块
5. 文档平台 - 创建包含代码块、表格和提示框的技术文档
6. 表单生成器 - 创建支持条件块可见性的动态表单
7. 协作编辑 - 实现支持块级权限的共享文档编辑

工作流模式

在 ASP.NET Core 中实现 Syncfusion Block Editor 时：

1. 安装和设置 - 按照入门指南安装并注册包
2. 定义块结构 - 选择块类型，并在 references/built-in-blocks.md 中进行配置
3. 初始化编辑器 - 创建包含初始块的 Block Editor 实例
4. 配置功能 - 根据需要启用菜单、拖放和粘贴清理
5. 处理事件 - 绑定事件以进行内容验证、日志记录或集成
6. 自定义外观 - 应用 CSS 主题、自定义类和样式
7. 实现方法 - 使用 API 方法以编程方式操作内容
8. 测试和优化 - 验证功能和性能