Back to Details

syncfusion-angular-blockeditor

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Syncfusion Angular Block Editor Component

Syncfusion Angular Block Editor组件

Component Overview

组件概述

The Syncfusion Angular Block Editor is a powerful block-based editor component for Angular applications. It provides a document-centric editing experience similar to modern content management systems, with extensive support for formatting, customization, and advanced features.
Key Capabilities:
  • Block Management - Compose documents with various block types (paragraphs, headings, lists, tables, code, images)
  • Text Formatting - Bold, italic, underline, strikethrough, colors, highlights, and inline styles
  • Advanced Menus - Slash commands, context menus, inline toolbars, and block action menus
  • Events & Interactions - Comprehensive event handling for content changes, selection, drag-drop, paste operations
  • Content Management - Import/export as JSON, HTML, or Markdown with full serialization control
  • Methods - Programmatically add, remove, move, and update blocks with full API access
  • Security Features - Built-in HTML sanitization and XSS prevention for safe content
  • Toolbar Configuration - Customizable slash commands and block action menus with grouping
  • Templates - Custom templates for blocks, placeholders, and empty states
  • Globalization - Multi-language support, RTL languages, and locale-based keyboard shortcuts
  • Customizable UI - Themes, CSS variables, responsive sizing, read-only mode, and placeholder text
Syncfusion Angular Block Editor是一款适用于Angular应用的强大块级编辑器组件。它提供类似现代内容管理系统的以文档为中心的编辑体验，全面支持格式设置、自定义和高级功能。
核心功能：
  • 块管理 - 使用多种块类型（段落、标题、列表、表格、代码、图片）组合文档
  • 文本格式设置 - 粗体、斜体、下划线、删除线、颜色、高亮及内联样式
  • 高级菜单 - 斜杠命令、上下文菜单、内联工具栏和块操作菜单
  • 事件与交互 - 针对内容变更、选择、拖放、粘贴操作的全面事件处理
  • 内容管理 - 以JSON、HTML或Markdown格式导入/导出，支持完整序列化控制
  • 方法 - 通过完整API访问以编程方式添加、删除、移动和更新块
  • 安全功能 - 内置HTML清理和XSS防护，确保内容安全
  • 工具栏配置 - 可自定义斜杠命令和块操作菜单，支持分组
  • 模板 - 块、占位符和空状态的自定义模板
  • 全球化 - 多语言支持、RTL语言和基于区域设置的键盘快捷键
  • 可自定义UI - 主题、CSS变量、响应式尺寸、只读模式和占位符文本

Quick Navigation Guide

快速导航指南

Getting Started

入门指南

Start here if you're new to Block Editor or need setup instructions.
Read When:
  • Setting up a new project with Block Editor
  • Installing and importing dependencies
  • Configuring CSS and basic properties
  • Creating your first editor instance
👉 Getting Started
如果您是Block Editor新手或需要设置说明，请从这里开始。
阅读场景：
  • 使用Block Editor搭建新项目
  • 安装和导入依赖项
  • 配置CSS和基本属性
  • 创建您的第一个编辑器实例
👉 入门指南

Core Concepts

核心概念

Learn the fundamental architecture and data structures.
Read When:
  • Understanding block types and their purposes
  • Learning about BlockModel and ContentModel
  • Grasping how blocks are organized and related
  • Understanding different content types within blocks
👉 Core Concepts
了解基础架构和数据结构。
阅读场景：
  • 了解块类型及其用途
  • 学习BlockModel和ContentModel
  • 掌握块的组织和关联方式
  • 了解块内的不同内容类型
👉 核心概念

Block Management Methods

块管理方法

Programmatically manipulate editor content and structure.
Read When:
  • Adding, removing, or moving blocks
  • Updating block properties
  • Querying block count and data
  • Building dynamic document structures
👉 Block Management Methods
以编程方式操作编辑器内容和结构。
阅读场景：
  • 添加、删除或移动块
  • 更新块属性
  • 查询块数量和数据
  • 构建动态文档结构
