syncfusion-blazor-rich-text-editor

Syncfusion Blazor 富文本编辑器

一份全面的技能指南，介绍如何实现和配置 Syncfusion Blazor Rich Text Editor（SfRichTextEditor）——一款功能齐全的所见即所得编辑器，支持 HTML 和 Markdown 编辑、丰富的工具栏自定义、媒体插入、表格、数据绑定、导入/导出和无障碍访问。

何时使用此技能

用户需要以下操作时，请使用此技能：

• 在 Blazor Server、WebAssembly 或 Web App 项目中安装和设置 SfRichTextEditor
• 配置工具栏项、工具栏类型（Expand、MultiRow、Scrollable、Popup）或工具栏位置
• 设置文本格式：粗体/斜体/下划线、标题、列表、对齐方式、颜色、字体、行高
• 插入和管理图片、视频或音频，并支持上传
• 使用表格：插入、调整大小、合并单元格、自定义快速工具栏
• 在 HTML、Markdown 或 IFrame 编辑器模式之间切换
• 启用内联编辑（内联工具栏）
• 添加自定义工具栏工具或使用 exec 命令
• 处理 RTE 事件（ValueChange、OnActionBegin、图片上传事件等）
• 使用 @bind-Value 双向绑定内容，或通过 GetTextAsync 获取内容
• 配置粘贴清理行为
• 从 Word 导入，或导出到 Word 或 PDF
• 实现无障碍访问、键盘快捷键、RTL 或全球化

快速开始

1. 安装 NuGet 包：

dotnet add package Syncfusion.Blazor.RichTextEditor
dotnet add package Syncfusion.Blazor.Themes

2. 在 Program.cs 中注册：

using Syncfusion.Blazor;
builder.Services.AddSyncfusionBlazor();

3. 添加到 _Imports.razor：

@using Syncfusion.Blazor
@using Syncfusion.Blazor.RichTextEditor

4. 在 index.html（WASM）或 App.razor（Server）中添加 CSS/JS：

<link href="_content/Syncfusion.Blazor.Themes/bootstrap5.css" rel="stylesheet" />
<script src="_content/Syncfusion.Blazor.Core/scripts/syncfusion-blazor.min.js"></script>

5. 添加组件：

<SfRichTextEditor @bind-Value="@Content">
    <RichTextEditorToolbarSettings Items="@Tools" />
</SfRichTextEditor>

@code {
    private string Content { get; set; } = "<p>Start editing...</p>";

    private List<ToolbarItemModel> Tools = new()
    {
        new() { Command = ToolbarCommand.Bold },
        new() { Command = ToolbarCommand.Italic },
        new() { Command = ToolbarCommand.Underline },
        new() { Command = ToolbarCommand.Separator },
        new() { Command = ToolbarCommand.Formats },
        new() { Command = ToolbarCommand.Alignments },
        new() { Command = ToolbarCommand.OrderedList },
        new() { Command = ToolbarCommand.UnorderedList },
        new() { Command = ToolbarCommand.Separator },
        new() { Command = ToolbarCommand.CreateLink },
        new() { Command = ToolbarCommand.Image },
        new() { Command = ToolbarCommand.CreateTable },
        new() { Command = ToolbarCommand.Separator },
        new() { Command = ToolbarCommand.Undo },
        new() { Command = ToolbarCommand.Redo }
    };
}

导航指南

入门与设置

📄 阅读： references/getting-started.md

• 适用于所有项目类型的 NuGet 安装（Visual Studio、VS Code、.NET CLI）
• 服务注册和命名空间导入
• CSS 主题和 JS 脚本引用
• 在页面中添加第一个组件
• 以 HTML、纯文本或字符数的形式获取内容

工具栏配置

📄 阅读： references/toolbar.md

• 使用 RichTextEditorToolbarSettings.Enable 启用或禁用工具栏
• 工具栏类型：Expand、MultiRow、Scrollable、Popup
• 浮动工具栏和偏移量配置
• 工具栏位置（顶部或底部）
• 使用 ToolbarItemModel 配置工具栏项
• 自定义工具栏项（基于模板）

内置工具栏工具参考

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

• 所有 ToolbarCommand 枚举值的完整列表
• 文本格式、字体与样式、对齐方式、列表、超链接
• 图片/表格/链接快速工具栏项命令
• 撤销/重做、全屏、打印、源代码、预览工具
• 移除或重新排列默认工具栏项

文本格式

📄 阅读： references/text-formatting.md

• 粗体、斜体、下划线、删除线、下标、上标、内联代码
• 文本对齐（左对齐、居中、右对齐、两端对齐）
• 使用自定义编号和项目符号样式的有序/无序列表
• 标题格式（H1–H6、段落、引用块、代码）
• 行高配置
• 水平线、格式刷、清除格式
• Markdown 自动格式（内联和块级快捷方式）

图片、视频和音频

📄 阅读： references/images-and-media.md

• 从本地计算机或 URL 插入图片
• RichTextEditorImageSettings：SaveUrl、Path、AllowedTypes、EnableResize
• Base64 与服务器端上传
• 图片快速工具栏配置
• 视频和音频插入及设置

表格

📄 阅读： references/tables.md

• 使用 CreateTable 工具栏项创建表格
• RichTextEditorTableSettings：宽度、调整大小、自定义样式
• 表格快速工具栏：添加/删除行和列、合并单元格、属性
• 高级表格操作（单元格选择、拆分、自定义边框）

编辑器模式

📄 阅读：references/editor-modes.md

• HTML 编辑器模式（默认所见即所得）
• Markdown 编辑器模式（EditorMode.Markdown）
• IFrame 与 DIV 渲染模式
• 切换源代码视图

