syncfusion-angular-blockeditor

Syncfusion Angular Block Editor 组件

组件概述

Syncfusion Angular Block Editor 是一款功能强大的基于块的编辑器组件，适用于 Angular 应用。它提供类似现代内容管理系统的以文档为中心的编辑体验，并全面支持格式设置、自定义和高级功能。

主要功能：

• 块管理 - 使用各种块类型（段落、标题、列表、表格、代码、图像）编写文档
• 文本格式设置 - 粗体、斜体、下划线、删除线、颜色、高亮和内联样式
• 高级菜单 - 斜杠命令、上下文菜单、内联工具栏和块操作菜单
• 事件与交互 - 全面的事件处理，支持内容更改、选择、拖放和粘贴操作
• 内容管理 - 导入或导出为 JSON、HTML 或 Markdown，并完全控制序列化
• 方法 - 通过完整的 API 访问，以编程方式添加、移除、移动和更新块
• 安全功能 - 内置 HTML 清理和 XSS 防护，确保内容安全
• 协同编辑 - 由 Yjs 驱动的实时多用户编辑，支持用户状态、远程光标和版本历史记录
• 工具栏配置 - 可自定义的斜杠命令和块操作菜单，并支持分组
• 模板 - 用于块、占位符和空状态的自定义模板
• 全球化 - 支持多种语言、RTL 语言，以及基于区域设置的键盘快捷键
• 可自定义界面 - 主题、CSS 变量、自适应尺寸、只读模式和占位文本

快速导航指南

入门

如果你是 Block Editor 的新用户，或需要设置说明，请从这里开始。

阅读时机：

• 安装 Node.js v18+ 和 Angular CLI v14+
• 设置新的 Angular 应用
• 安装 Syncfusion Block Editor 包
• 配置 CSS 主题和样式
• 创建第一个 Block Editor 组件实例
• 运行 Angular 应用

👉 入门

---

核心概念

了解基本架构和数据结构。

阅读时机：

• 了解块类型及其用途
• 学习 BlockModel 和 ContentModel
• 理解块的组织方式及其关联关系
• 了解块中的不同内容类型

👉 核心概念

---

块管理方法

以编程方式操作编辑器内容和结构。

阅读时机：

• 添加、移除或移动块
• 更新块属性
• 查询块数量和数据
• 构建动态文档结构

👉 块管理方法

---

选择和光标方法

控制用户选择和光标位置。

阅读时机：

• 以编程方式设置光标位置
• 选择文本或块
• 实现文本选择功能
• 管理范围和选择
• 以编程方式执行工具栏操作（executeToolbarAction）

👉 选择和光标方法

---

实用方法

控制编辑器焦点、工具栏状态和打印功能。

阅读时机：

• 以编程方式聚焦或取消聚焦编辑器
• 动态启用或禁用工具栏项
• 实现有条件的工具栏访问
• 打印编辑器内容
• 根据用户操作管理编辑器状态

👉 实用方法

---

配置属性

配置编辑器样式、安全设置、用户和标签。

适用于以下情况：

• 应用自定义 CSS 类进行主题设置
• 实现深色模式或自定义主题
• 配置 HTML 编码以确保安全
• 设置 XSS 防护
• 集成 CSS 框架（Bootstrap、Tailwind、Material）
• 配置多用户编辑的用户
• 添加用户头像和身份标识
• 实现 @提及功能
• 创建标签系统（#标签）
• 设置项目管理标签
• 按用户或类别跟踪内容

👉 配置属性

---

编辑器菜单

配置斜杠命令、上下文菜单和工具栏。

适用于以下情况：

• 自定义斜杠命令菜单（/）
• 添加上下文菜单项
• 配置块操作菜单
• 创建内联工具栏
• 添加自定义菜单项

👉 编辑器菜单

---

事件和回调

处理用户交互和内容更改。

适用于以下情况：

• 实现自动保存功能
• 验证内容更改
• 跟踪用户交互
• 响应选区更改
• 处理粘贴操作

👉 事件和回调

