syncfusion-maui-rich-text-editor

实现 Syncfusion .NET MAUI 富文本编辑器

Syncfusion .NET MAUI 富文本编辑器（SfRichTextEditor）可提供强大的 WYSIWYG 编辑体验，帮助创建格式丰富的文本内容。它提供全面的格式设置工具、可自定义工具栏、图像和表格插入、超链接管理，并返回有效的 HTML 标记。本技能将指导你为消息应用、邮件编辑器、博客编辑器、笔记应用以及任何需要输入带格式文本的场景实现富文本编辑器。

何时使用此技能

在以下场景中使用此技能：

• 在 .NET MAUI 应用中实现 WYSIWYG 文本编辑器，并支持格式设置
• 创建邮件编辑器或消息应用，支持富文本格式（粗体、斜体、列表等）
• 构建博客编辑器、CMS 界面或论坛帖子编辑器，并生成 HTML 输出
• 添加笔记或文档编辑功能，并提供格式设置工具栏
• 启用反馈表单、评价区域或评论区，支持丰富内容
• 实现可在内容中嵌入图像、表格、超链接和代码块的文本编辑器
• 在技术文档、博客文章或面向开发者的应用中嵌入格式化代码片段
• 针对特定编辑场景自定义工具栏项和外观
• 将工具栏项分组到上下文感知的浮层菜单中，打造移动优先的编辑体验
• 对用户选区应用文本大小写转换（大写、小写），或通过 Uppercase() 和 Lowercase() 方法以编程方式转换
• 将编辑器绑定到带类型的块架构模型（TValue="Schema"），而不是 HTML，以支持结构化文档工作流
• 通过粗体、斜体、对齐、颜色等方法以编程方式处理格式化文本
• 通过事件管理用户交互（文本更改、超链接点击、格式更改）
• 使用 Task<string> GetText() 方法以编程方式读取编辑器中的纯文本，用于字符数／字数统计、搜索索引、复制到剪贴板、文本转语音、导出为 SMS、翻译和拼写检查
• 应用自动调整大小或 Liquid Glass Effect 等高级功能，打造现代化 UI

组件概述

• WYSIWYG 编辑 - 所见即所得的格式化文本界面
• 全面的格式设置 - 粗体、斜体、下划线、删除线、字体、颜色、对齐、列表、缩进
• 可自定义工具栏 - 丰富且可配置的工具栏，支持显示／隐藏和自定义项
• 图像和表格 - 无缝插入并设置图像和表格的格式
• 超链接支持 - 插入、编辑和移除超链接，并支持点击事件
• 代码块支持 - 插入格式化代码片段，同时保留结构和可读性
• 编程式控制 - 提供应用格式、管理内容和控制编辑器状态的方法
• 事件 - FormatChanged、TextChanged、HyperlinkClicked、Focused／Unfocused，支持响应式 UI
• HTML 输出 - 返回有效的 HTML 标记，以便存储或传输
• AutoSize - 根据内容动态调整高度
• Liquid Glass Effect - 现代 Cupertino 风格的视觉效果（iOS／macOS）

公共 API 契约

• Value 属性是唯一的公共内容接口。其类型为 object，因此读取时务必将其强制转换为预期的运行时类型：
  • HTML 模式（TValue="HTML"）：强制转换为 string
  • Schema 模式（TValue="Schema"）：强制转换为 ObservableCollection<BlockNode>
• 若要读取纯文本，请使用 SfRichTextEditor 上的公共方法 Task<string> GetText()，不要自行移除 HTML。无论使用 HTML 模式还是 Schema 模式，该方法始终返回经 await 获取的纯文本内容。
• 旧版 Text 和 HtmlText 属性为内部属性，不得在应用代码中使用。
• 旧版 DefaultTextColor、DefaultFontSize 和 DefaultFontFamily 属性已弃用；请改用段落级或内联格式设置。

文档与导航指南

入门指南

📄 阅读： references/getting-started.md

• 安装 Syncfusion.Maui.RichTextEditor NuGet 包
• 在 XAML 和 C# 中添加 SfRichTextEditor
• 注册命名空间并进行基本设置
• 启用工具栏（ShowToolbar 属性）
• 使用 ToolbarItems 集合自定义工具栏项
• 首个包含格式化文本的可运行示例

工具栏配置

📄 阅读： references/toolbar.md

• 使用 ToolbarPosition 属性设置工具栏位置（顶部或底部）
• 可用的工具栏项（Bold、Italic、FontFamily、FontSize、列表、图片、表格等）
• 添加或移除特定工具栏项
• 使用分隔符项进行视觉分组
• 行内链接工具提示功能
• 使用 ToolbarSettings 自定义工具栏外观
• 背景色、文本颜色和分隔符样式
• 滚动按钮的可见性和图标自定义
• 特定平台的工具栏行为

工具栏分组

📄 阅读： references/toolbar-grouping.md

• 使用 IsGrouped 属性启用分组（覆盖式）工具栏
• 将每个 ToolbarItems 条目映射到适应上下文的覆盖式分组
• 面向移动设备触控操作的 UX（Android、iOS）
• 为分组布局选择一组精简的工具栏项
• 配合使用 IsGrouped、ToolbarPosition 和 ToolbarSettings
• 使用平台条件切换分组工具栏和行内工具栏
• 排查覆盖式菜单为空或过于拥挤的问题

