MudBlazor单选按钮：MudRadioGroup布局与状态管理全攻略-优快云博客

MudBlazor单选按钮：MudRadioGroup布局与状态管理全攻略

【免费下载链接】MudBlazor Blazor Component Library based on Material design with an emphasis on ease of use. Mainly written in C# with Javascript kept to a bare minimum it empowers .NET developers to easily debug it if needed. 项目地址: https://gitcode.com/GitHub_Trending/mu/MudBlazor

你还在为Blazor应用中的单选按钮组布局混乱、状态同步复杂而烦恼吗？作为基于Material Design的Blazor组件库，MudBlazor的MudRadioGroup组件彻底解决了这些痛点。本文将系统讲解MudRadioGroup的布局配置、双向绑定、状态管理和高级特性，通过15+代码示例和可视化图表，帮助你在30分钟内掌握企业级单选组件开发技巧。

读完本文你将获得：

3种基础布局实现（水平/垂直/行内紧凑）
4种状态管理模式（基础绑定/表单集成/级联选择/动态数据）
5个性能优化技巧（减少渲染/延迟加载/状态缓存）
完整的错误处理与无障碍访问指南

组件架构解析

MudRadioGroup采用父子组件协同模式，通过CascadingValue实现状态共享。这种架构确保了单选按钮组的一致性和灵活性，同时简化了开发者的使用流程。

mermaid

核心工作流程如下：

MudRadioGroup通过CascadingValue向下传递组实例
子MudRadio组件注册到组并同步初始状态
用户交互触发状态变更，组内自动维护互斥选中状态
通过Value/ValueChanged实现与外部数据的双向绑定

快速上手：3分钟实现基础单选组

环境准备

通过NuGet安装MudBlazor后，在_Imports.razor中添加命名空间：

@using MudBlazor

在Program.cs注册服务：

builder.Services.AddMudServices();

基础示例：性别选择器

<MudRadioGroup @bind-Value="selectedGender" Label="请选择性别">
    <MudRadio Value="Gender.Male" Label="男" />
    <MudRadio Value="Gender.Female" Label="女" />
    <MudRadio Value="Gender.Other" Label="其他" />
</MudRadioGroup>

@code {
    public enum Gender { Male, Female, Other }
    private Gender selectedGender;
}

这个示例展示了最基础的用法：

使用@bind-Value实现双向绑定
枚举类型作为选项值确保类型安全
自动处理选项互斥和状态同步

布局配置：从基础到高级

1. 方向控制

通过CSS类控制单选按钮的排列方向：

<!-- 垂直布局（默认） -->
<MudRadioGroup Class="d-flex flex-column gap-4" @bind-Value="selectedOption">
    <MudRadio Value="1" Label="选项 1" />
    <MudRadio Value="2" Label="选项 2" />
</MudRadioGroup>

<!-- 水平布局 -->
<MudRadioGroup Class="d-flex flex-row gap-6" @bind-Value="selectedOption">
    <MudRadio Value="1" Label="选项 1" />
    <MudRadio Value="2" Label="选项 2" />
</MudRadioGroup>

2. 紧凑布局

使用Dense属性减少间距，适合表单密集场景：

<MudRadioGroup Dense="true" @bind-Value="selectedOption">
    <MudRadio Value="1" Label="紧凑选项 1" />
    <MudRadio Value="2" Label="紧凑选项 2" />
    <MudRadio Value="3" Label="紧凑选项 3" />
</MudRadioGroup>

3. 自定义样式

通过Class和InputClass属性自定义外观：

<MudRadioGroup Class="my-custom-group" InputClass="pa-4 bg-light-blue-50 rounded-lg">
    <MudRadio Value="1" Label="自定义样式选项" Class="my-radio-item">
        <Icon>check_circle</Icon>
        <span class="ml-2">带图标的选项</span>
    </MudRadio>
</MudRadioGroup>

<style>
    .my-custom-group .mud-radio {
        transition: all 0.2s ease;
    }
    .my-custom-group .mud-radio:hover {
        transform: translateX(4px);
    }
    .my-radio-item .mud-icon {
        color: var(--mud-palette-primary);
    }
</style>

布局对比表

布局类型	实现方式	适用场景	性能影响
垂直布局	默认或`flex-column`	选项数量多	低
水平布局	`flex-row`	选项数量少（≤5）	低
紧凑布局	`Dense="true"`	移动设备或密集表单	低
自定义布局	自定义CSS + 嵌套组件	品牌风格要求高	中

状态管理深度解析

1. 基础双向绑定

