syncfusion-vue-blockeditor

Syncfusion Vue BlockEditor 组件

Syncfusion Vue BlockEditor 是一款功能强大的块式内容编辑器，用户可以使用各种块类型创建、格式化和组织内容。本指南将带你了解如何使用 Vue 3 Composition API 实现 BlockEditor 组件，涵盖全部 14 种块类型、菜单、方法、事件和高级功能。

组件概览

Vue BlockEditor 组件提供：

• 14 种块类型： 段落、标题（1-4 级）、无序列表、有序列表、清单、代码、图片、表格、引用、提示框、分隔线、可折叠块（段落/标题）、模板
• 5 种内容类型： 文本、链接、提及、标签、行内代码
• 4 种交互式菜单： 斜杠命令（/）、上下文菜单（右键）、块操作菜单、行内工具栏
• 拖放： 使用拖动手柄直观地重新排列块
• 20 多种方法： 块的增删改查、选择、数据导出（JSON/HTML）、格式设置
• 14 种事件： 块变更、拖放、粘贴、文件上传、焦点/失焦
• 高级功能： 语法高亮、图片上传、表格编辑、撤销/重做、键盘快捷键
• 主题自定义： 覆盖 --color-sf-* CSS 变量、指定 CSS 类/ID，或使用 Syncfusion Theme Studio 完全自定义主题

文档与导航指南

入门与安装

📄 阅读： references/getting-started.md

• Vue 3 + Vite 项目设置
• Node.js 18+ 先决条件
• 安装包（@syncfusion/ej2-vue-blockeditor）
• 使用 Tailwind 3 导入 CSS 主题
• 注册组件并进行基本初始化
• 运行应用程序

块类型与结构

📄 阅读： references/block-types.md

• 全部 14 种块类型及示例
• BlockModel 结构（id、blockType、content、properties）
• 配置块属性
• 自定义模板
• 自定义缩进和 CSS 类
• 块类型选择指南

行内内容与格式设置

📄 阅读： references/inline-content.md

• ContentModel 结构
• 5 种内容类型（文本、链接、提及、标签、行内代码）
• 行内样式（粗体、斜体、下划线、删除线、颜色、背景）
• 链接属性和 URL 配置
• 使用 users 数组设置用户提及
• 使用触发字符配置标签
• 行内格式设置示例

排版块

📄 阅读： references/typography-blocks.md

• 带占位符的段落块
• 标题块（1-4 级）
• 选择标题级别
• 用于分隔章节的分隔线块
• 自定义占位符
• 排版示例

列表块

📄 阅读： references/list-blocks.md

• 无序列表（项目符号列表）
• 有序列表（编号列表）
• 带 isChecked 状态的清单
• 自定义列表占位符
• 交互式清单示例

嵌套块与可折叠块

📄 阅读： references/nested-blocks.md

• 用于嵌套结构的 Children 属性
• 父子关系（parentId）
• 可折叠标题（1-4 级）
• 可折叠段落块
• 配置 isExpanded 状态
• 支持多行内容的引用块
• 用于重要信息的提示框
• 嵌套块示例

特殊块（代码、图片、表格）

📄 阅读： references/special-blocks.md

• 带语法高亮的代码块
• codeBlockSettings（语言、defaultLanguage）
• 支持上传和调整大小的图片块
• imageBlockSettings（saveUrl、path、maxFileSize、allowedTypes）
• 包含行、列和单元格的表格块
• 表格属性（width、enableHeader、enableRowNumbers）
• 调整表格大小和选择多行/多列
• 文件上传配置

编辑器菜单和工具栏

📄 阅读： references/editor-menus.md

• 斜杠命令菜单（/ 触发）- commandMenuSettings
• 上下文菜单（右键单击）- contextMenuSettings
• 块操作菜单（悬停时显示拖动手柄）- blockActionMenuSettings
• 内联工具栏（选中文本时显示）- inlineToolbarSettings
• 块类型转换的转换设置
• 字体颜色和背景颜色设置
• 菜单自定义和事件
• 自定义菜单项

方法和编程控制

📄 阅读： references/methods-api.md

• 块管理：addBlock()、removeBlock()、updateBlock()、moveBlock()
• 选择：setSelection()、getSelectedBlocks()、selectBlock()、selectAllBlocks()
• 光标：setCursorPosition()、focusIn()、focusOut()
• 数据导出：getDataAsJson()、getDataAsHtml()、print()
• 格式设置：executeToolbarAction()、enableToolbarItems()、disableToolbarItems()
• HTML 解析：parseHtmlToBlocks()、renderBlocksFromJson()
• 使用 Composition API 模式调用方法

