BootstrapBlazor单选按钮：Radio与RadioList组件全解析-优快云博客

BootstrapBlazor单选按钮：Radio与RadioList组件全解析

【免费下载链接】BootstrapBlazor 项目地址: https://gitcode.com/gh_mirrors/bo/BootstrapBlazor

1. 组件概述

在现代Web应用开发中，单选按钮（Radio Button）是用户界面不可或缺的交互元素，用于从互斥选项中选择单一值。BootstrapBlazor框架提供了两种核心单选组件：基础Radio（单选按钮）和增强型RadioList（单选列表），它们基于Bootstrap样式系统构建，提供了丰富的自定义选项和响应式支持。

1.1 组件定位与应用场景

组件类型	核心特性	典型应用场景
`Radio`	基础单选单元，独立使用	简单二选一场景（如启用/禁用）
`RadioList`	绑定数据源，批量生成单选组	多选项选择（如性别、支付方式）

1.2 组件关系图

mermaid

2. Radio组件深度解析

2.1 基本用法

Radio组件是构建单选功能的基础单元，支持双向绑定和状态管理：

<Radio TValue="string" Value="male" @bind-Value="Gender" DisplayText="男" />
<Radio TValue="string" Value="female" @bind-Value="Gender" DisplayText="女" />

@code {
    private string Gender { get; set; } = "male";
}

2.2 核心参数说明

参数名	类型	默认值	说明
`TValue`	泛型	-	绑定值类型（必填）
`Value`	`TValue`	-	单选按钮值
`GroupName`	`string`	自动生成	单选组名称（同组互斥）
`Color`	`Color`	`Primary`	选中状态颜色（Primary/Success/Info/Warning/Danger）
`IsDisabled`	`bool`	`false`	是否禁用
`ShowAfterLabel`	`bool`	`false`	文本是否显示在单选框右侧
`DisplayText`	`string`	-	显示文本
`ChildContent`	`RenderFragment`	-	自定义内容模板

2.3 高级特性

2.3.1 颜色定制

支持5种内置颜色主题，满足不同场景需求：

<Radio Value="1" Color="Color.Success" DisplayText="成功状态" />
<Radio Value="2" Color="Color.Danger" DisplayText="危险状态" />

2.3.2 禁用状态

通过IsDisabled参数控制交互状态：

<Radio Value="option1" IsDisabled="true" DisplayText="不可选选项" />

3. RadioList组件实战指南

3.1 数据源绑定

RadioList通过Items属性批量生成单选组，支持复杂对象绑定：

<RadioList TValue="int" 
           @bind-Value="SelectedCity" 
           Items="@Cities" 
           TextField="Name" 
           ValueField="Id" />

@code {
    private int SelectedCity { get; set; } = 1;
    
    private List<City> Cities = new()
    {
        new City { Id = 1, Name = "北京" },
        new City { Id = 2, Name = "上海" },
        new City { Id = 3, Name = "广州" }
    };
    
    class City {
        public int Id { get; set; }
        public string Name { get; set; }
    }
}

3.2 按钮样式模式

通过IsButton参数启用按钮样式单选组，提升视觉体验：

<RadioList TValue="string"
           Items="@Themes"
           @bind-Value="SelectedTheme"
           IsButton="true"
           ButtonClass="btn-sm"
           Color="Color.Info" />

@code {
    private string SelectedTheme { get; set; } = "light";
    private List<string> Themes = new() { "light", "dark", "system" };
}

3.3 核心参数扩展

参数名	类型	默认值	说明
`Items`	`IEnumerable`	-	数据源
`TextField`	`string`	"Text"	显示文本字段名
`ValueField`	`string`	"Value"	值字段名
`IsButton`	`bool`	`false`	是否启用按钮样式
`ButtonClass`	`string`	"btn"	按钮样式类
`OnValueChanged`	`EventCallback<TValue>`	-	值变更事件

3.4 数据绑定流程图