<MudRadioGroup @bind-Value="selectedOption" T="string">
    <MudRadio Value="A" Label="选项 A" />
    <MudRadio Value="B" Label="选项 B" />
</MudRadioGroup>

<p>当前选择: @selectedOption</p>

@code {
    private string selectedOption = "A"; // 默认选中A
}

2. 表单集成

与MudForm组件结合实现验证：

<MudForm @ref="form">
    <MudRadioGroup @bind-Value="selectedOption" Required="true" ErrorText="必须选择一个选项">
        <MudRadio Value="1" Label="选项 1" />
        <MudRadio Value="2" Label="选项 2" />
    </MudRadioGroup>
    <MudButton OnClick="SubmitForm" Variant="Variant.Filled" Color="Color.Primary" Class="mt-4">
        提交
    </MudButton>
</MudForm>

@code {
    private MudForm form;
    private int? selectedOption; // 可为null类型，用于验证

    private async Task SubmitForm()
    {
        await form.Validate();
        if (form.IsValid)
        {
            // 处理表单提交
        }
    }
}

3. 动态数据源绑定

从API加载选项并绑定：

<MudRadioGroup @bind-Value="selectedCategoryId" Label="选择分类">
    @if (categories == null)
    {
        <MudSkeleton Height="40px" Width="200px" />
        <MudSkeleton Height="40px" Width="200px" />
    }
    else
    {
        @foreach (var category in categories)
        {
            <MudRadio Value="category.Id" Label="@category.Name" />
        }
    }
</MudRadioGroup>

@code {
    private List<Category> categories;
    private int selectedCategoryId;

    protected override async Task OnInitializedAsync()
    {
        categories = await categoryService.GetCategoriesAsync();
        // 设置默认选中项
        if (categories.Any())
            selectedCategoryId = categories.First().Id;
    }

    public class Category
    {
        public int Id { get; set; }
        public string Name { get; set; }
    }
}

4. 级联单选组

实现依赖选择（如省市级联）：

<MudGrid>
    <MudItem xs="12" md="6">
        <MudRadioGroup @bind-Value="selectedProvince" Label="选择省份" T="string">
            <MudRadio Value="Beijing" Label="北京" />
            <MudRadio Value="Shanghai" Label="上海" />
            <MudRadio Value="Guangdong" Label="广东" />
        </MudRadioGroup>
    </MudItem>
    <MudItem xs="12" md="6">
        <MudRadioGroup @bind-Value="selectedCity" Label="选择城市" T="string" Disabled="@string.IsNullOrEmpty(selectedProvince)">
            @if (selectedProvince == "Beijing")
            {
                <MudRadio Value="Haidian" Label="海淀区" />
                <MudRadio Value="Chaoyang" Label="朝阳区" />
            }
            else if (selectedProvince == "Shanghai")
            {
                <MudRadio Value="Pudong" Label="浦东新区" />
                <MudRadio Value="Xuhui" Label="徐汇区" />
            }
            else if (selectedProvince == "Guangdong")
            {
                <MudRadio Value="Guangzhou" Label="广州市" />
                <MudRadio Value="Shenzhen" Label="深圳市" />
            }
            else
            {
                <MudText Color="Color.Info">请先选择省份</MudText>
            }
        </MudRadioGroup>
    </MudItem>
</MudGrid>

@code {
    private string selectedProvince;
    private string selectedCity;
}

5. 状态重置与初始化

<MudRadioGroup @bind-Value="selectedOption" @ref="radioGroup">
    <MudRadio Value="1" Label="选项 1" />
    <MudRadio Value="2" Label="选项 2" />
    <MudRadio Value="3" Label="选项 3" />
</MudRadioGroup>
<MudButton OnClick="ResetSelection" Variant="Variant.Outlined" Class="mt-4">
    重置选择
</MudButton>

@code {
    private MudRadioGroup<int> radioGroup;
    private int selectedOption = 1;

    private async Task ResetSelection()
    {
        // 方法1: 直接设置Value为默认值
        selectedOption = 1;
        
        // 方法2: 调用组件的Reset方法（如果需要触发验证重置）
        // await radioGroup.ResetValueAsync();
    }
}

高级特性与最佳实践

1. 禁用与只读状态

<MudRadioGroup @bind-Value="selectedOption" Disabled="isDisabled" ReadOnly="isReadOnly">
    <MudRadio Value="1" Label="选项 1" />
    <MudRadio Value="2" Label="选项 2" Disabled="true" /> <!-- 单独禁用 -->
    <MudRadio Value="3" Label="选项 3" />
</MudRadioGroup>
<MudSwitch @bind-Checked="isDisabled" Label="禁用整个组" Class="mt-2" />
<MudSwitch @bind-Checked="isReadOnly" Label="只读整个组" Class="mt-2" />

