syncfusion-blazor-smart-rich-text-editor

Syncfusion Blazor Smart Rich Text Editor

一份全面的技能指南，用于实现和配置 Syncfusion Blazor Smart Rich Text Editor（SfSmartRichTextEditor）——一款 AI 驱动的所见即所得编辑器，在功能完备的 SfRichTextEditor 基础上扩展了智能内容辅助功能。支持 OpenAI、Azure OpenAI、Ollama 和自定义 AI 后端。提供 Smart Action 下拉工具栏、AI 查询对话框（Alt+Enter），以及可通过 AssistViewSettings 完全自定义的 AI 助手弹出窗口。

何时使用此技能

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

• 在 Blazor Server 或 Web App 项目中安装并设置 SfSmartRichTextEditor
• 配置 AI 后端：OpenAI、Azure OpenAI、Ollama 或自定义 IChatClient
• 在 Program.cs 中注册 IChatInferenceService / SyncfusionAIService
• 使用 Smart Action 下拉工具栏执行 AI 命令（总结、扩展、调整语气）
• 向 ToolbarItemModel 列表添加 Name = "AI Commands" 和 Name = "AI Query"，以呈现 AI 工具栏按钮
• 使用 Alt+Enter 打开 AI Query 对话框，输入自由格式的 AI 提示词
• 配置 AssistViewSettings：Commands、Suggestions、Prompts、Placeholder、MaxPromptHistory、弹出窗口尺寸
• 自定义 AI 助手弹出窗口（BannerTemplate、HeaderToolbarSettings、PromptToolbarSettings、ResponseToolbarSettings）
• 处理 AI 事件：AIPromptRequested、AIResponseStopped、AIToolbarItemClicked、AIPopupOpening、AIPopupClosing
• 使用 AI 助手方法：ShowAIPopupAsync、HideAIPopupAsync、ExecuteAIPromptAsync、UpdateAIResponseAsync、GetAIPromptHistoryAsync、ClearAIPromptHistoryAsync
• 为 AI 助手弹出窗口设置样式或动画（.e-rte-aiquery-dialog）
• 使用 SfRichTextEditor 继承的全部功能：工具栏、图片、表格、事件、方法、数据绑定、粘贴清理、导入/导出、无障碍功能

快速开始

1. 安装 NuGet 包：

dotnet add package Syncfusion.Blazor.SmartRichTextEditor
dotnet add package Syncfusion.Blazor.Themes
dotnet add package Microsoft.Extensions.AI
dotnet add package Microsoft.Extensions.AI.OpenAI

2. 在 Program.cs 中注册服务：

using Syncfusion.Blazor;
using Syncfusion.Blazor.AI;
using Microsoft.Extensions.AI;
using OpenAI;

builder.Services.AddSyncfusionBlazor();

string openAIApiKey = "YOUR_API_KEY";
string openAIModel = "gpt-4";
OpenAIClient openAIClient = new OpenAIClient(openAIApiKey);
IChatClient chatClient = openAIClient.GetChatClient(openAIModel).AsIChatClient();
builder.Services.AddChatClient(chatClient);
builder.Services.AddSingleton<IChatInferenceService, SyncfusionAIService>();

3. 添加到 _Imports.razor：

@using Syncfusion.Blazor
@using Syncfusion.Blazor.SmartRichTextEditor

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

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

5. 添加组件：

@rendermode InteractiveServer

<SfSmartRichTextEditor>
    <h2>Welcome to Smart Rich Text Editor</h2>
    <p>Select text and use the Smart Action toolbar, or press Alt+Enter to open the AI Query dialog.</p>
    <AssistViewSettings Placeholder="Ask AI to rewrite or generate content." />
</SfSmartRichTextEditor>

导航指南

开始使用和 AI 服务设置

📄 阅读： references/getting-started.md

• NuGet 安装：Syncfusion.Blazor.SmartRichTextEditor + Syncfusion.Blazor.Themes
• Blazor Server App（Visual Studio 和 VS Code）及 Blazor Web App（.NET 8+）的完整设置说明
• 在 Program.cs 中配置 OpenAI、Azure OpenAI、Ollama 和自定义 IChatClient
• Web App 的 AddInteractiveServerComponents() 注册模式
• CSS 主题和 JS 脚本引用（.NET 6 至 .NET 10）
• 使用 AssistViewSettings 添加组件
• 内容获取方法（GetTextAsync、GetCharCountAsync）
• 常见设置问题及解决方法