文本转换

📄 阅读： references/text-transformation.md

• 使用 RichTextToolbarOptions 中的 TextTransform 工具栏项
• 基于选区的大小写转换操作（UPPERCASE、lowercase 等）
• 使用 Separator 分组，将 TextTransform 添加到自定义工具栏
• 使用 Uppercase() 和 Lowercase() 方法，以编程方式转换当前选区
• 将文本转换与粗体、斜体、下划线及其他字符格式结合使用
• 在分组（覆盖式）工具栏中使用 TextTransform
• 实际应用场景：消息应用、评论、博客和 CMS 编辑器
• 关于功能易发现性的故障排除和最佳实践

格式设置和自定义

📄 阅读： references/formatting-and-customization.md

• 自定义编辑器外观（背景、边框、自动换行）
• 以编程方式设置格式的方法（ToggleBold、ToggleItalic、ToggleUnderline 等）
• 字符格式（粗体、斜体、下划线、删除线、下标、上标）
• 列表格式（项目符号列表和编号列表）
• 文本对齐方式（左对齐、右对齐、居中、两端对齐）
• 设置字体、字号、文本颜色和突出显示颜色
• 段落格式和标题样式
• 缩进控制（增加/减少）
• 新内容的默认文本样式

内容管理

📄 阅读： references/content-management.md

• 通过 Value 属性设置纯文本，使用 TValue="HTML"
• 通过 Value 属性设置 HTML 格式文本，使用 TValue="HTML"
• 获取选中的 HTML 内容（GetSelectedText 方法）
• 配置占位文本及其样式
• 以编程方式控制光标（MoveCursorToStart、MoveCursorToEnd）
• 聚焦和取消聚焦方法
• 撤销和重做功能
• 内容操作模式和最佳实践

Schema 块

📄 阅读： references/schema-block.md

• 使用 TValue="Schema" 和 RichTextEditorValueType.Schema 切换内容模型
• 将 ObservableCollection 绑定到 Value 属性
• 支持的节点类型：ParagraphNode、HeadingNode、TextNode、BulletListNode、OrderedListNode、ListItemNode、ImageNode、CodeBlockNode 和 LinkMark
• 双向绑定，使编辑器中的编辑能够更新绑定的集合
• 组合块节点以创建标题、列表、链接、图片和代码块
• 通过块架构加载和保存结构化文档
• 将架构模型与工具栏和其他编辑器功能配合使用
• 排查编辑器内容为空、编辑未生效以及从 HTML 迁移的问题

图片和表格

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

• 图片插入概览和 ImageRequested 事件
• 从图库、文件选择器、流或 URI 插入图片
• RichTextEditorImageSource 配置（格式、大小、源）
• 平台特定权限（MacCatalyst 文件访问）
• 通过工具栏和行列对话框插入表格
• 使用 InsertTable 方法以编程方式插入表格
• 指定表格尺寸
• 图片和表格示例

超链接

📄 阅读： references/hyperlinks.md

• 使用 InsertHyperlink 方法插入超链接
• 显示文本和 URL 参数
• 使用 EditHyperlink 方法编辑现有超链接
• 移除超链接并保留文本（RemoveHyperlink）
• 链接快速工具提示的行为
• 使用 HyperlinkClicked 事件处理链接交互
• 从事件中提取链接 URL 和显示文本
• 超链接管理的用例和模式

代码块

📄 阅读： references/code-blocks.md

• 使用 CodeBlock 工具栏项启用代码块
• 使用 CodeBlockLanguages 属性自定义代码块语言
• 使用 RichTextToolbarItem 和 RichTextToolbarOptions.CodeBlock 设置 XAML 和 C#
• 配置语言下拉菜单（替换或追加自定义语言）
• 使用 Separator 项将代码块与其他格式工具组合
• 技术文档、博客和面向开发者的工具的用例
• 工具栏放置和 HTML 内容往返处理的最佳实践

事件和交互

📄 阅读： references/events-and-interactions.md

• 使用 FormatChanged 事件跟踪格式状态
• TextChanged 事件包含更改前后的 HTML 内容
• HyperlinkClicked 事件包含 URL 和显示文本
• 用于输入状态的 Focused 和 Unfocused 事件
• XAML 和 C# 中的事件订阅模式
• 使用事件更新上下文 UI
• 将事件与程序化格式设置结合使用
• 真实场景中的事件处理示例
• 用于提取纯文本的公共 Task<string> GetText() 方法（请使用此方法，而不要从 Value 中移除 HTML）

高级功能

📄 阅读： references/advanced-features.md

• 使用 EnableAutoSize 属性启用自动调整大小功能
• 根据内容动态调整高度
• 自动调整大小编辑器的布局注意事项
• 使用 EnableLiquidGlassEffect 启用 Liquid Glass 效果（iOS/macOS）
• 平台要求（.NET 10、iOS/macOS 26+）
• Cupertino 主题集成和透明背景
• 自定义工具栏和编辑器的圆角半径
• 用于视觉自定义的主题键
• 组合使用高级功能，打造现代 UI