ant-design-blazor Radio 单选框组件完全指南:API 详解与源码实现原理
ant-design-blazor Radio 单选框组件完全指南:API 详解与源码实现原理
Radio(单选框)是 ant-design-blazor 组件库中"数据录入"(Data Entry)分类下的核心组件之一,用于在一组备选项中选中唯一状态。本文以 Radio 官方文档 为骨架,结合组件库源码与单元测试,系统讲解 Radio 与 RadioGroup 的完整 API、按钮样式、尺寸控制、禁用同步、枚举绑定等实战用法,并深入剖析其互斥选中与值回传的底层实现。读完本文,你将能够在 Blazor 应用中熟练使用 Radio 完成单选交互,并理解其内部状态管理机制。
何时使用
Radio 适合在以下场景使用:
- 需要在多个备选项中选中单个状态;
- 与
Select(下拉选择)的区别在于:Radio的所有选项默认全部可见,方便用户在比较中直接点选,因此选项数量不宜过多。
从使用语义上看,若选项少且需要全部平铺展示,用 Radio;若选项多或空间有限,则优先考虑 Select。这一设计取舍与 Ant Design 的设计体系保持一致,详见 Radio 组件源码注释。
基本用法:单个 Radio
最简单的方式是直接使用泛型组件 Radio<TValue>,通过 ChildContent 指定标签文本:
<Radio TValue="bool">Radio</Radio>
对应渲染出的 DOM 结构(可参见 Radio.razor 与 RadioTests.razor):
<label class="ant-radio-wrapper">
<span class="ant-radio">
<input type="radio" class="ant-radio-input">
<span class="ant-radio-inner"></span>
</span>
<span>Radio</span>
</label>
单个 Radio 支持 Checked 与 DefaultChecked 两种选中控制方式:Checked 指定当前是否选中(受控),DefaultChecked 指定初始是否选中(非受控),二者在初始化时只会取一次生效(源码中通过 _defaultCheckedSetted 标记保证),参见 Radio.razor.cs。测试 Bind_DefaultChecked_basic_radio 验证了 DefaultChecked 会令 Checked 初始为 true。
单选组合:RadioGroup 互斥
多个 Radio 必须配合 RadioGroup<TValue> 使用才能实现互斥。通过 @bind-Value 双向绑定当前选中值:
<RadioGroup @bind-Value="_value">
<Radio Value="1">A</Radio>
<Radio Value="2">B</Radio>
<Radio Value="3">C</Radio>
<Radio Value="4">D</Radio>
</RadioGroup>
@code {
int _value = 1;
}
RadioGroup<TValue> 继承自 AntInputComponentBase<TValue>(见 RadioGroup.razor.cs),因此具备组件库统一的 Value/ValueChanged 双向绑定能力;Radio 与 RadioGroup 的泛型参数 TValue 必须一致(源码在 OnInitialized 中会对类型不匹配抛出 InvalidOperationException,见 Radio.razor.cs)。
互斥的实现原理
RadioGroup 通过 CascadingValue 将自身与 InGroup 标记级联给子级 Radio(见 RadioGroup.razor),其内部维护了 List<Radio<TValue>> _radioItems 列表:
- 注册:每个子 Radio 初始化时调用
RadioGroup.AddRadio(this)加入列表,若其Value与CurrentValue相等则立即选中(RadioGroup.razor.cs); - 点击:Radio 点击时若在组内,调用
RadioGroup.OnRadioChange(Value)(Radio.razor.cs); - 同步:
OnRadioChange更新CurrentValue,触发OnValueChange,遍历全部 Radio 依次调用Select/UnSelect,保证同一时刻只有一个 Radio 处于选中态(RadioGroup.razor.cs); - 注销:组件销毁时调用
RadioGroup.RemoveRadio(this),避免内存泄漏。
EqualsValue 使用 EqualityComparer<TValue>.Default 进行值比较,因此 int、string、枚举等可空值均能正确处理。
按钮样式:RadioButton 与 ButtonStyle
将 Radio 显示为按钮
为每个 Radio 设置 RadioButton 参数即可将单选组渲染为按钮样式:
<RadioGroup @bind-Value="radioValue4" ButtonStyle="RadioButtonStyle.Solid">
<Radio RadioButton Value="@("A")">Hangzhou</Radio>
<Radio RadioButton Value="@("B")">Shanghai</Radio>
<Radio RadioButton Value="@("C")">Beijing</Radio>
<Radio RadioButton Value="@("D")">Chengdu</Radio>
</RadioGroup>
@code {
string radioValue4 = "A";
}
RadioButton 类型为 bool,默认 false;为 true 时 Radio 渲染为按钮组风格(ant-radio-button-wrapper),CSS 类切换逻辑见 Radio.razor.cs。
ButtonStyle:描边与填色
RadioGroup 的 ButtonStyle 参数控制按钮风格,取值为 RadioButtonStyle 枚举(定义于 ButtonStyle.cs),共有两种:
| 枚举值 | 效果 |
|---|---|
Outline |
描边风格(默认),按钮间有间隔线 |
Solid |
实色填底风格 |
源码通过 Dictionary<RadioButtonStyle, string> 将其映射为 ant-radio-group-outline / ant-radio-group-solid 两个 CSS 类(RadioGroup.razor.cs)。
尺寸:仅对按钮样式生效
RadioGroup 的 Size 参数控制按钮样式下的大小,类型为 InputSize 枚举(定义于 InputSize.cs),取值为:
InputSize.Default(默认值)InputSize.LargeInputSize.Small
<RadioGroup @bind-Value="radioValue5" Size="InputSize.Large">
<Radio RadioButton Value="@("A")">Hangzhou</Radio>
...
</RadioGroup>
<RadioGroup @bind-Value="radioValue5" Size="InputSize.Small">
<Radio RadioButton Value="@("A")">Hangzhou</Radio>
...
</RadioGroup>
注意:Size 只对按钮样式生效,纯 Radio 样式下不产生视觉效果。源码中通过 .If($"{prefixCls}-large", () => Size == InputSize.Large) 等条件为 ant-radio-group 追加尺寸类(RadioGroup.razor.cs)。
禁用:RadioGroup 的级联同步
单个 Radio 与整个 RadioGroup 均可禁用:
<!-- 单个禁用 -->
<Radio Checked Disabled TValue="bool">Disabled</Radio>
<!-- 整组禁用:配合按钮切换演示 -->
<RadioGroup Disabled @bind-Value="radioValue3">
<Radio RadioButton Value="@("A")">Hangzhou</Radio>
...
</RadioGroup>
需要注意一个细节:RadioGroup 的 Disabled 属性会级联同步给所有子 Radio(通过 SetDisabledValue 与事件订阅 OnDisabledValueChanged 实现),但已单独设置 Disabled 的 Radio 不会被覆盖——从源码 if (!radio.Disabled) 的判断可以看出,组级禁用同步会跳过已经禁用的成员(RadioGroup.razor.cs)。这一行为由测试 Sync_Disabled_exist_disabled_member_radioGroup 验证:members<a href="https://link.gitcode.com/i/689258d6419cb68d8402e5a572925d0a" target="_blank">0](自身禁用)保持 true,而 members[1] 跟随组状态变化([RadioGroupTests.razor)。
配合 name 属性:让浏览器识别真实分组
可以为 RadioGroup 配置 Name 参数,为组内所有 input[type="radio"] 赋予相同的 name 属性,使浏览器把 RadioGroup 下的 Radio 真正视为一组(例如通过方向键始终在同一组内切换选项):
<RadioGroup @bind-Value="radioValue1" Name="radiogroup1">
<Radio Value="@("A")">A</Radio>
<Radio Value="@("B")">B</Radio>
<Radio Value="@("C")">C</Radio>
<Radio Value="@("D")">D</Radio>
</RadioGroup>
<RadioGroup @bind-Value="radioValue2" Name="radiogroup2">
...
</RadioGroup>
如果未显式指定 Name,源码会自动生成:优先取 NameAttributeValue ?? PropertyName,最后回退到 IComponentIdGenerator 生成的唯一 ID(RadioGroup.razor.cs),并通过 AddRadio 时调用 radio.SetName(Name) 将 name 下发到每个子 Radio 的 <input> 元素上。
配置方式:Options 属性渲染选项
除声明式书写子 Radio 外,RadioGroup 还支持通过 Options 参数以数据驱动方式渲染选项(见 RadioGroup.razor)。Options 支持两种类型(OneOf 联合类型):
1. string[]——仅需值数组:
<RadioGroup Options="@options" @bind-Value="_radioValue"></RadioGroup>
@code {
string _radioValue = "Apple";
string[] options = new string[] { "Apple", "Pear", "Orange" };
}
2. RadioOption<TValue>[]——带标签与值的选项对象:
<RadioGroup Options="@options2" @bind-Value="_radioValue" ButtonStyle="RadioButtonStyle.Outline"></RadioGroup>
@code {
RadioOption<string>[] options2 = new RadioOption<string>[]
{
new() { Value = "Apple", Label = "🍎 Apple" },
new() { Value = "Pear", Label = "🍐 Pear" },
new() { Value = "Orange", Label = "🍊 Orange" },
};
}
RadioOption<TValue> 定义于 RadioOption.cs,包含三个属性:
| 属性 | 类型 | 说明 |
|---|---|---|
Label |
string |
选项显示文本 |
Value |
TValue |
选项值,用于比较选中 |
Disabled |
bool |
是否禁用该项 |
使用 Options 时无需(也不应)再写 ChildContent,二者二选一。Options 模式下会自动为生成的 Radio 设置 RadioButton(是否按钮由 IsButton 即 ButtonStyle.HasValue 决定)。
枚举方式:EnumRadioGroup 一键生成
如果选项恰好来自 C# 枚举,可使用专用组件 EnumRadioGroup<TEnum>,它继承自 RadioGroup<TEnum>,在构造函数中通过 EnumHelper<TEnum>.GetValueLabelList() 自动将枚举成员转为 RadioOption<TEnum><a href="https://link.gitcode.com/i/766a4435c3994c62b7fc61ecb41cc361" target="_blank">](见 [EnumRadioGroup.cs):
@using System.ComponentModel.DataAnnotations
<EnumRadioGroup TEnum="Fruits" @bind-Value="_radioValue" Disabled="_disabled" Name="group1"></EnumRadioGroup>
<br />
<EnumRadioGroup TEnum="Fruits" @bind-Value="_radioValue" Disabled="_disabled" ButtonStyle="RadioButtonStyle.Solid" Name="group2"></EnumRadioGroup>
<br />
Value: @_radioValue
@code {
Fruits _radioValue = Fruits.Apple;
bool _disabled;
enum Fruits
{
[Display(Name = "🍎 Apple")]
Apple,
Pear,
Orange
}
}
枚举成员的 [Display(Name = "...")] 特性会作为选项标签展示;EnumRadioGroup 同样支持 Disabled、ButtonStyle、Name 等 RadioGroup 的全部参数。
泛型用法:int / string / bool / bool? 皆可
得益于 Radio<TValue> 与 RadioGroup<TValue> 的泛型设计,单选值可以是任意可比较类型。官方演示(Generic.razor)展示了 int、string、bool 与可空 bool? 四种用法:
<RadioGroup @bind-Value="@_intValue">
<Radio Value="1">1</Radio>
<Radio Value="2">2</Radio>
<Radio Value="3">3</Radio>
<Radio Value="4">4</Radio>
</RadioGroup>
<RadioGroup @bind-Value="@_strValue">
<Radio Value="@("A")">A</Radio>
<Radio Value="@("B")">B</Radio>
<Radio Value="@("C")">C</Radio>
<Radio Value="@("D")">D</Radio>
</RadioGroup>
<RadioGroup @bind-Value="@_boolValue">
<Radio Value="true">Yes</Radio>
<Radio Value="false">No</Radio>
</RadioGroup>
<RadioGroup @bind-Value="@_nullBoolValue">
<Radio Value="@(true)" TValue="bool?">Yes</Radio>
<Radio Value="@(false)" TValue="bool?">No</Radio>
<Radio Value="@(null)" TValue="bool?">Unknown</Radio>
</RadioGroup>
@code {
int _intValue = 1;
string _strValue = "A";
bool _boolValue = false;
bool? _nullBoolValue;
}
字符串值建议写成 Value="@("A")"(而非 Value="A")以显式绑定;bool? 场景中,值为 null 时允许"未知/未选"状态,测试 Bind_default_null_value_radioGroup 验证了初始无选中项时 .ant-radio-checked 列表为空(RadioGroupTests.razor)。
完整 API 一览
以下为官方文档 API 表格的完整收录,并依据源码补充了文档未列出的关键参数。
Radio / Radio.Button
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
AutoFocus |
自动获取焦点(首帧渲染后对 input 调用 focus) | bool |
false |
Checked |
指定当前是否选中 | bool |
- |
DefaultChecked |
初始是否选中(仅在初始化时生效一次) | bool |
- |
CheckedChanged |
选中状态变化时的回调 | EventCallback<bool> |
- |
Disabled |
禁用 Radio | bool |
false |
RadioButton |
设置为 true 以将 radio 风格设置为按钮组 |
bool |
false |
Value |
根据 value 进行比较,判断是否选中 | TValue |
- |
ChildContent |
标签显示内容 | RenderFragment |
- |
注:源码中还存在标记为
<a href="https://link.gitcode.com/i/7a8f3e15d755d04dd930c090cfbb3657" target="_blank">Obsolete]的CheckedChange参数,官方建议改用CheckedChanged([Radio.razor.cs)。
RadioGroup
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
ButtonStyle |
RadioButton 的风格样式,描边(Outline)或填色(Solid) | RadioButtonStyle? |
- |
Disabled |
禁选所有子单选器(级联同步,但不覆盖已单独禁用的子项) | bool |
false |
Value |
用于设置当前选中的值(支持 @bind-Value) |
TValue |
- |
DefaultValue |
组的默认选中值(仅在初始化时生效) | TValue |
- |
Name |
RadioGroup 下所有 input[type="radio"] 的 name 属性 |
string |
自动生成 |
Size |
大小,只对按钮样式生效 | InputSize |
InputSize.Default |
OnChange |
选项变化时的回调 | EventCallback<TValue> |
- |
Options |
以配置方式渲染选项,string[] 或 RadioOption<TValue>[] |
OneOf<string[], RadioOption<TValue>[]> |
- |
ChildContent |
声明式子 Radio 内容(与 Options 二选一) |
RenderFragment |
- |
回调示例:
<RadioGroup @bind-Value="_value" OnChange="OnRadioGroupChange">
<Radio Value="1">A</Radio>
<Radio Value="2">B</Radio>
</RadioGroup>
@code {
int _value = 1;
void OnRadioGroupChange(int value)
{
// 仅在值真正发生变化时触发
}
}
从源码看,OnChange 仅在 oldValue 与 CurrentValue 经 EqualsValue 比较不相等时才被调用(RadioGroup.razor.cs),因此重复点击当前已选中项不会触发回调。
垂直布局与更多输入框组合
Radio 的布局通过内联 Style 控制即可实现垂直排列,官方演示(Vgroup.razor)还展示了"More..."选项选中后动态展开文本框的场景:
<RadioGroup @bind-Value="@radioValue">
<Radio Style="@style" Value="@("A")">Option A</Radio>
<Radio Style="@style" Value="@("B")">Option B</Radio>
<Radio Style="@style" Value="@("C")">Option C</Radio>
<Radio Style="@style" Value="@("M")">
More...
@if (radioValue == "M")
{
<Input Type="InputType.Text" TValue="string" />
}
</Radio>
</RadioGroup>
@code {
string radioValue = "A";
string style = "display: block;height:30px;line-height:30px";
}
小结
ant-design-blazor 的 Radio 组件以泛型 Radio<TValue> / RadioGroup<TValue> 为核心,通过 CascadingValue 注册机制与值比较同步实现了组内互斥,支持声明式 ChildContent、配置式 Options 与枚举式 EnumRadioGroup 三种选项构建方式,并完整覆盖按钮样式(RadioButton + ButtonStyle)、三档尺寸(InputSize)、级联禁用、name 分组与 OnChange 回调等企业级表单所需能力。相关的全部演示代码可查阅 Radio 演示目录,单元测试覆盖于 RadioTests.razor 与 RadioGroupTests.razor,读者可结合源码进一步验证文中所述的各项行为。