syncfusion-blazor-buttons

Syncfusion Blazor 按钮组件

目录

• 何时使用此技能
• 组件概览
• 通用设置和安装
• 文档和导航指南
• 组件通用模式
• 共享配置
• 常见用例

---

组件概览

Syncfusion.Blazor.Buttons 包提供 11 个功能全面的按钮组件：

核心按钮

1. Button (SfButton) - 标准按钮，支持多种类型、样式、图标和状态
2. ButtonGroup (SfButtonGroup) - 支持选择模式的分组按钮控件
3. CheckBox (SfCheckBox) - 三态复选框，具有选中、未选中和不确定状态
4. RadioButton (SfRadioButton) - 用于互斥选择的单选按钮
5. ToggleSwitch (SfSwitch) - 开/关切换开关控件

交互式按钮

6. DropdownMenu (SfDropDownButton) - 带有下拉菜单选项的按钮
7. SplitButton (SfSplitButton) - 带有主要操作和下拉菜单的按钮
8. ProgressButton (SfProgressButton) - 内置进度指示的按钮

浮动操作

9. FloatingActionButton (SfFab) - 圆形浮动操作按钮
10. SpeedDial (SfSpeedDial) - 带有可展开操作项的 FAB（线性/径向）

Chip 组件

11. Chip (SfChip) - 用于标签、筛选器、选择和操作的紧凑元素

包： Syncfusion.Blazor.Buttons 和 Syncfusion.Blazor.SplitButtons

---

通用设置和安装

所有按钮组件的安装和设置流程相同：

NuGet 包

根据组件类型安装所需的包：

# For Button, Chip, FAB, ToggleSwitch
dotnet add package Syncfusion.Blazor.Buttons

# For DropdownMenu, SplitButton, ProgressButton, ButtonGroup, SpeedDial
dotnet add package Syncfusion.Blazor.SplitButtons

# Required theme package
dotnet add package Syncfusion.Blazor.Themes

设置步骤（适用于所有组件）

1. 添加命名空间（~/_Imports.razor）：

@using Syncfusion.Blazor
@using Syncfusion.Blazor.Buttons
@using Syncfusion.Blazor.SplitButtons

2. 注册服务（~/Program.cs）：

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

3. 添加主题和脚本（~/index.html 或 ~/App.razor）：

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

---

文档和导航指南

Button 组件

📄 阅读： references/button-features.md

• 入门和安装
• 基本按钮实现
• 按钮类型（flat、outline、round、primary、toggle）
• 按钮样式（primary、success、info、warning、danger、link）
• 图标及其位置
• 按钮尺寸（small、normal）
• 连按按钮
• 工具提示
• HTML 属性支持
• 原生事件处理

📄 阅读： references/button-styling.md

• CSS 类自定义
• 外观自定义
• 块级按钮
• 圆角
• RTL（从右到左）支持
• 主题集成
• 配色方案和变体
• 响应式设计模式

📄 阅读： references/button-advanced-features.md

• 无障碍功能（符合 WCAG、键盘导航、ARIA 属性）
• 屏幕阅读器支持
• 禁用状态处理
• 切换按钮功能
• Server 与 Web App 实现差异
• 性能优化
• 最佳实践和常见问题

单选按钮组件

📄 阅读： references/radio-button-features.md

• 入门与安装
• 单选按钮的基本实现
• 使用 Name 属性对单选按钮分组
• 标签配置与位置
• 状态和值管理
• 双向数据绑定（@bind-Checked）
• 用于标识的 Value 属性
• 预先选择默认值
• 表单集成模式

📄 阅读： references/radio-button-styling.md

• 使用 CssClass 自定义样式
• HtmlAttributes 字典的用法
• 使用 EnableRtl 支持从右向左的布局
• 禁用状态配置
• 使用 EnablePersistence 存储状态
• 自定义 CSS 类模式
• 主题自定义技巧
• 响应式设计方法

📄 阅读： references/radio-button-advanced-features.md

• ValueChange 事件处理程序
• ChangeArgs 事件数据结构
• CheckedChanged 回调实现
• Created 生命周期事件
• 事件处理模式
• 用于无障碍访问的 ARIA 属性
• 键盘导航支持
• 最佳实践和常见模式

---

复选框组件

📄 阅读： references/checkbox-features.md

• 入门与安装
• 复选框的基本实现
• 复选框状态（选中、未选中、已禁用）
• 标签配置
• Change 事件处理
• 双向数据绑定（@bind-Checked）
• 多个复选框和复选框组
• 不确定（三态）状态