---

格式和样式

应用文本格式和样式。

适用于以下情况：

• 将文本设为粗体、斜体或下划线
• 应用颜色和背景
• 使用高级文本样式（上标、代码等）
• 设置块类型格式（标题、引用等）
• 创建带样式的内容

👉 格式和样式

---

数据结构和列表

使用列表块和表格结构。

适用于以下情况：

• 创建项目符号列表或编号列表
• 添加带复选框的清单
• 创建包含行和列的表格
• 创建嵌套缩进内容
• 使用可切换／可折叠块

👉 数据结构和列表

---

高级功能

探索撤销／重做、拖放、代码块和模板。

适用于以下情况：

• 配置撤销／重做堆栈大小
• 自定义拖放行为
• 添加带语法高亮的代码块
• 创建自定义模板块
• 构建复杂的文档布局

👉 高级功能

---

数据导出和导入

在不同格式之间转换并持久化内容。

适用于以下情况：

• 将编辑器内容导出为 JSON
• 转换为 HTML 或 Markdown
• 从 JSON 或 HTML 文件导入
• 解析外部 HTML 内容
• 打印文档
• 与服务同步

👉 数据导出和导入

---

协同编辑

使用 Yjs 和版本控制实现实时多人编辑。

适用于以下情况：

• 使用 y-websocket 开始实时协作
• 选择并配置 Yjs 提供程序（y-websocket、y-webrtc、Hocuspocus、Liveblocks、PartyKit）
• 设置用于协作的 WebSocket 服务
• 显示用户状态、远程光标和文本选区
• 配置当前用户和活跃协作者
• 使用快照实现文档版本历史
• 创建、还原、比较、导出和导入文档快照
• 处理版本历史事件（snapshotCreated、snapshotRestored）
• 使用 IndexedDB 或自定义存储后端持久化快照

👉 协同编辑

---

键盘快捷键和全球化

配置快捷键和多语言支持。

适用于以下情况：

• 自定义键盘快捷键
• 设置特定平台的快捷键
• 实现国际化
• 支持 RTL 语言
• 配置特定语言的设置

👉 键盘快捷键和全球化

---

安全与粘贴处理

保护编辑器并管理粘贴的内容。

阅读时机：

• 启用 HTML 清理
• 防止 XSS 攻击
• 配置粘贴清理规则
• 管理允许的样式和标签
• 实现只读模式
• 验证用户输入

👉 安全与粘贴处理

---

外观与自定义

设置编辑器的样式并自定义其外观。

阅读时机：

• 设置自定义宽度/高度
• 应用内置主题或定义自定义主题
• 覆盖 --color-sf-* CSS 变量
• 定位 Block Editor CSS 类（.e-blockeditor、.e-active、.e-selected、.e-list-item、.e-dropdownbase、.e-table-element）和 ID（#blockeditor_contextmenu、#blockeditor_code-ddl_popup）
• 在运行时切换多个主题
• 自定义字体和排版
• 创建响应式编辑器
• 使用 Syncfusion Theme Studio 生成完全自定义的主题

👉 外观与自定义

---

快速入门示例

1. 安装依赖项

npm install @syncfusion/ej2-angular-blockeditor

2. 创建组件

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. 导入 CSS

安装与应用相匹配的主题包。此示例使用 Material 3：

npm install @syncfusion/ej2-material3-theme

在 src/styles.css 中添加以下样式表。

@import '../node_modules/@syncfusion/ej2-material3-theme/styles/blockeditor/index.css';

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

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

---

常见模式

模式 1：文档自动保存

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

模式 2：导出格式化文档

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

---

故障排除指南

问题：编辑器未显示

解决方案：确保在 main.ts 或全局样式中导入了 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';

问题：内容未保存

解决方案：使用 getDataAsJson() 方法获取内容

const content = this.blockEditor.getDataAsJson();

问题：事件未触发

解决方案：确保组件是独立组件，且导入正确

@Component({
  standalone: true,
  imports: [BlockEditorModule]
})

---