@code {
    private int selectedOption = 1;
    private bool isDisabled;
    private bool isReadOnly;
}

禁用与只读的区别：

Disabled：完全不可交互，UI显示为禁用状态，不参与表单提交
ReadOnly：视觉上与普通状态相似但不可更改，值会参与表单提交

2. 自定义图标与大小

<MudRadioGroup @bind-Value="selectedOption" T="int">
    <MudRadio Value="1" Label="小型图标" Size="Size.Small" Icon="@Icons.Material.Filled.RadioButtonChecked" />
    <MudRadio Value="2" Label="中型图标（默认）" Icon="@Icons.Material.Filled.CheckCircle" />
    <MudRadio Value="3" Label="大型图标" Size="Size.Large" Icon="@Icons.Custom.Brands.Blazor" />
    <MudRadio Value="4" Label="自定义颜色" Color="Color.Error" Icon="@Icons.Material.Filled.Warning" />
</MudRadioGroup>

3. 键盘导航与无障碍访问

MudRadioGroup原生支持键盘导航，符合WCAG 2.1标准：

<MudRadioGroup @bind-Value="selectedOption" aria-label="可访问的单选组示例">
    <MudRadio Value="1" Label="选项 1" />
    <MudRadio Value="2" Label="选项 2" />
    <MudRadio Value="3" Label="选项 3" />
</MudRadioGroup>

@code {
    private int selectedOption;
}

无障碍特性：

支持Tab键聚焦和Shift+Tab反向聚焦
支持方向键（↑↓→←）选择选项
支持Enter/Space键确认选择
自动生成正确的ARIA属性（role="radiogroup"、aria-checked等）

4. 性能优化策略

减少渲染次数

@* 避免不必要的组件重建 *@
<MudRadioGroup @bind-Value="selectedOption">
    @foreach (var option in Options)
    {
        <MudRadio Key="option.Id" Value="option.Id" Label="@option.Name" />
    }
</MudRadioGroup>

@code {
    private List<SelectOption> Options = new()
    {
        new SelectOption { Id = 1, Name = "选项 1" },
        new SelectOption { Id = 2, Name = "选项 2" }
    };
    
    private int selectedOption;
    
    public class SelectOption
    {
        public int Id { get; set; }
        public string Name { get; set; }
    }
}

延迟加载选项

<MudRadioGroup @bind-Value="selectedOption">
    @if (options == null)
    {
        <MudSkeleton Height="40px" Width="200px" />
        <MudSkeleton Height="40px" Width="200px" />
    }
    else
    {
        @foreach (var option in options)
        {
            <MudRadio Value="option.Id" Label="@option.Name" />
        }
    }
</MudRadioGroup>

@code {
    private List<Option> options;
    private int selectedOption;
    
    protected override async Task OnInitializedAsync()
    {
        // 模拟API延迟加载
        await Task.Delay(800);
        options = await GetOptionsFromApi();
    }
    
    private Task<List<Option>> GetOptionsFromApi()
    {
        return Task.FromResult(new List<Option>
        {
            new Option { Id = 1, Name = "延迟加载选项 1" },
            new Option { Id = 2, Name = "延迟加载选项 2" }
        });
    }
    
    public class Option
    {
        public int Id { get; set; }
        public string Name { get; set; }
    }
}

5. 事件处理与验证

<MudForm @ref="form">
    <MudRadioGroup @bind-Value="selectedOption" Required="true" ErrorText="请选择一个选项" 
                  ValueChanged="HandleValueChanged">
        <MudRadio Value="1" Label="选项 1" />
        <MudRadio Value="2" Label="选项 2" />
        <MudRadio Value="3" Label="选项 3" />
    </MudRadioGroup>
    <MudButton OnClick="SubmitForm" Variant="Variant.Filled" Class="mt-4">
        提交
    </MudButton>
</MudForm>

@code {
    private MudForm form;
    private int? selectedOption;
    
    private void HandleValueChanged(int? value)
    {
        Console.WriteLine($"选项变更: {value}");
        // 可以在这里添加额外的业务逻辑
        if (value == 3)
        {
            // 显示确认对话框等
        }
    }
    
    private async Task SubmitForm()
    {
        await form.Validate();
        if (form.IsValid)
        {
            // 处理提交
        }
    }
}

常见问题与解决方案

1. 选项不互斥问题

问题：选择一个选项后，其他选项未自动取消选中。

解决方案：确保所有MudRadio都在同一个MudRadioGroup内，且具有相同的泛型类型T。

