ant-design-blazor Radio 单选框组件完全指南:API 详解与源码实现原理

原创2026-10-12 00:06:431,880 阅读
文章标签:前端UI组件设计系统WebAssembly

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 列表:

  1. 注册:每个子 Radio 初始化时调用 RadioGroup.AddRadio(this) 加入列表,若其 Value 与 CurrentValue 相等则立即选中(RadioGroup.razor.cs);
  2. 点击:Radio 点击时若在组内,调用 RadioGroup.OnRadioChange(Value)(Radio.razor.cs);
  3. 同步:OnRadioChange 更新 CurrentValue,触发 OnValueChange,遍历全部 Radio 依次调用 Select/UnSelect,保证同一时刻只有一个 Radio 处于选中态(RadioGroup.razor.cs);
  4. 注销:组件销毁时调用 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.Large
  • InputSize.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,读者可结合源码进一步验证文中所述的各项行为。

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