内联模式

📄 阅读：references/inline-mode.md

• 启用内联工具栏（InlineMode）
• 选中文本时显示内联工具栏
• 使用场景：评论编辑器、原位内容编辑

自定义工具与执行命令

📄 阅读：references/custom-tools.md

• 使用 ToolbarItemModel 和模板添加自定义工具栏按钮
• 使用 ExecuteCommandAsync 以编程方式执行命令
• 配置斜杠命令（/ 触发菜单）
• 格式刷高级设置（RichTextEditorFormatPainterSettings）

事件

📄 阅读：references/events.md

• RichTextEditorEvents 子组件的用法和连接模式
• 生命周期事件：Created、Destroyed
• 焦点/交互事件：Focus、Blur、OnToolbarClick、SelectionChanged
• 内容事件：ValueChange、BeforePasteCleanup、AfterPasteCleanup
• 工具栏生命周期：OnActionBegin、OnActionComplete
• 对话框事件：OnDialogOpen、DialogOpened、OnDialogClose、DialogClosed
• 快速工具栏：OnQuickToolbarOpen、QuickToolbarOpened、QuickToolbarClosed
• 图像事件：OnImageSelected、BeforeUploadImage、OnImageUploadSuccess、OnImageUploadFailed、ImageUploadChange、OnImageDrop、ImageDelete
• 媒体事件：FileSelected、FileUploading、FileUploadSuccess、FileUploadFailed、FileUploadChange、OnMediaDrop、MediaDeleted
• 调整大小事件：OnResizeStart、OnResizeStop
• 工具栏状态：UpdatedToolbarStatus
• 导出事件：OnExport、OnExportFailure
• 斜杠菜单：SlashMenuItemSelecting
• 完整的 EventArgs 类参考，包含所有属性

方法

📄 阅读：references/methods.md

• 焦点与选择：FocusAsync、FocusOutAsync、SaveSelectionAsync、RestoreSelectionAsync、SelectAllAsync、GetSelectionAsync
• 内容获取：GetTextAsync、GetSelectedHtmlAsync、GetCharCountAsync、GetXhtmlAsync
• 命令执行：所有带类型化参数的 ExecuteCommandAsync 重载（图像、链接、表格、视频、音频、代码块、格式刷）
• 工具栏控制：EnableToolbarItem、DisableToolbarItem、RemoveToolbarItem
• 对话框与 UI 控制：ShowDialogAsync、CloseDialogAsync、ShowFullScreenAsync、PrintAsync、RefreshUIAsync、ShowSourceCodeAsync
• 撤销/重做：ClearUndoRedoAsync
• 完整的 CommandName、ToolbarCommand 和 DialogType 枚举参考

属性

📄 阅读：references/properties.md

• 内容与值：Value、Placeholder、Readonly、Enabled、MaxLength、ShowCharCount
• 编辑器行为：EditorMode、EnterKey、ShiftEnterKey、EnableTabKey、EnableAutoUrl、EnableMarkdownAutoFormat、EnableClipboardCleanup、EnableXhtml、EnableHtmlEncode、EnableResize、EnableChunkMessages
• 外观与布局：Height、Width、CssClass、ShowTooltip、FloatingToolbarOffset
• 安全与净化：EnableHtmlSanitizer、AdditionalSanitizeAttributes、AdditionalSanitizeTags、DeniedSanitizeSelectors
• 键盘与快捷键：KeyConfigure，以及完整的 ShortcutKeys 默认绑定表
• 持久化与自动保存：EnablePersistence、SaveInterval、AutoSaveOnIdle
• 撤销/重做配置：UndoRedoSteps、UndoRedoTimer
• HTTP 集成：HttpClientInstance
• 完整的 37 项属性摘要表

数据绑定与值管理

📄 阅读：references/data-binding.md

• 使用 @bind-Value 进行双向绑定
• 单向绑定和以编程方式更新值
• 使用 ValueChange 事件检测编辑
• 只读模式（Readonly 属性）
• 强制执行最大长度限制并显示字符数

粘贴清理

📄 阅读： references/paste-and-cleanup.md

• RichTextEditorPasteCleanupSettings 配置
• 粘贴时剥离或保留特定 HTML 属性和样式
• 强制以纯文本粘贴
• Enter 键行为（EnterKey、ShiftEnterKey）
• 撤销/重做管理器配置

导入与导出

📄 阅读： references/import-export.md

• 将 Word 文档导入编辑器
• 将内容导出为 Word（.docx）和 PDF
• 导入/导出服务的 HTTP 客户端配置
• 使用动态数据进行邮件合并
• 针对大型文档的 WebAssembly 性能优化

无障碍与全球化

📄 阅读： references/accessibility-globalization.md

• WCAG 2.1 合规详情
• 键盘快捷键和导航参考
• ARIA 角色和屏幕阅读器支持
• RTL 布局（EnableRtl）
• 本地化和区域性配置
• XHTML 验证

常见模式

带字符计数的双向绑定编辑器

<SfRichTextEditor @bind-Value="@HtmlContent" ShowCharCount="true" MaxLength="2000">
</SfRichTextEditor>

@code {
    private string HtmlContent { get; set; } = string.Empty;
}

只读显示

<SfRichTextEditor Value="@HtmlContent" Readonly="true">
    <RichTextEditorToolbarSettings Enable="false" />
</SfRichTextEditor>

Markdown 编辑器模式

<SfRichTextEditor EditorMode="EditorMode.Markdown" @bind-Value="@MarkdownContent">
</SfRichTextEditor>

@code {
    private string MarkdownContent { get; set; } = "**Hello** world!";
}