<!-- 错误示例 -->
<MudRadioGroup @bind-Value="selectedOption">
    <MudRadio Value="1" Label="选项 1" />
</MudRadioGroup>
<MudRadioGroup @bind-Value="selectedOption"> <!-- 错误：多个组 -->
    <MudRadio Value="2" Label="选项 2" />
</MudRadioGroup>

<!-- 正确示例 -->
<MudRadioGroup @bind-Value="selectedOption">
    <MudRadio Value="1" Label="选项 1" />
    <MudRadio Value="2" Label="选项 2" />
</MudRadioGroup>

2. 绑定值不更新问题

问题：代码中修改Value后，UI未同步更新。

解决方案：确保使用@bind-Value或手动触发StateHasChanged()。

<!-- 正确绑定方式 -->
<MudRadioGroup @bind-Value="selectedOption">
    <MudRadio Value="1" Label="选项 1" />
    <MudRadio Value="2" Label="选项 2" />
</MudRadioGroup>

@code {
    private int selectedOption;
    
    private void SetOption()
    {
        selectedOption = 2;
        // 如果在异步方法中，确保使用await或调用StateHasChanged()
        // StateHasChanged();
    }
}

3. 动态数据不刷新问题

问题：选项数据更新后，单选组未重新渲染。

解决方案：使用Key属性强制组件刷新或确保集合引用变更。

<MudRadioGroup @bind-Value="selectedOption">
    @foreach (var option in options)
    {
        <MudRadio Key="option.Id" Value="option.Id" Label="@option.Name" />
    }
</MudRadioGroup>

@code {
    private List<Option> options;
    private int selectedOption;
    
    private void RefreshOptions()
    {
        // 方法1: 创建新的集合实例
        options = new List<Option>(options);
        
        // 方法2: 使用Key属性（推荐）
        // 已在上面示例中实现
    }
}

性能优化与高级技巧

1. 虚拟滚动（大量选项场景）

当选项数量超过50个时，使用虚拟滚动提升性能：

<MudList>
    <Virtualize Items="options" Context="option" ItemSize="40">
        <MudRadio Value="option.Id" Label="@option.Name" />
    </Virtualize>
</MudList>

@code {
    private List<Option> options;
    
    protected override void OnInitialized()
    {
        // 生成1000个选项用于演示
        options = Enumerable.Range(1, 1000)
                           .Select(i => new Option { Id = i, Name = $"选项 {i}" })
                           .ToList();
    }
    
    public class Option
    {
        public int Id { get; set; }
        public string Name { get; set; }
    }
}

2. 响应式布局适配

<MudRadioGroup @bind-Value="selectedOption" Class="d-md-flex flex-md-row flex-column">
    <MudRadio Value="1" Label="选项 1" Class="flex-1" />
    <MudRadio Value="2" Label="选项 2" Class="flex-1" />
    <MudRadio Value="3" Label="选项 3" Class="flex-1" />
</MudRadioGroup>

在大屏幕上水平排列，在小屏幕上垂直排列，通过Bootstrap的响应式类实现。

3. 主题定制

<MudThemeProvider Theme="_theme" />
<MudRadioGroup @bind-Value="selectedOption">
    <MudRadio Value="1" Label="选项 1" />
    <MudRadio Value="2" Label="选项 2" />
</MudRadioGroup>

@code {
    private MudTheme _theme = new MudTheme
    {
        Palette = new Palette
        {
            Primary = Colors.Blue.Darken3,
            Secondary = Colors.Orange.Lighten2,
        },
        Components = new Components
        {
            MudRadio = new MudRadioTheme
            {
                ColorChecked = Colors.Teal.Default,
                ColorUnchecked = Colors.Grey.Default,
                Size = Size.Medium,
                Ripple = true
            }
        }
    };
    
    private int selectedOption;
}

总结与展望

MudRadioGroup组件通过简洁的API和强大的功能，为Blazor应用提供了完善的单选按钮解决方案。本文详细介绍了其布局配置、状态管理、高级特性和最佳实践，涵盖了从基础使用到企业级应用的各个方面。

随着Blazor技术的不断发展，MudBlazor也在持续迭代。未来版本可能会引入更多高级特性，如：

多选模式支持
自定义动画效果
更丰富的键盘导航
增强的无障碍支持

掌握MudRadioGroup的使用，将帮助你构建更优雅、更高效的Blazor应用界面。无论你是开发简单的表单还是复杂的企业级应用，MudBlazor的单选组件都能满足你的需求。

点赞+收藏+关注，获取更多MudBlazor进阶教程，下期我们将深入探讨数据表格组件MudDataGrid的高级用法！

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考