mermaid

4. 高级应用场景

4.1 动态禁用项

通过GetDisabledState回调控制特定选项的禁用状态：

<RadioList TValue="string"
           Items="@Options"
           @bind-Value="SelectedOption"
           GetDisabledState="IsOptionDisabled" />

@code {
    private string SelectedOption { get; set; }
    private List<string> Options = new() { "选项1", "选项2", "选项3" };
    
    private bool IsOptionDisabled(string option)
    {
        // 禁用"选项2"
        return option == "选项2";
    }
}

4.2 自定义模板

使用ChildContent自定义选项呈现内容：

<RadioList TValue="Product"
           Items="@Products"
           @bind-Value="SelectedProduct">
    <ChildContent Context="product">
        <div class="d-flex align-items-center">
            <span>@product.Name</span>
            <span class="ms-2 badge bg-secondary">@product.Price.ToString("C")</span>
        </div>
    </ChildContent>
</RadioList>

@code {
    private Product SelectedProduct { get; set; }
    private List<Product> Products = new()
    {
        new Product { Name = "笔记本", Price = 4999 },
        new Product { Name = "手机", Price = 3999 }
    };
    
    class Product {
        public string Name { get; set; }
        public decimal Price { get; set; }
    }
}

4.3 结合表单验证

与ValidateForm组件配合实现表单验证：

<ValidateForm Model="@FormModel" OnValidSubmit="OnSubmit">
    <div class="mb-3">
        <RadioList TValue="string"
                   Items="@Genders"
                   @bind-Value="FormModel.Gender"
                   Required
                   ErrorMessage="请选择性别" />
    </div>
    <button type="submit" class="btn btn-primary">提交</button>
</ValidateForm>

@code {
    private FormModel FormModel { get; set; } = new();
    private List<string> Genders = new() { "男", "女" };
    
    class FormModel {
        public string Gender { get; set; }
    }
    
    private void OnSubmit()
    {
        // 处理表单提交
    }
}

5. 性能优化建议

5.1 大数据集处理

当选项超过50项时，建议使用Virtualize组件优化渲染性能：

<Virtualize Items="@LargeOptions" Context="option">
    <Radio TValue="string" 
           Value="option" 
           @bind-Value="SelectedLargeOption" 
           DisplayText="option" />
</Virtualize>

@code {
    private string SelectedLargeOption { get; set; }
    private List<string> LargeOptions = Enumerable.Range(1, 1000).Select(i => $"选项{i}").ToList();
}

5.2 组件复用策略

<!-- 定义可复用单选组组件 -->
@typeparam TValue
<RadioList TValue="TValue"
           Items="@Items"
           @bind-Value="Value"
           Color="Color.Primary"
           IsButton="IsButton" />

@code {
    [Parameter] public IEnumerable Items { get; set; }
    [Parameter] public TValue Value { get; set; }
    [Parameter] public EventCallback<TValue> ValueChanged { get; set; }
    [Parameter] public bool IsButton { get; set; } = false;
}

6. 常见问题解决方案

6.1 绑定值不更新

问题：设置@bind-Value后值不更新
解决方案：确保绑定字段为public且正确设置TValue类型

<!-- 错误示例 -->
<Radio Value="1" @bind-Value="privateValue" /> <!-- 私有字段无法绑定 -->

<!-- 正确示例 -->
<Radio TValue="int" Value="1" @bind-Value="publicValue" />

@code {
    public int publicValue { get; set; } = 1;
}

6.2 组间互斥失效

问题：不同组单选按钮相互影响
解决方案：显式设置GroupName参数

<!-- 第一组 -->
<Radio GroupName="group1" Value="a" @bind-Value="Group1Value" />
<Radio GroupName="group1" Value="b" @bind-Value="Group1Value" />

<!-- 第二组 -->
<Radio GroupName="group2" Value="x" @bind-Value="Group2Value" />
<Radio GroupName="group2" Value="y" @bind-Value="Group2Value" />