AI 后端配置

📄 阅读： references/ai-backends.md

• OpenAI：API 密钥、支持的模型（gpt-4-turbo、gpt-4、gpt-3.5-turbo）、OpenAIClient 设置、环境变量和 User Secrets
• Azure OpenAI：资源部署、AzureOpenAIClient + ApiKeyCredential、appsettings.json 配置、托管标识（生产环境推荐）、HIPAA/SOC 2 合规性、监控、成本优化
• Ollama：本地模型安装（mistral、llama2）、OllamaApiClient + OllamaSharp NuGet 包、Docker Compose、GPU 加速、模型建议
• 自定义 IChatClient：为内部/专有 AI 实现 IChatClient、在 Program.cs 中注册、流式响应、重试逻辑、错误处理、企业 AI API 示例

AssistViewSettings — 属性

📄 阅读： references/assist-view-settings.md

• Commands（List<AICommands>）：智能操作下拉菜单，包含嵌套子命令和图标 CSS
• PopupMaxHeight / PopupWidth：控制弹出窗口尺寸（CSS 值或像素数值）
• Placeholder：AI 提示词文本区域中的占位文本
• Prompts（List<AssistViewPrompt>）：加载到弹出窗口中的预定义提示词/响应模板
• Suggestions（List<string>）：AI 弹出窗口中显示的快速建议标签
• MaxPromptHistory：保留的对话条目上限（默认值：20）
• BannerTemplate：AI 弹出窗口的自定义品牌标识/页眉 RenderFragment
• HeaderToolbarSettings / PromptToolbarSettings / ResponseToolbarSettings：使用 AssistViewToolbarItem 自定义工具栏

AssistViewSettings — 事件

📄 阅读： references/ai-events.md

• AIPromptRequested（AssistViewPromptRequestedEventArgs）：在调用 AI 前拦截/修改提示词；设置 Cancel=true 以阻止调用；修改 Response、PromptSuggestions、ResponseToolbarItems
• AIResponseStopped（ResponseStoppedEventArgs）：用户点击了“停止响应”；提供 DataIndex 和 Prompt
• AIToolbarItemClicked（AssistViewToolbarItemClickedEventArgs）：处理自定义工具栏按钮点击；访问 Item、DataIndex、Event；设置 Cancel=true
• AIPopupOpening（BeforeOpenEventArgs）：使用 args.Cancel = true 取消打开弹出窗口；访问 Element 引用
• AIPopupClosing（BeforeCloseEventArgs）：取消关闭弹出窗口；访问 ClosedBy、IsInteracted、PreventFocus

AssistViewSettings — 方法

📄 阅读： references/ai-methods.md

• ShowAIPopupAsync()：以编程方式打开 AI 助手弹出窗口
• HideAIPopupAsync()：关闭 AI 助手弹出窗口
• ExecuteAIPromptAsync(string prompt)：以编程方式发送提示词（效果如同用户输入）
• UpdateAIResponseAsync(string response, bool isFinalUpdate)：流式传输或注入 AI 响应；设置 isFinalUpdate=true 以隐藏“停止”按钮
• GetAIPromptHistoryAsync()：以 AssistViewPrompt[] 的形式获取所有已保存的提示词/响应（按时间顺序排列，数量受 MaxPromptHistory 限制）
• ClearAIPromptHistoryAsync()：重置所有对话历史记录
• 完整示例：通过 @ref 结合使用全部六个方法

AI 弹出窗口外观与 CSS

📄 阅读： references/ai-appearance.md

• AI 弹出窗口的 CSS 选择器：.e-rte-aiquery-dialog、.e-aiassistview
• 自定义弹出窗口背景、边框、阴影
• 针对 .e-view-header、.e-view-content .e-toolbar、.e-footer 子区域进行精细控制
• 完整的自定义弹出窗口样式示例

工具栏配置

📄 阅读： references/toolbar.md

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

内置工具栏工具参考

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

• SfSmartRichTextEditor 的默认工具栏项目
• AI 专用工具栏项目 — Name = "AI Commands"（智能操作下拉菜单）和 Name = "AI Query"（询问 AI 按钮）；必须使用 Name 属性，而非 ToolbarCommand 枚举
• ToolbarCommand 枚举值完整列表
• 文本格式、字体与样式、对齐方式、列表、超链接
• 使用 SfSmartRichTextEditor 的图片/表格/链接快速工具栏项目命令
• 撤销/重做、全屏、打印、源代码、预览工具
• 移除或重新排列默认工具栏项目

