Ant Design Blazor Radio 单选框组件完全指南：从基础用法到 RadioGroup 组合实战

Ant Design Blazor Radio 单选框组件完全指南：从基础用法到 RadioGroup 组合实战

发布时间：2026/10/11 12:02:44
Ant Design Blazor Radio 单选框组件完全指南：从基础用法到 RadioGroup 组合实战 前端UI组件设计系统【免费下载链接】ant-design-blazor基于 Ant Design 与 Blazor 的前端组件库。让开发者解放生产力实现更大价值。项目地址https://gitcode.com/ant-design-blazor/ant-design-blazor点击查看免费下载导读Radio是 Ant Design Blazor 组件库中数据录入类的单选框组件用于在多个备选项中强制用户选中单个状态。本篇文章以官方 Basic 示例为入口结合组件库源码与单元测试系统讲解Radio/RadioGroup的参数体系、组合互斥、按钮样式、禁用同步、Options 配置、枚举渲染与泛型绑定等实战用法帮助你在 Blazor 表单、筛选器与设置面板中正确选型并写出可复用的单选逻辑。一、组件定位什么时候该用 Radio在 Ant Design Blazor 中Radio与Select的职责边界十分清晰参考 组件文档用于在多个备选项中选中单个状态与Select的区别在于Radio的所有选项默认全部可见便于用户在选择中直观比较因此选项数量不宜过多。如果你的业务场景是固定少量选项、必须立即看到全部候选那么Radio比下拉框更合适选项过多时则应考虑Select或Cascader。源码中 Radio.razor.cs 的文档注释也重申了这一点Used to select a single state from multiple options并且 there shouldnt be too many of them。二、最基础的用法Basic官方 Basic 示例位于 Basic.razor全文只有几行div Radio TValueboolRadio/Radio /div这是Radio组件的最小使用形态独立渲染一个未选中的单选框TValue声明了该选项携带值的类型这里为boolChildContent即标签之间的内容作为展示文案。组件渲染结构从模板 Radio.razor 可以看到Radio最终渲染为一个label包裹的原生input typeradiolabel classant-radio-wrapper span classant-radio input typeradio classant-radio-input checked... disabled... name... value... / span classant-radio-inner/span /span spanRadio/span /label外层label承接点击事件onclickOnClickant-radio-inner负责绘制圆点样式这样既保留了原生 radio 的语义又能完全由 Less 样式控制外观。单元测试 RadioGroupTests.razor 中对基础组合的断言也印证了这一 DOM 结构ant-radio-wrapper、ant-radio-input、ant-radio-inner等 class 均可在测试的 MarkupMatches 中看到。独立使用时的点击逻辑不放在RadioGroup里的Radio是自管理选中状态的OnClick会直接调用内部的Select()方法见 Radio.razor.csSelect()内部在未选中时置_checked true并触发CheckedChanged回调Radio.razor.cs。因此独立Radio可以配合Checked/DefaultChecked单独使用。三、Radio 参数详解依据 组件 API 文档 并对照 Radio.razor.cs 源码Radio/Radio.Button的完整参数如下参数说明类型默认值AutoFocus自动获取焦点boolfalseChecked指定当前是否选中bool-DefaultChecked初始是否选中boolfalseDisabled禁用 RadioboolfalseRadioButton设置为true以将 radio 风格设置为按钮组boolfalseValue根据 value 进行比较判断是否选中TValue-CheckedChanged选中状态变化时的回调EventCallbackbool--ChildContent展示在选项右侧的标签内容RenderFragment-几个值得注意的细节RadioButton不是独立组件。官方 React 版有Radio.Button子组件而在 ant-design-blazor 中统一收敛为Radio的布尔参数RadioButton置为true即渲染按钮风格。对应源码见 Radio.razor.cs。AutoFocus的实现组件在OnFirstAfterRenderAsync中通过FocusAsync(this._inputRef)对原生 input 完成聚焦Radio.razor.cs。Checked与DefaultChecked的优先级OnInitialized中只有在设置了DefaultChecked且尚未设置过时才覆盖_checkedRadio.razor.cs即DefaultChecked只作用于初始渲染。过期 API 提示源码中CheckedChange已标记[Obsolete(Use CheckedChanged instead)]Radio.razor.cs新代码请一律使用CheckedChanged。四、RadioGroup一组互斥的 Radio单个Radio本身不具互斥能力互斥逻辑由RadioGroup承担。官方组合示例见 Group.razordiv RadioGroup bind-Value_value Radio Value1A/Radio Radio Value2B/Radio Radio Value3C/Radio Radio Value4D/Radio /RadioGroup /div code { int _value 1; }这里RadioGroup通过级联参数RadioGroup/InGroup与子Radio建立联系RadioGroup.razor并把组内选中值bind-Value双向绑定到_value。选中任一选项其余选项自动取消选中。互斥选中的底层机制注册与销毁每个子Radio在OnInitialized中调用RadioGroup.AddRadio(this)注册自己并在Dispose时移除Radio.razor.cs。组值下发RadioGroup.OnValueChange遍历所有注册的Radio与当前Value相等的调用Select()其余调用UnSelect()RadioGroup.razor.cs。点击上抛Radio.OnClick在组内时不再自行选中而是调用RadioGroup.OnRadioChange(this.Value)由组统一更新CurrentValue并触发OnChangeRadio.razor.cs、RadioGroup.razor.cs。泛型一致性校验RadioGroupTValue与RadioTValue的泛型必须一致否则组件会在初始化时抛出异常if (InGroup RadioGroup null) { throw new InvalidOperationException($Please make sure that both RadioGroup and Radio have the same generic type: {typeof(TValue)} .); }这段校验位于 Radio.razor.cs是排查Radio 放进 RadioGroup 后不生效类问题的第一线索。五、RadioGroup 参数详解参数说明类型默认值Value / DefaultValue当前选中值 / 初始选中值TValue-Disabled禁选所有子单选器会自动下发给未单独禁用的子项boolfalseButtonStyleRadioButton 的风格样式描边与填色两种RadioButtonStyle?OutlineNameRadioGroup 下所有input[typeradio]的 name 属性string自动生成Size大小只对按钮样式生效InputSizeInputSize.DefaultOnChange选项变化时的回调EventCallbackTValue-Options通过配置渲染选项支持string[]或RadioOptionTValue[]OneOfstring[], RadioOptionTValue[]-ChildContent直接以子内容声明选项RenderFragment-需要说明的是官方 API 文档中RadioGroup.Disabled的类型标注为string而从 RadioGroup.razor.cs 源码可见其真实类型为boolSize的取值枚举定义在 InputSize.csDefault/Large/SmallButtonStyle枚举定义在 ButtonStyle.csOutline/Solid。Name 的自动生成Name是可选的OnInitialized中若未显式指定则会依次回退到NameAttributeValue ?? PropertyName ?? ComponentIdGenerator.Generate(this)自动生成RadioGroup.razor.cs。这保证了多组 Radio 并存时 name 不会互相干扰同时也允许你手动指定以获得原生浏览器行为。六、不可用状态Disabled官方示例 Disable.razor 展示了单选项禁用与整体切换Radio Checked DisabledDisabled TValueboolDisabled/Radio br / Radio DisabledDisabled TValueboolDisabled/Radio div stylemargin-top: 20px Button TypeButtonType.Primary OnClick_Disabled!DisabledToggle Disabled/Button /div code { bool Disabled true; }Radio.Disabled会同时渲染到原生input的disabled属性与ant-radio-wrapper-disabled/ant-radio-disabledclass见 Radio.razor 与 Radio.razor.cs并在OnClick入口直接 return杜绝点击事件。RadioGroup 禁用同步机制组级Disabled会自动下发AddRadio时若子项未被单独禁用则调用radio.SetDisabledValue(_disabled)并订阅OnDisabledValueChangedRadioGroup.razor.cs之后组Disabled属性变化时所有已订阅子项同步更新。若某个Radio自身已被设为Disabled则组不会覆盖它——这与单元测试Sync_Disabled_exist_disabled_member_radioGroup的断言完全一致RadioGroupTests.razormembers[0].Instance.Disabled.Should().BeTrue()保持不变。七、按钮样式RadioButton 与 ButtonStyle1. 默认描边按钮在组内为每个Radio添加RadioButton属性即可切换为按钮外观示例见 Style.razorRadioGroup bind-ValueradioValue3 Radio RadioButton Value(A)Hangzhou/Radio Radio RadioButton Value(B) DisabledShanghai/Radio Radio RadioButton Value(C)Beijing/Radio Radio RadioButton Value(D)Chengdu/Radio /RadioGroup此时 class 会切换为ant-radio-button-wrapper/ant-radio-button系列Radio.razor.cs单选按钮之间无缝拼接。2. 实色填底样式Solid官方填底示例见 Button_.razorRadioGroup bind-ValueradioValue4 ButtonStyleRadioButtonStyle.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 /RadioGroupButtonStyle与RadioButton是配套使用的组上设置ButtonStyle会把每个子项都渲染为按钮RadioGroup.razor中Options分支会自动带上RadioButtonIsButton而ButtonStyle为空时则按RadioButton逐个声明。两个取值Outline、Solid会被映射为ant-radio-group-outline/ant-radio-group-solidRadioGroup.razor.cs分别对应描边与实色填底两种视觉风格。八、大小大中小三种组合Size仅对按钮样式生效官方示例 Size.razorRadioGroup bind-ValueradioValue5 SizeInputSize.Large 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 !-- 不写 Size 即为默认尺寸 -- RadioGroup bind-ValueradioValue5 !-- ... -- /RadioGroup RadioGroup bind-ValueradioValue5 SizeInputSize.Small !-- ... -- /RadioGroupSize定义在 InputSize.csDefault/Large/Small源码会在组容器上追加ant-radio-group-large或ant-radio-group-smallclassRadioGroup.razor.cs可与表单输入框如Input、InputNumber保持一致的尺寸节奏。九、配合 name 使用让浏览器识别真·分组官方示例 Name.razorRadioGroup bind-ValueradioValue1 Nameradiogroup1 Radio Value(A)A/Radio Radio Value(B)B/Radio Radio Value(C)C/Radio Radio Value(D)D/Radio /RadioGroup div RadioGroup bind-ValueradioValue2 Nameradiogroup2 Radio Value(A)A/Radio ... /RadioGroup /div组上配置的Name会通过radio.SetName(Name)级联到组内所有Radio的原生input[name]上RadioGroup.razor.cs。同名 input 让浏览器把组内选项视为同一个 radio 组从而保留原生行为——例如可以用键盘方向键←/→在同一组内切换选中项。不同分组使用不同 nameradiogroup1/radiogroup2彼此互不干扰。十、配置方式Options 属性渲染除了用ChildContent手写选项还可以通过Options属性配置渲染官方示例 Optional.razorRadioGroup Optionsoptions bind-Value_radioValue/RadioGroup br / RadioGroup Optionsoptions2 bind-Value_radioValue/RadioGroup br/ RadioGroup Optionsoptions2 bind-Value_radioValue ButtonStyleRadioButtonStyle.Outline/RadioGroup code { string _radioValue Apple; string[] options new string[] { Apple, Pear, Orange }; RadioOptionstring[] options2 new RadioOptionstring[] { new(){ Value Apple, Label Apple }, new(){ Value Pear, Label Pear }, new(){ Value Orange, Label Orange }, }; }Options支持两种形态RadioGroup.razor.csstring[]值与标签相同直接渲染RadioOptionTValue[]RadioOptionTValue定义在 RadioOption.cs包含Label、Value、Disabled三个属性可分别定制文案、值与禁用状态。RadioGroup.razor模板在Options非空时优先遍历 Options 渲染Radio否则才渲染ChildContentRadioGroup.razor。测试Sync_Disabled_basic_radioGroup_with_options也验证了 Options 模式下组禁用同样能同步到每个生成的RadioRadioGroupTests.razor。十一、枚举方式EnumRadioGroup当选项恰好对应一个枚举时可以直接使用EnumRadioGroupTEnum官方示例 EnumGroup.razorusing System.ComponentModel.DataAnnotations EnumRadioGroup TEnumFruits bind-Value_radioValue Disabled_disabled Namegroup1/EnumRadioGroup br / EnumRadioGroup TEnumFruits bind-Value_radioValue Disabled_disabled ButtonStyleRadioButtonStyle.Solid Namegroup2/EnumRadioGroup br / Value: _radioValue code { Fruits _radioValue Fruits.Apple; bool _disabled; enum Fruits { [Display(Name Apple)] Apple, Pear, Orange } }EnumRadioGroup本质是RadioGroupTEnum的子类在构造函数中通过EnumHelperTEnum.GetValueLabelList()把枚举成员含[Display(Name ...)]中文/emoji 文案转换为RadioOptionTEnum[]EnumRadioGroup.cs。它继承RadioGroup的全部能力因此Disabled、ButtonStyle、Name、bind-Value均可直接使用非常适合状态机、角色、类型等固定枚举场景。十二、泛型与可空类型绑定RadioGroupTValue是强类型组件官方泛型示例 Generic.razor 覆盖了int、string、bool以及bool?四种典型场景RadioGroup bind-Value_intValue Radio Value11/Radio Radio Value22/Radio Radio Value33/Radio Radio Value44/Radio /RadioGroup RadioGroup bind-Value_nullBoolValue Radio Value(true) TValuebool?Yes/Radio Radio Value(false) TValuebool?No/Radio Radio Value(null) TValuebool?Unknown/Radio /RadioGroup要点Radio.Value是TValue类型比较时使用EqualityComparerTValue.Default.EqualsRadioGroup.razor.cs可空类型如bool?与null值都能正常参与选中比较单元测试Bind_default_null_value_radioGroup与set_value_to_null_radioGroup专门验证了初始值为 null 时不选中任何项、把值置回 null 后取消全部选中的行为RadioGroupTests.razor绑定本身基于AntInputComponentBaseTValue的CurrentValue属性——它先比较新旧值再依次写回Value、调用ValueChanged.InvokeAsync(value)与OnCurrentValueChange并联动EditContext.NotifyFieldChangedAntInputComponentBase.cs因此RadioGroup可以无缝接入Form表单校验体系。十三、垂直布局与条件联动默认多个Radio是水平排布的通过内联Style可以轻松改为垂直布局并可在选中特定选项时动态渲染附加输入框官方示例 Vgroup.razorRadioGroup bind-ValueradioValue Radio Stylestyle Value(A)Option A/Radio Radio Stylestyle Value(B)Option B/Radio Radio Stylestyle Value(C)Option C/Radio Radio Stylestyle Value(M) More... if (radioValue M) { Input TypeInputType.Text TValuestring / } /Radio /RadioGroup code { string radioValue A; string style display: block;height:30px;line-height:30px; }由于Radio继承AntDomComponentBase自带Style参数透传至外层label当radioValue M时ChildContent中的Input会随双向绑定值变化而条件渲染实现选择更多后展开输入框的经典交互模式。十四、动态选项与渲染注意事项如果你的选项列表是动态的例如从接口加载需要注意组件是按值比对选中态的。测试Change_radio_list_and_binding_value_at_same_time展示了一个典型陷阱RadioGroupTests.razor列表从{ 1, 2, 3 }变为{ 2, 3, 4 }、选中值同步变为4时新选项4必须能正确获得checked。实践上建议为动态Radio使用key标识帮助 Blazor 正确复用/重建组件列表与选中值尽量在同一个渲染周期内更新若选项与选中值存在异步时序可借助WaitForElement等测试手段验证最终渲染结果。结语从最简单的用法到RadioGroup的互斥机制Ant Design Blazor 的 Radio 家族通过RadioTValueRadioGroupTValueEnumRadioGroupTValue三个组件覆盖了几乎所有单选场景基础单选、按钮组、大小联动、原生 name 分组、Options 配置、枚举渲染、可空值与表单校验。理解其底层组注册 值比对 统一上下发的实现模型Radio.razor.cs、RadioGroup.razor.cs你就能在真实业务中快速定位选中异常、禁用不同步等问题并借助 RadioGroupTests.razor 中的测试思路验证自己的实现。相关源码与文档入口组件演示API 文档Radio 实现RadioGroup 实现赞分享前端UI组件设计系统【免费下载链接】ant-design-blazor基于 Ant Design 与 Blazor 的前端组件库。让开发者解放生产力实现更大价值。项目地址https://gitcode.com/ant-design-blazor/ant-design-blazor点击查看免费下载相关推荐ant-design-blazor单选框组件实战Radio高级用法ant design blazor单选框组件实战Radio高级用法 一、单选框Radio组件核心价值与应用场景 在企业级Blazor应用开发中单选框RUI组件前端Ant Design Blazor Checkbox 多选框组件完全指南基础用法、分组全选与混合模式实战Ant Design Blazor Checkbox 多选框组件完全指南基础用法、分组全选与混合模式实战 多选框Checkbox是 Ant DesignUI组件前端ts-jest 与 React Native 集成为 TypeScript Babel 7 项目配置 Jest 测试ts jest 与 React Native 集成为 TypeScript Babel 7 项目配置 Jest 测试 ts jest 作为支持 sourc测试开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考