syncfusion-aspnetcore-blockeditor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Syncfusion ASP.NET Core Block Editor Control

Syncfusion ASP.NET Core Block Editor 控件

Overview

概述

A comprehensive skill for implementing Syncfusion EJ2 Block Editor in ASP.NET Core applications using Razor Tag Helpers. This skill covers setup, block configuration, content manipulation, events, and best practices for creating block-based document editors.

The Syncfusion Block Editor is a versatile, block-based content editor that allows users to create and edit structured documents using discrete content blocks. Key capabilities include:

Multiple Block Types: Paragraph, Headings (1-4), Lists (Bullet, Numbered, Checklist), Code, Tables, Images, Quotes, Callouts, and more
Nested Structures: Support for collapsible headings, quotes, and callouts with child blocks
Rich Editor Menus: Slash commands, context menus, inline toolbars, and block action menus
Drag-and-Drop: Reorder blocks seamlessly with visual feedback
Content Sanitization: Built-in paste cleanup with configurable allowed styles and denied tags
Keyboard Shortcuts: Comprehensive shortcuts for formatting, block creation, and management
Undo/Redo: Configurable undo/redo stack (default 30 actions)
Globalization: Multi-language support and RTL layout support
Events: Rich event system for monitoring user interactions and content changes
Responsive Design: Adaptive UI that works on desktop and mobile devices

这是一份关于使用Razor Tag Helpers在ASP.NET Core应用中实现Syncfusion EJ2 Block Editor的全面指南。本指南涵盖了基于区块的文档编辑器的搭建、区块配置、内容操作、事件处理以及最佳实践。

Syncfusion Block Editor是一款多功能的基于区块的内容编辑器，允许用户使用独立的内容区块创建和编辑结构化文档。核心功能包括：

多种区块类型：Paragraph（段落）、Headings（1-4级标题）、Lists（项目符号、编号、复选列表）、Code（代码块）、Tables（表格）、Images（图片）、Quotes（引用）、Callouts（提示框）等
嵌套结构：支持可折叠标题、引用和带有子区块的提示框
丰富编辑器菜单：斜杠命令、上下文菜单、内联工具栏和区块操作菜单
拖放功能：通过视觉反馈无缝重新排序区块
内容清理：内置粘贴清理功能，可配置允许的样式和禁用的标签
键盘快捷键：用于格式化、区块创建和管理的全面快捷键
撤销/重做：可配置的撤销/重做堆栈（默认30次操作）
全球化：多语言支持和RTL布局支持
事件系统：用于监控用户交互和内容变化的丰富事件体系
响应式设计：适配桌面和移动设备的自适应UI

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

Installation and package setup
Basic BlockEditor implementation
CSS imports and theme selection
Creating the first Block Editor instance
Setting initial block content

📄 阅读： references/getting-started.md

安装和包配置
BlockEditor基础实现
CSS导入和主题选择
创建第一个Block Editor实例
设置初始区块内容

Built-in Blocks

内置区块

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

Block types overview (Paragraph, Heading, Lists, Code, Table, Embed, etc.)
Block properties (id, blockType, content, indent)
Nested block types (CollapsibleHeading, CollapsibleParagraph, Quote, Callout)
Parent-child relationships and hierarchy
Expanded state control and placeholders
CSS class customization and templates

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

区块类型概述（Paragraph、Heading、Lists、Code、Table、Embed等）
区块属性（id、blockType、content、indent）
嵌套区块类型（CollapsibleHeading、CollapsibleParagraph、Quote、Callout）
父子关系和层级结构
展开状态控制和占位符
CSS类自定义和模板

Block Editor Menus

Block Editor菜单

📄 Read: references/blockeditor-menus.md

Inline toolbar configuration and events
Block actions menu customization
Slash commands (/) for quick block insertion
Context menu configuration
Toolbar buttons and formatting actions

📄 阅读： references/blockeditor-menus.md

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

Drag-Drop and Content

拖放与内容

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

Enable drag-and-drop functionality
Reordering blocks by dragging
Multiple block selection and movement
Visual feedback during drag operations
Content insertion and block positioning

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

启用拖放功能
通过拖动重新排序区块
多选区块并移动
拖放操作中的视觉反馈
内容插入和区块定位

Methods and API

方法与API

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

Block Management: addBlock, removeBlock, moveBlock, updateBlock, getBlock, getBlockCount
Selection & Cursor: setSelection, setCursorPosition, getSelectedBlocks, getRange, selectRange, selectBlock, selectAllBlocks
Focus Management: focusIn, focusOut
Formatting: executeToolbarAction, enableToolbarItems, disableToolbarItems
Data Export: getDataAsJson, getDataAsHtml, renderBlocksFromJson, parseHtmlToBlocks, print
Practical examples for each method category

📄 阅读： 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
各类方法的实用示例