📄 阅读： references/checkbox-styling.md

• CSS 类自定义
• 外观自定义
• 主题集成（Bootstrap5、Material、Fabric、Tailwind）
• 颜色变体（主要、成功、警告、危险）
• 大小自定义
• RTL（从右向左）支持
• 禁用状态外观
• 标签样式与间距

📄 阅读： references/checkbox-advanced-features.md

• 禁用状态处理和条件禁用
• 无障碍访问（WCAG、ARIA 属性、屏幕阅读器）
• 键盘导航（Tab、Space）
• 表单集成与验证
• 状态管理模式
• 最佳实践和常见模式

---

按钮组组件

📄 阅读： references/button-group-features.md

• 入门与安装
• 按钮组的基本实现
• 水平和垂直方向
• 选择模式（单选、多选、无）
• 嵌套按钮组
• 原生事件处理
• 项目配置与数据绑定

📄 阅读： references/button-group-styling.md

• 外观自定义
• 组内按钮类型和样式
• 按钮组中的图标
• 大小变体
• 自定义 CSS 类
• 主题集成

📄 阅读： references/button-group-advanced-features.md

• 无障碍访问功能
• 键盘导航
• 选择状态管理
• 事件处理模式
• 按钮组最佳实践

---

标签组件

📄 阅读： references/chip-features.md

• 入门与安装
• 标签的基本实现
• 标签类型（输入、筛选、选择、操作）
• 图标集成
• 删除功能
• 选择处理
• 事件（click、delete、created、beforeItemRender）
• 动态标签集合
• 从数据源渲染

📄 阅读： references/chip-styling.md

• 外观自定义
• 颜色变体
• 大小选项
• 自定义 CSS 类
• 图标和头像样式
• 主题集成
• 响应式设计

📄 阅读： references/chip-advanced-features.md

• 无障碍访问支持
• 键盘导航
• 自定义模板支持
• 状态管理模式
• 事件处理
• 最佳实践

下拉菜单组件

📄 阅读： references/dropdown-menu-features.md

• 入门与安装
• 下拉菜单的基本实现
• 弹出项配置（文本、ID、图标、分隔线）
• 菜单项中的图标
• 项目单击事件
• 打开和关闭行为
• 位置自定义
• 动态添加/移除项目
• 与 ListView 集成的分组弹出菜单
• 单击项目时打开对话框
• DropdownList 与 DropdownButton 对比

📄 阅读： references/dropdown-menu-styling.md

• 外观自定义
• 符号图标自定义
• 隐藏下拉箭头
• 图标和宽度自定义
• 弹出菜单宽度自定义
• 圆角
• RTL 支持
• 动画效果
• 模板自定义
• 主题集成

📄 阅读： references/dropdown-menu-advanced-features.md

• 无障碍功能
• 禁用状态处理
• 原生事件处理
• 键盘导航
• 焦点管理
• 最佳实践与模式

---

浮动操作按钮（FAB）组件

📄 阅读： references/fab-features.md

• 入门与安装
• FAB 的基本实现
• 位置选项（TopLeft、TopCenter、TopRight、MiddleLeft、MiddleCenter、MiddleRight、BottomLeft、BottomCenter、BottomRight）
• 图标配置
• 内容自定义
• 目标元素绑定
• 单击事件处理
• 显示/隐藏行为
• 可见性控制

📄 阅读： references/fab-styling.md

• 外观样式（primary、success、info、warning、danger）
• 尺寸变体（small、medium、large）
• 图标位置
• 颜色自定义
• CSS 类自定义
• 禁用状态外观
• 主题集成

📄 阅读： references/fab-advanced-features.md

• 无障碍支持
• 键盘导航
• 事件处理模式
• 状态管理
• FAB 使用最佳实践

---

进度按钮组件

📄 阅读： references/progress-button-features.md

• 入门与安装
• 进度按钮的基本实现
• 加载指示器类型和位置（左侧、右侧、顶部、底部、居中）
• 进度状态（Begin、Progress、End、Fail）
• 持续时间配置
• 进度期间的内容自定义
• 事件（OnBegin、Progress、End、Fail）
• 以编程方式停止进度
• 隐藏加载指示器
• 进度跟踪

📄 阅读： references/progress-button-styling.md

• 外观自定义
• 按钮类型和图标
• 进度状态的 CSS 类自定义
• 进度指示器样式
• 加载指示器自定义
• 进度期间的内容变更
• 主题集成