文本格式

📄 阅读： 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）

事件（RTE）

📄 阅读： 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 类参考，包含所有属性

方法（RTE）

📄 阅读： references/methods.md

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

属性（RTE）

📄 阅读： references/properties.md

• 内容和值：Value、Placeholder、Readonly、Enabled、MaxLength、ShowCharCount
• 编辑器行为：EditorMode、EnterKey、ShiftEnterKey、EnableTabKey、EnableAutoUrl、EnableMarkdownAutoFormat、EnableClipboardCleanup、EnableXhtml、EnableHtmlEncode、EnableResize
• 外观和布局：Height、Width、CssClass、ShowTooltip、FloatingToolbarOffset
• IFrame 模式：包含 Enable、Attributes、Resources 的 RichTextEditorIFrameSettings 子组件
• 安全和清理：EnableHtmlSanitizer、AdditionalSanitizeAttributes、AdditionalSanitizeTags、DeniedSanitizeSelectors
• 键盘和快捷键：KeyConfigure，包含完整的 ShortcutKeys 默认绑定表
• 持久化和自动保存：EnablePersistence、SaveInterval、AutoSaveOnIdle
• 撤销/重做配置：UndoRedoSteps、UndoRedoTimer
• HTTP 集成：HttpClientInstance
• 完整的 38 个属性摘要表

数据绑定和值管理

📄 阅读： 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 验证

常见模式

带 AI 的基础智能富文本编辑器

@rendermode InteractiveServer
@using Syncfusion.Blazor.SmartRichTextEditor

<SfSmartRichTextEditor @bind-Value="@Content">
    <AssistViewSettings Placeholder="Ask AI to rewrite or generate content." />
</SfSmartRichTextEditor>

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

使用自定义智能操作命令的 AI

<SfSmartRichTextEditor>
    <AssistViewSettings Commands="@MyCommands" Suggestions="@QuickSuggestions" />
</SfSmartRichTextEditor>

@code {
    private List<AICommands> MyCommands = new()
    {
        new AICommands { Text = "Summarize", Prompt = "Summarize this content concisely" },
        new AICommands { Text = "Expand", Prompt = "Add more details and examples" },
        new AICommands
        {
            Text = "Translate",
            Items = new List<AICommands>
            {
                new AICommands { Text = "To French", Prompt = "Translate to French" },
                new AICommands { Text = "To Spanish", Prompt = "Translate to Spanish" }
            }
        }
    };

    private List<string> QuickSuggestions = new()
    {
        "Fix grammar", "Make shorter", "More formal", "Simplify"
    };
}

以编程方式控制 AI 弹出窗口

<SfSmartRichTextEditor>
    <AssistViewSettings @ref="AssistViewRef" MaxPromptHistory="10" />
</SfSmartRichTextEditor>
<button @onclick="OpenAI">Open AI</button>
<button @onclick="RunPrompt">Run Prompt</button>

@code {
    private AssistViewSettings AssistViewRef;

    private async Task OpenAI() =>
        await AssistViewRef.ShowAIPopupAsync();

    private async Task RunPrompt() =>
        await AssistViewRef.ExecuteAIPromptAsync("Improve the clarity of this text");
}

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

<SfSmartRichTextEditor @bind-Value="@HtmlContent" ShowCharCount="true" MaxLength="2000">
    <AssistViewSettings Placeholder="Ask AI for writing help." />
</SfSmartRichTextEditor>

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

只读显示

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

Markdown 编辑器模式

<SfSmartRichTextEditor EditorMode="EditorMode.Markdown" @bind-Value="@MarkdownContent">
    <AssistViewSettings Placeholder="Ask AI to help with your Markdown content." />
</SfSmartRichTextEditor>

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

处理 AI 提示词事件以拦截请求

<SfSmartRichTextEditor>
    <AssistViewSettings AIPromptRequested="OnAIPrompt" />
</SfSmartRichTextEditor>

@code {
    private async Task OnAIPrompt(AssistViewPromptRequestedEventArgs args)
    {
        // Log, validate, or modify args.Prompt before it is sent to AI
        Console.WriteLine($"Prompt: {args.Prompt}");
        // To cancel: args.Cancel = true;
    }
}