事件和生命周期

📄 阅读： references/events-lifecycle.md

• 块更改事件：blockChanged
• 拖放：blockDragStart、blockDragging、blockDropped
• 焦点事件：focus、blur
• 选择：selectionChanged
• 粘贴：beforePasteCleanup、afterPasteCleanup
• 文件上传：beforeFileUpload、fileUploading、fileUploadSuccess、fileUploadFailed
• 创建事件
• 使用 Composition API 的事件处理程序模式

功能和配置

📄 阅读： references/features-configuration.md

• 拖放：enableDragAndDrop
• 粘贴清理：pasteCleanupSettings（deniedTags、keepFormat、plainText）
• 撤销/重做：undoRedoStack（默认值：30）
• 键盘快捷键：自定义 keyConfig
• 只读模式：readOnly
• 持久化：enablePersistence
• 自定义样式：cssClass
• 高度/宽度：height、width
• 主题自定义：覆盖默认 CSS、--color-sf-* CSS 变量、CSS 类/ID（.e-blockeditor、.e-active、.e-selected、.e-list-item、.e-dropdownbase、.e-table-element、#blockeditor_contextmenu、#blockeditor_code-ddl_popup）、多主题切换示例（Slate Light、Sage Green、Dark Pro）以及 Syncfusion Theme Studio

协作编辑

📄 阅读： references/collaborative-editing.md

• 使用 Yjs CRDT 框架进行实时协作编辑
• 包含 WebSocket 服务设置的 6 步快速入门指南
• Yjs 提供程序（y-websocket、y-webrtc、y-indexeddb、Hocuspocus、Liveblocks、PartyKit）
• 协作配置文件，包含房间分配逻辑（基于 URL 哈希）
• collaborationSettings 配置（adapter、provider、enableAwareness、versionHistory）
• 使用 enableAwareness 显示用户状态和远程光标
• 使用 users 数组和 currentUserId 标识用户
• 使用 IndexedDB 存储版本历史记录，支持快照、还原、比较、导出/导入
• 快照生命周期事件（snapshotCreated、snapshotRestored）
• 版本历史记录 UI 面板示例，包含完整实现代码

无障碍访问和全球化

📄 阅读： references/accessibility-globalization.md

• 符合 WCAG 2.2 和 Section 508 标准
• WAI-ARIA 属性
• 键盘导航快捷键
• 本地化：使用 L10n 的 locale 属性
• RTL 支持：enableRtl
• 安全性：enableHtmlSanitizer（防止 XSS）、enableHtmlEncode
• 本地化示例（德语、阿拉伯语等）

快速入门示例

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

npm install @syncfusion/ej2-tailwind3-theme

<template>
  <div>
    <ejs-blockeditor 
      ref="blockEditor"
      :blocks="blocks"
      :users="users"
      :enableDragAndDrop="true"
      @blockChanged="onBlockChanged"
    />
  </div>
</template>

<script setup>
import { ref } from 'vue';
import { BlockEditorComponent as EjsBlockeditor, ContentType } from '@syncfusion/ej2-vue-blockeditor';

const blockEditor = ref(null);

const blocks = [
  {
    id: 'heading-1',
    blockType: 'Heading',
    properties: { level: 1 },
    content: [
      { contentType: ContentType.Text, content: 'Welcome to BlockEditor' }
    ]
  },
  {
    id: 'intro-para',
    blockType: 'Paragraph',
    content: [
      { contentType: ContentType.Text, content: 'Create content using blocks. Type ' },
      { contentType: ContentType.Text, content: '/', properties: { styles: { bold: true } } },
      { contentType: ContentType.Text, content: ' for commands.' }
    ]
  },
  {
    id: 'checklist-1',
    blockType: 'Checklist',
    properties: { isChecked: false },
    content: [
      { contentType: ContentType.Text, content: 'Complete the tutorial' }
    ]
  }
];

const users = [
  { id: 'user1', user: 'John Doe' },
  { id: 'user2', user: 'Jane Smith' }
];

const onBlockChanged = (args) => {
  console.log('Block changed:', args.changes);
};
</script>

<style>
@import '../node_modules/@syncfusion/ej2-tailwind3-theme/styles/blockeditor/index.css';
</style>