📄 阅读： references/progress-button-advanced-features.md

• 无障碍功能
• 用于调试的跟踪事件
• 原生事件处理
• 状态管理模式
• 错误处理
• 进度按钮最佳实践

---

Speed Dial 组件

📄 阅读： references/speeddial-features.md

• 入门与安装
• SpeedDial 基本实现
• 显示模式（线性、径向）
• 操作项配置
• 位置选项（9 个位置）
• 打开和关闭行为
• 项目点击事件
• 打开模式（悬停、点击）
• 方向选项（上、下、左、右、自动）
• 径向设置（偏移量、方向、起始角度、结束角度）
• 图标配置（打开/关闭图标）

📄 阅读： references/speeddial-styling.md

• 外观自定义
• 图标（打开图标、关闭图标、项目图标）
• 颜色变体
• 项目模板
• CSS 类自定义
• 动画效果
• 主题集成

📄 阅读： references/speeddial-advanced-features.md

• 无障碍支持
• 键盘导航
• 事件处理（所有事件）
• 状态管理模式
• 模态背景
• 最佳实践

---

Split Button 组件

📄 阅读： references/split-button-features.md

• 入门与安装
• Split Button 基本实现
• 下拉菜单项配置
• 主按钮操作
• 项目选择事件
• 项目中的图标
• 分隔线支持
• 打开和关闭行为
• 事件处理

📄 阅读： references/split-button-styling.md

• 外观自定义
• 按钮样式
• 图标和图标位置
• 尺寸变体
• 自定义 CSS 类
• RTL 支持
• 主题集成

📄 阅读： references/split-button-advanced-features.md

• 无障碍功能
• 禁用状态处理
• 键盘导航
• 原生事件处理
• 最佳实践

---

Toggle Switch 组件

📄 阅读： references/toggle-switch-features.md

• 入门与安装
• Toggle Switch 基本实现
• 选中和未选中状态
• 双向数据绑定（@bind-Checked）
• 开/关标签配置
• 更改事件
• 值绑定
• 表单的 Name 属性
• 默认状态配置

📄 阅读： references/toggle-switch-styling.md

• 外观自定义
• 尺寸变体
• 标签自定义（OnLabel、OffLabel）
• 配色方案
• 自定义 CSS 类
• RTL 支持
• Material 主题注意事项（不支持文本）
• 主题集成

📄 阅读： references/toggle-switch-advanced-features.md

• 无障碍支持
• 键盘导航
• 禁用状态处理
• 表单集成
• 状态管理模式
• 最佳实践

---

组件通用模式

事件处理模式

所有按钮组件均支持标准的 Blazor 事件处理：

<SfButton OnClick="HandleClick">Click Me</SfButton>

@code {
    private void HandleClick()
    {
        // Handle button click
    }
}

样式模式

所有组件均支持 CSS 类自定义：

<SfButton CssClass="e-primary custom-button">Styled Button</SfButton>

图标集成模式

大多数组件均支持图标 CSS 类：

<SfButton IconCss="e-icons e-plus-icon">Add Item</SfButton>

禁用状态模式

所有交互式组件均支持禁用状态：

<SfButton Disabled="@isDisabled">Button</SfButton>

RTL 支持模式

所有组件均支持从右向左渲染：

<SfButton EnableRtl="true">RTL Button</SfButton>

---

共享配置

主题选项

所有按钮组件均支持 Syncfusion 主题：

• Bootstrap5（默认）：bootstrap5.css
• Material：material.css
• Fabric：fabric.css
• Tailwind：tailwind.css
• Fluent：fluent.css

常用 CSS 类

标准 CSS 实用类可用于所有组件：

• e-primary：主要操作样式
• e-success：成功/正向操作
• e-info：信息提示操作
• e-warning：警告/注意操作
• e-danger：危险/负向操作
• e-link：超链接样式
• e-small：小尺寸变体
• e-flat：扁平样式（无背景）
• e-outline：轮廓样式（仅边框）
• e-round：圆形/圆角样式

无障碍功能

所有组件均包含：

• ARIA 属性
• 键盘导航支持
• 屏幕阅读器兼容性
• 焦点指示器
• 符合 WCAG 2.1 标准

---

常见用例

标准操作

在表单、对话框和页面中，使用 Button 执行主要、次要和第三级操作。

多选

使用 CheckBox 进行多个互相独立的选项选择、列表项选择和偏好设置。

单选