7. 完整示例代码

7.1 综合演示页面

@page "/radiodemo"
@using BootstrapBlazor.Components

<Card Title="单选组件综合演示">
    <CardBody>
        <div class="row g-4">
            <!-- 基础Radio示例 -->
            <div class="col-md-6">
                <h5>基础单选按钮</h5>
                <div class="mb-3">
                    <Radio TValue="int" Value="1" @bind-Value="BasicValue" DisplayText="选项1" />
                    <Radio TValue="int" Value="2" @bind-Value="BasicValue" DisplayText="选项2" />
                    <Radio TValue="int" Value="3" @bind-Value="BasicValue" DisplayText="选项3" IsDisabled="true" />
                </div>
                <p>当前选择: @BasicValue</p>
            </div>

            <!-- RadioList示例 -->
            <div class="col-md-6">
                <h5>列表单选组件</h5>
                <RadioList TValue="string"
                           Items="@ListItems"
                           @bind-Value="ListValue"
                           Color="Color.Success" />
                <p>当前选择: @ListValue</p>
            </div>

            <!-- 按钮样式示例 -->
            <div class="col-md-6">
                <h5>按钮样式单选组</h5>
                <RadioList TValue="string"
                           Items="@ButtonItems"
                           @bind-Value="ButtonValue"
                           IsButton="true"
                           ButtonClass="btn-outline-primary" />
                <p>当前选择: @ButtonValue</p>
            </div>

            <!-- 自定义模板示例 -->
            <div class="col-md-6">
                <h5>自定义模板</h5>
                <RadioList TValue="User"
                           Items="@Users"
                           @bind-Value="SelectedUser"
                           ValueField="Id"
                           TextField="Name">
                    <ChildContent Context="user">
                        <div class="d-flex align-items-center">
                            <Avatar Url="@user.Avatar" Class="me-2" />
                            <div>
                                <div>@user.Name</div>
                                <div class="text-muted small">@user.Email</div>
                            </div>
                        </div>
                    </ChildContent>
                </RadioList>
                <p>当前选择用户: @SelectedUser?.Name</p>
            </div>
        </div>
    </CardBody>
</Card>

@code {
    // 基础单选
    private int BasicValue { get; set; } = 2;
    
    // 列表单选
    private string ListValue { get; set; } = "B";
    private List<string> ListItems = new() { "A", "B", "C", "D" };
    
    // 按钮单选
    private string ButtonValue { get; set; } = "Option2";
    private List<string> ButtonItems = new() { "Option1", "Option2", "Option3" };
    
    // 自定义模板
    private User SelectedUser { get; set; }
    private List<User> Users = new()
    {
        new User { Id = 1, Name = "张三", Email = "zhangsan@example.com", Avatar = "https://picsum.photos/id/1/32/32" },
        new User { Id = 2, Name = "李四", Email = "lisi@example.com", Avatar = "https://picsum.photos/id/2/32/32" }
    };
    
    class User
    {
        public int Id { get; set; }
        public string Name { get; set; }
        public string Email { get; set; }
        public string Avatar { get; set; }
    }
}

8. 总结与最佳实践

8.1 组件选择指南

mermaid

8.2 开发建议

类型安全：始终显式指定TValue泛型类型
性能考量：选项超过20个时优先使用RadioList
用户体验：重要选项使用按钮样式提升辨识度
可访问性：确保GroupName唯一且DisplayText清晰
表单集成：配合ValidateForm实现完整验证逻辑

通过合理运用Radio和RadioList组件，可以构建出既美观又功能完善的单选交互界面，满足从简单到复杂的各类业务需求。框架提供的灵活配置和扩展能力，使得开发者能够轻松实现个性化的交互体验。

【免费下载链接】BootstrapBlazor 项目地址: https://gitcode.com/gh_mirrors/bo/BootstrapBlazor

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