Styling and Appearance

样式与外观

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

CSS theming options (Material, Bootstrap, Fluent, Tailwind, Fabric themes)
Block-level styling and cssClass property
Typography options (bold, italic, underline, strikethrough)
Indentation and nested block styling
Placeholder text customization
Dark mode support and custom themes

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

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

Advanced Features

高级特性

📄 Read: references/advanced-features.md

Paste cleanup and content sanitization (allowed styles, denied tags)
Keep format and plain text modes
Undo/Redo functionality and stack configuration
Keyboard shortcuts and customization
Read-only mode for view-only editors
XSS protection and HTML sanitizer
RTL (Right-to-Left) support
Globalization and multi-language localization

📄 阅读： references/advanced-features.md

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

Quick Start Example

快速入门示例

Basic Block Editor Setup

基础Block Editor配置

Step 1: Install NuGet Package

powershell

Install-Package Syncfusion.EJ2.AspNet.Core

Step 2: Register in _ViewImports.cshtml

razor

@addTagHelper *, Syncfusion.EJ2

Step 3: Add CSS and Scripts in _Layout.cshtml

razor

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

Step 4: Create Block Editor in View

razor

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

Step 5: Configure Blocks in Controller

csharp

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：安装NuGet包

powershell

Install-Package Syncfusion.EJ2.AspNet.Core

步骤2：在_ViewImports.cshtml中注册

razor

@addTagHelper *, Syncfusion.EJ2

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

razor

<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：在视图中创建Block Editor

razor

@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：在控制器中配置区块

csharp

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

Common Patterns

常见模式

Pattern 1: Add New Block Dynamically

模式1：动态添加新区块

javascript

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

javascript

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'
        }
    ]
};

// 在指定区块后添加
blockEditorObj.addBlock(newBlock, 'existing-block-id', true);

Pattern 2: Nested Collapsible Structure

模式2：嵌套可折叠结构

csharp

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

csharp

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

Pattern 3: Configure Paste Cleanup

模式3：配置粘贴清理

razor

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

razor

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

Pattern 4: Custom Slash Commands

模式4：自定义斜杠命令

csharp

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;

csharp

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;

Pattern 5: Readonly Editor for Display

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

razor

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

razor

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

Key Properties

关键属性

Property	Type	Description	Default
`id`	string	Unique identifier for the Block Editor instance	-
`blocks`	List<BlockModel>	Initial block content	[]
`height`	string	Height of the editor (px, vh, %)	auto
`width`	string	Width of the editor (px, %)	100%
`readOnly`	bool	Enable read-only mode	false
`cssClass`	string	Custom CSS class for styling	-
`enableDragAndDrop`	bool	Enable block drag-and-drop	true
`enableRtl`	bool	Enable right-to-left layout	false
`locale`	string	Localization culture (e.g., "de", "es")	"en"
`undoRedoStack`	int	Number of undo/redo steps	30
`keyConfig`	object	Keyboard shortcuts configuration	default shortcuts

属性	类型	描述	默认值
`id`	string	Block Editor实例的唯一标识符	-
`blocks`	List<BlockModel>	初始区块内容	[]
`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	键盘快捷键配置	默认快捷键

Common Use Cases

常见应用场景

Blog Post Editor - Create a structured blog editor with headings, paragraphs, lists, code snippets, and images
Knowledge Base - Build hierarchical documentation with collapsible sections and nested content
Newsletter Template Builder - Design email templates with predefined blocks
Content Management System - Manage modular content with drag-and-drop block reordering
Documentation Platform - Create technical documentation with code blocks, tables, and callouts
Form Builder - Create dynamic forms with conditional block visibility
Collaborative Editing - Implement shared document editing with block-level permissions

博客文章编辑器 - 创建包含标题、段落、列表、代码片段和图片的结构化博客编辑器
知识库 - 构建带有可折叠章节和嵌套内容的层级文档
通讯模板构建器 - 使用预定义区块设计邮件模板
内容管理系统 - 通过拖放重新排序区块来管理模块化内容
文档平台 - 创建包含代码块、表格和提示框的技术文档
表单构建器 - 创建带有条件区块可见性的动态表单
协作编辑 - 实现带有区块级权限的共享文档编辑

Workflow Pattern

工作流模式

When implementing a Syncfusion Block Editor in ASP.NET Core:

Install and Setup - Follow Getting Started guide for package installation and registration
Define Block Structure - Choose block types and configure them in references/built-in-blocks.md
Initialize Editor - Create Block Editor instance with initial blocks
Configure Features - Enable menus, drag-drop, paste cleanup as needed
Handle Events - Bind to events for content validation, logging, or integration
Customize Appearance - Apply CSS themes, custom classes, and styling
Implement Methods - Use API methods for programmatic content manipulation
Test and Optimize - Verify functionality and performance

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

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