syncfusion-maui-toolkit-button

实现 .NET MAUI Button

一份全面介绍如何实现和自定义 Syncfusion .NET MAUI Button（SfButton）控件的指南。SfButton 提供丰富的自定义选项，包括图标、背景图像、视觉状态、圆角以及自定义内容支持。

何时使用此指南

在以下情况下使用此指南：

• 在 .NET MAUI 项目中安装和设置 SfButton
• 创建带文本和图标的基本按钮或自定义按钮
• 实现视觉状态（正常、悬停、按下、已选中、禁用）
• 为按钮添加背景图像或自定义内容
• 处理按钮点击事件
• 创建切换/可选按钮
• 应用 RTL（从右到左）支持
• 自定义按钮外观（颜色、字体、边框、内边距）
• 排查与按钮相关的问题

组件概述

Syncfusion .NET MAUI Button（SfButton）是一种自定义按钮控件，在标准 MAUI 按钮的基础上扩展了高级 UI 自定义功能：

主要功能：

• 灵活的样式： 描边、扁平、圆形或图标按钮类型
• 丰富的内容： 图标、背景图像和自定义视图
• 视觉状态： 内置支持悬停、按下、已选中和禁用状态
• 无障碍功能： 支持 RTL 和键盘导航
• 轻松集成： 可通过简单的 XAML 或 C# 实现

文档和导航指南

入门

📄 阅读： references/getting-started.md

适合阅读的场景：安装、初始设置、首次实现

• 安装 NuGet 包（Syncfusion.Maui.Toolkit）
• 在 MauiProgram.cs 中注册处理程序
• 在 XAML 和 C# 中实现基本按钮
• 使用 ImageSource 和 ShowIcon 添加按钮图标
• 使用 BackgroundImageSource 设置背景图像
• 最精简的可运行示例

自定义和样式

📄 阅读： references/customization.md

适合阅读的场景：自定义外观、设置按钮样式、控制布局

• 文本自定义（颜色、大小、字体、对齐方式）
• 背景颜色和边框样式
• 调整圆角和内边距
• 控制大小（宽度、高度）
• 设置图像宽度和位置
• 对齐选项（水平、垂直）
• 完整的样式示例

视觉状态

📄 阅读： references/visual-states.md

适合阅读的场景：基于状态设置样式、悬停效果、切换按钮、交互反馈

• 视觉状态概述（Normal、Hovered、Pressed、Checked、Disabled）
• 实现 VisualStateManager
• 使用 IsCheckable 创建可选/切换按钮
• 自定义各状态的外观
• 处理状态转换
• 完整的状态管理示例

高级功能

📄 阅读： references/advanced-features.md

适合阅读的场景：RTL 支持、现代效果、自定义内容、事件、迁移

• 支持从右到左（RTL）的语言
• 在按钮内添加自定义内容视图
• 处理点击事件（Clicked 事件）
• 高级场景和组合用法
• 从旧版本迁移

故障排除

📄 阅读： references/troubleshooting.md

适合阅读的场景：问题、错误、意外行为、最佳实践

• 常见问题和解决方案
• 处理程序注册错误
• 图像加载问题
• 布局和大小问题
• 视觉状态未更新
• 特定平台的注意事项