Ant Design Blazor Radio 单选框组件完全指南:API 参数、RadioGroup 互斥组与源码级实现解析
Ant Design Blazor Radio 单选框组件完全指南:API 参数、RadioGroup 互斥组与源码级实现解析
Radio(单选框)是 ant-design-blazor 组件库中"数据录入(Data Entry)"类的核心组件之一,用于在一组可见备选项中让用户选中单个状态。本文以 Radio 官方文档 为骨架,结合 组件源码 与 单元测试 中可验证的实现细节,系统讲解 Radio、Radio.Button 与 RadioGroup 的全部 API 参数、七类典型使用场景(基础、互斥组、禁用、按钮样式、尺寸、垂直布局、泛型与枚举),并深入剖析"选中值如何联动""禁用状态如何向下同步"等底层机制,帮助你从"会写"进阶到"写得对、查得准"。
何时使用 Radio
官方文档对适用场景给出了两条明确指引:
- 用于在多个备选项中选中单个状态,即"单选"语义;
- 与
Select的区别:Radio的所有选项默认对用户可见,方便用户在直观比较中做出选择,因此选项数量不宜过多。如果备选项数量庞大(例如几十上百项),应优先考虑 Select 等下拉型组件。
一句话总结:选项少、需要"所见即所得"对比时用 Radio;选项多、节省空间优先时用 Select。
API 速查:Radio / Radio.Button
Radio<TValue> 是泛型组件(定义于 Radio.razor.cs),使用时需要显式指定 TValue,或者由编译器从 Value 参数推断。
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| AutoFocus | 组件挂载并完成首次渲染后自动获取焦点 | boolean | false |
| Checked | 指定当前是否选中 | boolean | - |
| DefaultChecked | 初始(首次渲染)是否选中,仅在组件初始化时生效 | boolean | false |
| Disabled | 禁用该 Radio | boolean | false |
| RadioButton | 设置为 true 后,以按钮组(button group)风格渲染该 Radio |
bool | false |
| Value | 用于与其他 Radio 的 Value 比较,决定哪个被选中 |
TValue | - |
| CheckedChanged | 选中状态变化时触发的回调(EventCallback<bool>) |
- | - |
| ChildContent | Radio 的标签展示内容 | RenderFragment | - |
说明:
CheckedChange是历史遗留参数,源码中已标注<a href="https://link.gitcode.com/i/851da0fd15fb7082dd6afd4fbf013e49" target="_blank">Obsolete("Use CheckedChanged instead")](见 [Radio.razor.cs),新代码请统一使用CheckedChanged。
选中状态的两种来源
从源码 Radio.razor.cs 可以看到 OnInitialized 的处理顺序:
- 如果设置了
DefaultChecked且尚未应用,则将_checked初始化为该值(_defaultCheckedSetted保证只生效一次); Checked作为可双向绑定的属性(@bind-Checked),由外部字段/属性驱动。
这两者对应两种使用方式:外部受控(Checked + CheckedChanged)与内部初始值(DefaultChecked)。在 RadioGroup 内部时,选中状态由组统一管理,单个 Radio 的 Checked 通常无需手动设置。
渲染结构
Radio.razor 渲染出的 DOM 结构为:
<label class="ant-radio-wrapper ...">
<span class="ant-radio ...">
<input type="radio" class="ant-radio-input" checked name="..." value="..."/>
<span class="ant-radio-inner"></span>
</span>
<span>标签内容</span>
</label>
注意 name、value、checked、disabled 都真实映射到原生 input 上(name 由所在 RadioGroup 注入),这正是后面"浏览器原生分组行为"能够生效的基础。单元测试 RadioTests.razor 中的 Renders_basic_radio 与 Renders_Value_basic_radio 对上述标记结构做了精确断言。
API 速查:RadioGroup
RadioGroup<TValue>(定义于 RadioGroup.razor.cs)是互斥单选组的容器,继承自 AntInputComponentBase<TValue>,因此天然支持 @bind-Value 双向绑定。
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| ButtonStyle | RadioButton 风格:描边(Outline)或填色(Solid) | RadioButtonStyle? |
- |
| Disabled | 禁选组内所有子 Radio | boolean | false |
| Value | 当前选中的值(双向绑定目标) | TValue | - |
| DefaultValue | 组的初始选中值,仅在初始化时生效 | TValue | - |
| Name | 组内所有 input[type="radio"] 的 name 属性;不设置时自动生成 |
string | - |
| Size | 尺寸,只对按钮样式生效 | InputSize | InputSize.Default |
| OnChange | 选中值变化时的回调 | EventCallback<TValue> |
- |
| Options | 以数据驱动方式声明选项,见下文"Options 配置方式" | OneOf<string[], RadioOption<TValue>[]> |
- |
| ChildContent | 以模板方式声明 Radio 子组件(与 Options 二选一) |
RenderFragment | - |
枚举值定义
RadioButtonStyle:Outline(描边)、Solid(填实),见 ButtonStyle.cs。InputSize:Default、Large、Small,定义于 components/input/InputSize.cs。
Name 参数的默认行为
若未显式指定 Name,源码在 OnInitialized 中按 NameAttributeValue ?? PropertyName ?? ComponentIdGenerator.Generate(this) 的顺序兜底生成(RadioGroup.razor.cs)。也就是说:表单字段场景会优先采用表单属性名,否则由组件 ID 生成器保证唯一性。
基础用法:最简单的 Radio
<div>
<Radio TValue="bool">Radio</Radio>
</div>
对应官方演示 Basic.razor 与 Basic.md。独立使用(不在组内)时,Radio 更像一个开关:点击后通过内部 Select() 把 _checked 置为 true 并触发 CheckedChanged(Radio.razor.cs)。测试 RadioTests.razor 的 Toggle_basic_radio、Bind_Checked_basic_radio 验证了点击与双向绑定的行为。
RadioGroup:一组互斥的 Radio
单选组是 Radio 最常用的形态。官方演示 Group.razor:
<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;
}
要点:
- 组内所有
Radio的Value类型必须与RadioGroup的TValue一致。若类型不一致,Radio.OnInitialized会抛出InvalidOperationException(提示语见 Radio.razor.cs)。 - 选中依据是
Value相等比较(EqualityComparer<TValue>.Default.Equals),而不是 DOM 原生checked状态。 - 测试 RadioGroupTests.razor 中的
Bind_Value_basic_radioGroup验证了点击value=2的选项后,绑定变量变为2。
选中值的联动逻辑(源码级)
RadioGroup.OnValueChange(RadioGroup.razor.cs)是核心联动逻辑:
- 先取消上一个选中项(
UnSelect); - 遍历
_radioItems列表,对Value与CurrentValue相等的 Radio 执行Select(),其余执行UnSelect(); - 调用
InvokeStateHasChanged()刷新 UI(注释说明这覆盖了 Modal 中的刷新场景)。
而用户点击单个 Radio 时,会经 Radio.OnClick 转交给 RadioGroup.OnRadioChange(value):先更新 CurrentValue(触发 ValueChanged,即 @bind-Value 回写),再用 EqualsValue 判断新旧值是否真的不同,仅在确实变化时才触发 OnChange 回调(RadioGroup.razor.cs)。
初始值与空值处理
DefaultValue="2"会在初始化时设置CurrentValue(RadioGroup.razor.cs),测试Bind_Default_radioGroup验证了Instance.Value == 2。- 对于
int?/bool?等可空类型,可以选"无值"项(见下文泛型示例),测试Bind_default_null_value_radioGroup、set_value_to_null_radioGroup分别覆盖了初始为 null 与把值置为 null 时"所有项取消选中"的边界行为。
Disabled:禁用单个或整组 Radio
官方演示 Disable.razor 展示了三种禁用粒度:
<Radio Checked Disabled="@Disabled" TValue="bool">Disabled</Radio>
<Radio Disabled="@Disabled" TValue="bool">Disabled</Radio>
<RadioGroup Disabled @bind-Value="radioValue3">
<Radio RadioButton Value="@("A")">Hangzhou</Radio>
...
</RadioGroup>
组禁用如何同步到子项
RadioGroup.Disabled 的 setter 会在值变化时触发 OnDisabledValueChanged 委托(RadioGroup.razor.cs)。AddRadio 注册子项时做了一次订阅:OnDisabledValueChanged += radio.SetDisabledValue,从而把组级禁用状态传播给每个子 Radio(RadioGroup.razor.cs)。
需要注意一个关键细节:如果某个 Radio 自身已经设置了 Disabled,组不会覆盖它的值——源码注释明确写着"if the current radio has been already disabled, this radio group won't sync the value of Disabled"。测试 Sync_Disabled_exist_disabled_member_radioGroup 验证了这一行为:Disabled=true 的子项始终保持禁用,其余子项跟随组状态翻转。同时,Sync_Disabled_basic_radioGroup(含 with_options 变体)验证了整组禁用状态切换会同步到所有成员。
禁用时的点击行为
Radio.OnClick 开头即判断 if (Disabled) return;(Radio.razor.cs),因此禁用项既不会改变选中值,也不会触发任何回调。
按钮风格:RadioButton 与 ButtonStyle
描边按钮样式
官方演示 Style.razor:
<RadioGroup @bind-Value="radioValue3">
<Radio RadioButton Value="@("A")">Hangzhou</Radio>
<Radio RadioButton Value="@("B")" Disabled>Shanghai</Radio>
<Radio RadioButton Value="@("C")">Beijing</Radio>
<Radio RadioButton Value="@("D")">Chengdu</Radio>
</RadioGroup>
每个 Radio 加 RadioButton 属性后,ClassMapper 会改用 ant-radio-button-wrapper / ant-radio-button 系列样式类(Radio.razor.cs),视觉上由圆点变为按钮排。组内个别选项仍可单独 Disabled,形成"整组可用、个别禁用"的粒度。
填实按钮样式(Solid)
官方演示 Button_.razor:
<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>
ButtonStyle 决定组根节点的样式类:源码通过 _buttonStyleDics 字典把 Outline/Solid 映射为 ant-radio-group-outline / ant-radio-group-solid(RadioGroup.razor.cs)。不指定 ButtonStyle 时,即使子项都加了 RadioButton,组也不会附加 outline/solid 修饰类——这就是为什么有的场景需要显式给出 ButtonStyle。
Size 尺寸
官方演示 Size.razor 展示了三档尺寸:
<RadioGroup Size="InputSize.Large">...</RadioGroup> <!-- 大 -->
<RadioGroup>...</RadioGroup> <!-- 默认(中) -->
<RadioGroup Size="InputSize.Small">...</RadioGroup> <!-- 小 -->
Size 仅影响 ant-radio-group-large / ant-radio-group-small 两个样式类(RadioGroup.razor.cs),只对按钮风格生效,普通圆点样式不受影响。官方文档也强调它可以与表单输入框(Input)的尺寸相互配合,保持整体视觉一致。
垂直布局与更多输入项
官方演示 Vgroup.razor 展示了两种垂直场景的通用写法:
<RadioGroup @bind-Value="@radioValue">
<Radio Style="@style" Value="@("A")">Option A</Radio>
<Radio Style="@style" Value="@("B")">Option B</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";
}
这里有两个实用技巧:
- 垂直化:通过给每个
Radio设置style="display:block"实现纵向排列,因为 Radio 本身默认是行内元素; - 联动补充输入:利用"选中值回写"的特性,当
radioValue == "M"(选中 More 项)时才渲染额外的文本框,实现"选其他 + 填补充信息"的常见表单需求。
泛型用法:同一组件支持任意值类型
Radio<TValue> 与 RadioGroup<TValue> 均为泛型组件,官方演示 Generic.razor 一次性展示了四种类型:
<RadioGroup @bind-Value="@_intValue"> <!-- int -->
<Radio Value="1">1</Radio> ...
</RadioGroup>
<RadioGroup @bind-Value="@_strValue"> <!-- string -->
<Radio Value="@("A")">A</Radio> ...
</RadioGroup>
<RadioGroup @bind-Value="@_boolValue"> <!-- bool -->
<Radio Value="true">Yes</Radio>
<Radio Value="false">No</Radio>
</RadioGroup>
<RadioGroup @bind-Value="@_nullBoolValue"> <!-- bool?(可空) -->
<Radio Value="@(true)" TValue="bool?">Yes</Radio>
<Radio Value="@(false)" TValue="bool?">No</Radio>
<Radio Value="@(null)" TValue="bool?">Unknown</Radio>
</RadioGroup>
关键点:
- 字符串字面量作为
TValue为int的Value时,Blazor 会自动转换;非字符串类型请用@(...)表达式或显式TValue指明类型。 - 可空类型(
bool?、int?)是单选的常见需求:Value="@(null)"表示"未知/未选择"状态,且不会与其它值冲突。测试Bind_default_null_value_radioGroup也验证了初始值为 null 时组内没有任何ant-radio-checked。 - 泛型机制保证了
RadioGroup与子Radio的TValue在编译期对齐,避免运行时类型错配。
Options 配置方式:数据驱动渲染
除了模板方式(ChildContent 中手写 <Radio>),RadioGroup 还支持 Options 参数纯数据驱动渲染。官方演示 Optional.razor:
<RadioGroup Options="@options" @bind-Value="_radioValue"></RadioGroup>
<RadioGroup Options="@options2" @bind-Value="_radioValue"
ButtonStyle="RadioButtonStyle.Outline"></RadioGroup>
@code {
string _radioValue = "Apple";
string[] options = new string[] { "Apple", "Pear", "Orange" };
RadioOption<string>[] options2 = new RadioOption<string>[]
{
new(){ Value = "Apple", Label = "🍎 Apple" },
new(){ Value = "Pear", Label = "🍐 Pear" },
new(){ Value = "Orange", Label = "🍊 Orange" },
};
}
Options 的两种形式
Options 的类型是 OneOf<string<a href="https://link.gitcode.com/i/280d8719a40d40459c760729e3268c4f" target="_blank">], RadioOption<TValue>[]>([RadioGroup.razor.cs),在 RadioGroup.razor 中按 IsT0 分流渲染:
string[]:直接以字符串同时作为Value和Label,适合"显示值与选中值一致"的简单场景;RadioOption<TValue><a href="https://link.gitcode.com/i/bb2c1082fed2d74566dc482a19c1ab2a" target="_blank">]:RadioOption模型定义于 [RadioOption.cs,包含Label(展示文本)、Value(选中值)、Disabled(单项禁用)三个属性,可精细控制每个选项。
两种形式渲染的 Radio 都会自动带上 RadioButton="IsButton",其中 IsButton 由 ButtonStyle.HasValue 决定(RadioGroup.razor.cs),因此 Options 方式同样可以搭配按钮风格。
EnumRadioGroup:枚举一键生成单选组
对于"枚举 ↔ 单选"这种高频场景,仓库提供了开箱即用的 EnumRadioGroup<TEnum>(EnumRadioGroup.cs),它直接继承 RadioGroup<TEnum>,并在构造函数中调用 EnumHelper<TEnum>.GetValueLabelList() 将枚举自动转换为 RadioOption<TEnum>[],无需手写选项列表。
官方演示 EnumGroup.razor:
<EnumRadioGroup TEnum="Fruits" @bind-Value="_radioValue" Name="group1"></EnumRadioGroup>
<EnumRadioGroup TEnum="Fruits" @bind-Value="_radioValue"
Disabled="_disabled" ButtonStyle="RadioButtonStyle.Solid" Name="group2"></EnumRadioGroup>
@code {
Fruits _radioValue = Fruits.Apple;
bool _disabled;
enum Fruits
{
[Display(Name = "🍎 Apple")]
Apple,
Pear,
Orange
}
}
要点:
TEnum指定枚举类型,选中值类型即该枚举;- 枚举成员上的
[Display(Name = "...")]特性(来自System.ComponentModel.DataAnnotations)可作为选项的Label,未标注的成员则使用默认名称; - 由于
EnumRadioGroup仍是RadioGroup,Disabled、ButtonStyle、Name、@bind-Value等全部参数照常可用。
实战自检清单
编写与排查 Radio 相关代码时,可对照以下经验:
- 类型对齐:
RadioGroup与所有子Radio的TValue必须一致,否则初始化抛异常(错误信息见 Radio.razor.cs)。 - 选中靠比较:是否选中取决于
Value相等比较,与渲染顺序无关;修改选中值请通过@bind-Value或直接赋值Value。 - Name 的浏览器语义:
RadioGroup的Name会级联到组内所有input<a href="https://link.gitcode.com/i/dc996740483718c024882cc823d367c9" target="_blank">type="radio"]([Name.razor 演示了两个独立组互不干扰),这让浏览器把同组 Radio 视为真正的一组,支持方向键在同一组内切换选项。 - 禁用优先级:子项自身
Disabled优先于组级Disabled;整组禁用的传播通过OnDisabledValueChanged委托订阅完成。 - 按钮风格两要素:子项加
RadioButton+ 组上配ButtonStyle(Outline/Solid),Size只在按钮风格下生效。 - 选项数据化:选项多、结构复杂时优先用
Options(string[]或RadioOption<TValue>[]);枚举场景直接用EnumRadioGroup<TEnum>。
延伸阅读
- 组件文档:Radio 官方文档(en)、Radio 官方文档(zh)
- 组件源码:Radio.razor、Radio.razor.cs、RadioGroup.razor、RadioGroup.razor.cs、RadioOption.cs、EnumRadioGroup.cs
- 官方演示:
site/AntDesign.Docs/Demos/Components/Radio/demo/目录下的 Basic、Group、Disable、Vgroup、Style、Button_、Size、Name、Generic、Optional、EnumGroup 共 11 个示例 - 单元测试:RadioTests.razor、RadioGroupTests.razor,覆盖渲染标记、点击切换、双向绑定、空值边界、禁用同步与动态列表等场景,可作为理解组件行为的"可执行文档"