👉 块管理方法

Selection and Cursor Methods

选择与光标方法

Control user selection and cursor positioning.
Read When:
  • Setting cursor position programmatically
  • Selecting text or blocks
  • Implementing text selection features
  • Managing ranges and selections
  • Execute toolbar actions programmatically (executeToolbarAction)
👉 Selection and Cursor Methods
控制用户选择和光标位置。
阅读场景：
  • 以编程方式设置光标位置
  • 选择文本或块
  • 实现文本选择功能
  • 管理范围和选择
  • 以编程方式执行工具栏操作（executeToolbarAction）
👉 选择与光标方法

Utility Methods

实用方法

Control editor focus, toolbar state, and printing functionality.
Read When:
  • Focusing or blurring the editor programmatically
  • Enabling or disabling toolbar items dynamically
  • Implementing conditional toolbar access
  • Printing editor content
  • Managing editor state based on user actions
👉 Utility Methods
控制编辑器焦点、工具栏状态和打印功能。
阅读场景：
  • 以编程方式聚焦或失焦编辑器
  • 动态启用或禁用工具栏项
  • 实现条件工具栏访问
  • 打印编辑器内容
  • 根据用户操作管理编辑器状态
👉 实用方法

Configuration Properties

配置属性

Configure editor styling, security settings, users and labels.
Read When:
  • Applying custom CSS classes for theming
  • Implementing dark mode or custom themes
  • Configuring HTML encoding for security
  • Setting up XSS prevention
  • Integrating with CSS frameworks (Bootstrap, Tailwind, Material)
  • Configuring users for multi-user editing
  • Adding user avatars and identification
  • Implementing @mentions functionality
  • Creating label/tag systems (#tags)
  • Setting up project management labels
  • Tracking content by user or category
👉 Configuration Properties
配置编辑器样式、安全设置、用户和标签。
阅读场景：
  • 应用自定义CSS类进行主题设置
  • 实现深色模式或自定义主题
  • 配置HTML编码以保障安全
  • 设置XSS防护
  • 与CSS框架（Bootstrap、Tailwind、Material）集成
  • 配置多用户编辑的用户信息
  • 添加用户头像和标识
  • 实现@提及功能
  • 创建标签/标记系统（#tags）
  • 设置项目管理标签
  • 按用户或类别跟踪内容
👉 配置属性

Editor Menus

编辑器菜单

Configure slash commands, context menus, and toolbars.
Read When:
  • Customizing the slash command menu (/)
  • Adding context menu items
  • Configuring block action menus
  • Creating inline toolbars
  • Adding custom menu items
👉 Editor Menus
配置斜杠命令、上下文菜单和工具栏。
阅读场景：
  • 自定义斜杠命令菜单（/）
  • 添加上下文菜单项
  • 配置块操作菜单
  • 创建内联工具栏
  • 添加自定义菜单项
👉 编辑器菜单

Events and Callbacks

事件与回调

Handle user interactions and content changes.
Read When:
  • Implementing auto-save functionality
  • Validating content changes
  • Tracking user interactions
  • Responding to selection changes
  • Handling paste operations
👉 Events and Callbacks
处理用户交互和内容变更。
阅读场景：
  • 实现自动保存功能
  • 验证内容变更
  • 跟踪用户交互
  • 响应选择变更
  • 处理粘贴操作
👉 事件与回调

Formatting and Styles

格式设置与样式

Apply text formatting and styling.
Read When:
  • Making text bold, italic, underlined
  • Applying colors and backgrounds
  • Using advanced text styles (superscript, code, etc.)
  • Formatting block types (headings, quotes, etc.)
  • Creating styled content
👉 Formatting and Styles
应用文本格式设置和样式。
阅读场景：
  • 设置文本粗体、斜体、下划线
  • 应用颜色和背景
  • 使用高级文本样式（上标、代码等）
  • 设置块类型格式（标题、引用等）
  • 创建带样式的内容
👉 格式设置与样式

Data Structures and Lists

数据结构与列表

Work with list blocks and table structures.
Read When:
  • Creating bullet or numbered lists
  • Adding checklists with checkboxes
  • Building tables with rows and columns
  • Creating nested indented content
  • Working with toggle/collapsible blocks
👉 Data Structures and Lists
处理列表块和表格结构。
阅读场景：
  • 创建项目符号或编号列表
  • 添加带复选框的待办事项列表
  • 构建带行和列的表格
  • 创建嵌套缩进内容
  • 处理可切换/折叠块
👉 数据结构与列表

Advanced Features

高级功能

Explore undo/redo, drag-drop, code blocks, and templates.
Read When:
  • Configuring undo/redo stack size
  • Customizing drag and drop behavior
  • Adding code blocks with syntax highlighting
  • Creating custom template blocks
  • Building complex document layouts
👉 Advanced Features
探索撤销/重做、拖放、代码块和模板。
阅读场景：
  • 配置撤销/重做栈大小
  • 自定义拖放行为
  • 添加带语法高亮的代码块
  • 创建自定义模板块
  • 构建复杂文档布局
👉 高级功能

Data Export and Import

数据导出与导入

Convert between formats and persist content.
Read When:
  • Exporting editor content as JSON
  • Converting to HTML or Markdown
  • Importing from JSON or HTML files
  • Parsing external HTML content
  • Printing documents
  • Synchronizing with servers
👉 Data Export and Import
在不同格式间转换并持久化内容。
阅读场景：
  • 将编辑器内容导出为JSON
  • 转换为HTML或Markdown
  • 从JSON或HTML文件导入
  • 解析外部HTML内容
  • 打印文档
  • 与服务器同步
👉 数据导出与导入

Keyboard Shortcuts and Globalization

键盘快捷键与全球化

Configure shortcuts and multi-language support.
Read When:
  • Customizing keyboard shortcuts
  • Setting up platform-specific shortcuts
  • Implementing internationalization
  • Supporting RTL languages
  • Configuring language-specific settings
👉 Keyboard Shortcuts and Globalization
配置快捷键和多语言支持。
阅读场景：
  • 自定义键盘快捷键
  • 设置平台特定快捷键
  • 实现国际化
  • 支持RTL语言
  • 配置特定语言设置
👉 键盘快捷键与全球化

Security and Paste Handling

安全与粘贴处理

Secure the editor and manage content pasting.
Read When:
  • Enabling HTML sanitization
  • Preventing XSS attacks
  • Configuring paste cleanup rules
  • Managing allowed styles and tags
  • Implementing read-only mode
  • Validating user input
👉 Security and Paste Handling
保障编辑器安全并管理内容粘贴。
阅读场景：
  • 启用HTML清理
  • 防止XSS攻击
  • 配置粘贴清理规则
  • 管理允许的样式和标签
  • 实现只读模式
  • 验证用户输入
👉 安全与粘贴处理

Appearance and Customization

外观与自定义

Style and customize the editor appearance.
Read When:
  • Setting custom width/height
  • Applying themes (light, dark, high-contrast)
  • Using CSS variables for styling
  • Customizing fonts and typography
  • Creating responsive editors
  • Styling with custom CSS classes
👉 Appearance and Customization
设置和自定义编辑器外观。
阅读场景：
  • 设置自定义宽/高
  • 应用主题（浅色、深色、高对比度）
  • 使用CSS变量进行样式设置
  • 自定义字体和排版
  • 创建响应式编辑器
  • 使用自定义CSS类设置样式
👉 外观与自定义

Quick Start Example

快速开始示例

1. Install Dependencies

1. 安装依赖

bash
npm install @syncfusion/ej2-angular-blockeditor
npm install @syncfusion/ej2-angular-buttons
npm install @syncfusion/ej2-base
bash
npm install @syncfusion/ej2-angular-blockeditor
npm install @syncfusion/ej2-angular-buttons
npm install @syncfusion/ej2-base

2. Create Component

2. 创建组件

typescript
import { Component } from '@angular/core';
import { BlockEditorModule } from '@syncfusion/ej2-angular-blockeditor';

@Component({
  selector: 'app-editor',
  template: `<ejs-blockeditor [height]="'500px'" />`,
  standalone: true,
  imports: [BlockEditorModule]
})
export class EditorComponent {}
typescript
import { Component } from '@angular/core';
import { BlockEditorModule } from '@syncfusion/ej2-angular-blockeditor';

@Component({
  selector: 'app-editor',
  template: `<ejs-blockeditor [height]="'500px'" />`,
  standalone: true,
  imports: [BlockEditorModule]
})
export class EditorComponent {}

3. Import CSS

3. 导入CSS

css

@import '../node_modules/@syncfusion/ej2-base/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-inputs/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-popups/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-buttons/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-splitbuttons/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-navigations/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-dropdowns/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-angular-blockeditor/styles/material3.css';
css

@import '../node_modules/@syncfusion/ej2-base/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-inputs/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-popups/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-buttons/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-splitbuttons/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-navigations/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-dropdowns/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-angular-blockeditor/styles/material3.css';

4. Add to Module/Bootstrap

4. 添加到模块/引导程序

typescript
// app.config.ts
import { importProvidersFrom } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';

export const appConfig = {
  providers: [
    importProvidersFrom(BrowserModule)
  ]
};

// OR in app.module.ts
@NgModule({
  imports: [BlockEditorModule]
})
export class AppModule {}
typescript
// app.config.ts
import { importProvidersFrom } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';

export const appConfig = {
  providers: [
    importProvidersFrom(BrowserModule)
  ]
};

// OR in app.module.ts
@NgModule({
  imports: [BlockEditorModule]
})
export class AppModule {}

Common Patterns

常见模式

Pattern 1: Document Auto-Save

模式1：文档自动保存

typescript
@Component({
  selector: 'app-autosave-editor',
  template: `
    <div>
      <span>Status: {{ saveStatus }}</span>
      <ejs-blockeditor #editor (blockChanged)="onContentChange()"></ejs-blockeditor>
    </div>
  `,
  standalone: true,
  imports: [BlockEditorModule]
})
export class AutosaveEditorComponent {
  @ViewChild('editor') editor!: BlockEditorComponent;
  public saveStatus = 'Saved';
  private saveTimeout: any;

  public onContentChange(): void {
    this.saveStatus = 'Unsaved';
    clearTimeout(this.saveTimeout);
    
    this.saveTimeout = setTimeout(() => {
      const content = this.editor.getDataAsJson();
      this.saveToServer(content);
    }, 1000);
  }

  private saveToServer(content: any): void {
    // Save to backend
    this.saveStatus = 'Saved';
  }
}
typescript
@Component({
  selector: 'app-autosave-editor',
  template: `
    <div>
      <span>状态: {{ saveStatus }}</span>
      <ejs-blockeditor #editor (blockChanged)="onContentChange()"></ejs-blockeditor>
    </div>
  `,
  standalone: true,
  imports: [BlockEditorModule]
})
export class AutosaveEditorComponent {
  @ViewChild('editor') editor!: BlockEditorComponent;
  public saveStatus = '已保存';
  private saveTimeout: any;

  public onContentChange(): void {
    this.saveStatus = '未保存';
    clearTimeout(this.saveTimeout);
    
    this.saveTimeout = setTimeout(() => {
      const content = this.editor.getDataAsJson();
      this.saveToServer(content);
    }, 1000);
  }

  private saveToServer(content: any): void {
    // 保存到后端
    this.saveStatus = '已保存';
  }
}

Pattern 2: Formatted Document Export

模式2：格式化文档导出

typescript
@Component({
  selector: 'app-document-exporter',
  template: `
    <div>
      <button (click)="exportJson()">Export JSON</button>
      <button (click)="exportHtml()">Export HTML</button>
      <button (click)="exportMarkdown()">Export Markdown</button>
      <ejs-blockeditor #editor></ejs-blockeditor>
    </div>
  `,
  standalone: true,
  imports: [BlockEditorModule]
})
export class DocumentExporterComponent {
  @ViewChild('editor') editor!: BlockEditorComponent;

  public exportJson(): void {
    const data = this.editor.getDataAsJson();
    this.downloadFile(JSON.stringify(data, null, 2), 'document.json', 'application/json');
  }

  public exportHtml(): void {
    const html = this.editor.getDataAsHtml();
    this.downloadFile(html, 'document.html', 'text/html');
  }

  public exportMarkdown(): void {
    // Convert to markdown format
    const data = this.editor.getDataAsJson();
    const markdown = this.convertToMarkdown(data);
    this.downloadFile(markdown, 'document.md', 'text/markdown');
  }

  private downloadFile(content: string, filename: string, type: string): void {
    const blob = new Blob([content], { type });
    const url = URL.createObjectURL(blob);
    const link = document.createElement('a');
    link.href = url;
    link.download = filename;
    link.click();
  }

  private convertToMarkdown(blocks: any[]): string {
    // Implementation details in Data Export and Import reference
    return '';
  }
}
typescript
@Component({
  selector: 'app-document-exporter',
  template: `
    <div>
      <button (click)="exportJson()">导出JSON</button>
      <button (click)="exportHtml()">导出HTML</button>
      <button (click)="exportMarkdown()">导出Markdown</button>
      <ejs-blockeditor #editor></ejs-blockeditor>
    </div>
  `,
  standalone: true,
  imports: [BlockEditorModule]
})
export class DocumentExporterComponent {
  @ViewChild('editor') editor!: BlockEditorComponent;

  public exportJson(): void {
    const data = this.editor.getDataAsJson();
    this.downloadFile(JSON.stringify(data, null, 2), 'document.json', 'application/json');
  }

  public exportHtml(): void {
    const html = this.editor.getDataAsHtml();
    this.downloadFile(html, 'document.html', 'text/html');
  }

  public exportMarkdown(): void {
    // 转换为Markdown格式
    const data = this.editor.getDataAsJson();
    const markdown = this.convertToMarkdown(data);
    this.downloadFile(markdown, 'document.md', 'text/markdown');
  }

  private downloadFile(content: string, filename: string, type: string): void {
    const blob = new Blob([content], { type });
    const url = URL.createObjectURL(blob);
    const link = document.createElement('a');
    link.href = url;
    link.download = filename;
    link.click();
  }

  private convertToMarkdown(blocks: any[]): string {
    // 实现细节请参考数据导出与导入文档
    return '';
  }
}

Troubleshooting Guide

故障排除指南

Issue: Editor not displaying

问题：编辑器未显示

Solution: Ensure CSS is imported in main.ts or global styles
css

@import '../node_modules/@syncfusion/ej2-base/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-inputs/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-popups/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-buttons/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-splitbuttons/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-navigations/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-dropdowns/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-angular-blockeditor/styles/material3.css';
解决方案：确保在main.ts或全局样式中导入CSS
css

@import '../node_modules/@syncfusion/ej2-base/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-inputs/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-popups/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-buttons/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-splitbuttons/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-navigations/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-dropdowns/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-angular-blockeditor/styles/material3.css';

Issue: Content not saving

问题：内容未保存

Solution: Use 
getDataAsJson()
method to retrieve content
typescript
const content = this.blockEditor.getDataAsJson();
解决方案：使用
getDataAsJson()
方法获取内容
typescript
const content = this.blockEditor.getDataAsJson();

Issue: Events not firing

问题：事件未触发

Solution: Ensure component is standalone and imports are correct
typescript
@Component({
  standalone: true,
  imports: [BlockEditorModule]
})
解决方案：确保组件为独立组件且导入正确
typescript
@Component({
  standalone: true,
  imports: [BlockEditorModule]
})