Ant Design Blazor Radio 单选框组件完全指南:API 参数、RadioGroup 互斥组与源码级实现解析

原创2026-10-11 22:29:281,816 阅读
文章标签:前端UI组件设计系统WebAssembly

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 的处理顺序:

  1. 如果设置了 DefaultChecked 且尚未应用,则将 _checked 初始化为该值(_defaultCheckedSetted 保证只生效一次);
  2. 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 -

枚举值定义

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)是核心联动逻辑:

  1. 先取消上一个选中项(UnSelect);
  2. 遍历 _radioItems 列表,对 Value 与 CurrentValue 相等的 Radio 执行 Select(),其余执行 UnSelect();
  3. 调用 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";
}

这里有两个实用技巧:

  1. 垂直化:通过给每个 Radio 设置 style="display:block" 实现纵向排列,因为 Radio 本身默认是行内元素;
  2. 联动补充输入:利用"选中值回写"的特性,当 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 分流渲染:

  1. string[]:直接以字符串同时作为 Value 和 Label,适合"显示值与选中值一致"的简单场景;
  2. 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 相关代码时,可对照以下经验:

  1. 类型对齐:RadioGroup 与所有子 Radio 的 TValue 必须一致,否则初始化抛异常(错误信息见 Radio.razor.cs)。
  2. 选中靠比较:是否选中取决于 Value 相等比较,与渲染顺序无关;修改选中值请通过 @bind-Value 或直接赋值 Value。
  3. Name 的浏览器语义:RadioGroup 的 Name 会级联到组内所有 input<a href="https://link.gitcode.com/i/dc996740483718c024882cc823d367c9" target="_blank">type="radio"]([Name.razor 演示了两个独立组互不干扰),这让浏览器把同组 Radio 视为真正的一组,支持方向键在同一组内切换选项。
  4. 禁用优先级:子项自身 Disabled 优先于组级 Disabled;整组禁用的传播通过 OnDisabledValueChanged 委托订阅完成。
  5. 按钮风格两要素:子项加 RadioButton + 组上配 ButtonStyle(Outline/Solid),Size 只在按钮风格下生效。
  6. 选项数据化:选项多、结构复杂时优先用 Options(string[] 或 RadioOption<TValue>[]);枚举场景直接用 EnumRadioGroup<TEnum>。

延伸阅读

登录后查看全文
ant-design-blazor