使用 RadioButton 从多个选项中进行单选，适用于偏好设置、配置和问卷问题。

分组操作

使用 ButtonGroup 组织相关操作，例如文本对齐、视图模式或筛选选项。

标签和筛选器

使用 Chip 展示标签、联系人列表、筛选选项和可移除项。

菜单操作

使用 DropdownMenu 创建包含多个选项的上下文菜单。

双重操作

需要主要操作及其附加选项时，使用 SplitButton。

耗时操作

对于需要耗费时间的操作（文件上传、表单提交、API 调用），使用 ProgressButton。

页面主要操作

在移动设备或仪表板页面上，使用 FloatingActionButton 执行主要操作。

多个快捷操作

需要通过单个 FAB 访问多个相关操作时，使用 SpeedDial。

开/关状态

使用 ToggleSwitch 设置二元选项、功能开关和偏好设置。

---

快速入门示例

基本 Button

<SfButton CssClass="e-primary">Primary Action</SfButton>

基本 CheckBox

<SfCheckBox TChecked="bool" Label="Accept Terms"></SfCheckBox>

带双向绑定的 CheckBox

<SfCheckBox @bind-Checked="isEnabled" Label="Enable Feature"></SfCheckBox>

@code {
    private bool isEnabled = false;
}

多个 CheckBox

<SfCheckBox TChecked="bool"  Label="Option 1"></SfCheckBox>
<SfCheckBox TChecked="bool" Label="Option 2"></SfCheckBox>
<SfCheckBox TChecked="bool" Label="Option 3"></SfCheckBox>

三态 CheckBox

<SfCheckBox EnableTriState="true" Checked="null" Label="Select All" TChecked="bool?"></SfCheckBox>

基本 RadioButton

<SfRadioButton Label="Option 1" Name="group" Value="option1" @bind-Checked="@selected"></SfRadioButton>
<SfRadioButton Label="Option 2" Name="group" Value="option2" @bind-Checked="@selected"></SfRadioButton>
<SfRadioButton Label="Option 3" Name="group" Value="option3" @bind-Checked="@selected"></SfRadioButton>

@code {
    private string selected = "option1";
}

RadioButton 组

<h4>Choose Your Plan</h4>
<SfRadioButton Label="Free" Name="plan" Value="free" @bind-Checked="@plan"></SfRadioButton>
<SfRadioButton Label="Pro" Name="plan" Value="pro" @bind-Checked="@plan"></SfRadioButton>
<SfRadioButton Label="Enterprise" Name="plan" Value="enterprise" @bind-Checked="@plan"></SfRadioButton>

@code {
    private string plan = "free";
}

带图标的 Button

<SfButton IconCss="e-icons e-plus-icon" CssClass="e-primary">
    Add New
</SfButton>

Toggle Switch

<SfSwitch @bind-Checked="isEnabled" OnLabel="On" OffLabel="Off"></SfSwitch>

@code {
    private bool isEnabled = true;
}

Dropdown Menu

<SfDropDownButton Content="Actions">
    <DropDownMenuItems>
        <DropDownMenuItem Text="Edit"></DropDownMenuItem>
        <DropDownMenuItem Text="Delete"></DropDownMenuItem>
    </DropDownMenuItems>
</SfDropDownButton>

浮动操作按钮

<div id="target" style="min-height:200px; position:relative;">
    <SfFab Target="#target" IconCss="e-icons e-plus" Content="Add"></SfFab>
</div>

Chip 集合

<SfChip EnableDelete="true">
    <ChipItems>
        <ChipItem Text="Tag 1"></ChipItem>
        <ChipItem Text="Tag 2"></ChipItem>
        <ChipItem Text="Tag 3"></ChipItem>
    </ChipItems>
</SfChip>

---

导航提示

• 有关安装和基本设置，请参阅任意组件的功能文件
• 有关样式和外观，请参阅各组件的样式文件
• 有关无障碍功能和高级功能，请参阅高级功能文件
• 有关特定组件功能，请导航到上方相应组件的文档部分

---

支持和资源

• 官方演示： https://blazor.syncfusion.com/demos/buttons/
• API 文档： https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Buttons.html
• GitHub 示例： https://github.com/SyncfusionExamples/Blazor-Getting-Started-Examples/
• 系统要求： https://blazor.syncfusion.com/documentation/system-requirements
• 许可： 生产环境使用需要商业许可证

---

请记住： 实施时务必先查阅相应组件的功能文件以获取指导，然后根据需要查看样式和高级功能。