ng-zorro-antd Radio 填底按钮样式（Solid Radio Button）完整指南

• UI组件
• 前端

导读

本文围绕 ng-zorro-antd 的 Radio 单选框组件展开，重点讲解其nzButtonStyle="solid"填底按钮样式（Solid Radio Button）的用法、源码实现与样式原理。你将学会如何通过一行配置把默认的描边按钮切换为实色填底的按钮形态，了解它与outline描边风格在实现与视觉上的差异，并掌握与之配套的尺寸、禁用、双向绑定与表单集成等实战要点。文章以 solid.md 演示文档为主体，结合 radio-group.component.ts 与 radio.component.ts 的源码，以及 radio 样式表 深入剖析其底层原理。

一、什么是填底按钮样式

ng-zorro-antd 的 Radio 组件除了默认的单选圆点形态（[nz-radio]），还提供了按钮形态（[nz-radio-button]），即以一组相连的按钮来呈现互斥选项。按钮形态下，nz-radio-group通过nzButtonStyle属性提供两种风格：

该参数的默认值为'outline'，类型为'outline' \| 'solid'，在 radio-group.component.ts 中定义：

export type NzRadioButtonStyle = 'outline' | 'solid';

solid模式即 solid.md 中所说的"实色填底的单选按钮样式"，适用于需要强调当前选中项、视觉权重更高的场景，例如步骤切换、状态筛选等。

二、快速上手：solid 填底按钮示例

2.1 完整示例代码

components/radio/demo/solid.ts 提供了官方演示，完整代码如下：

import { Component, signal } from '@angular/core'; import { FormsModule } from '@angular/forms'; import { NzRadioModule } from 'ng-zorro-antd/radio'; @Component({ selector: 'nz-demo-radio-solid', imports: [FormsModule, NzRadioModule], template: ` <nz-radio-group [(ngModel)]="value" nzButtonStyle="solid"> <label nz-radio-button nzValue="A">Hangzhou</label> <label nz-radio-button nzValue="B">Shanghai</label> <label nz-radio-button nzValue="C">Beijing</label> <label nz-radio-button nzValue="D">Chengdu</label> </nz-radio-group> ` }) export class NzDemoRadioSolidComponent { readonly value = signal('A'); }

2.2 关键点拆解

1. 模块导入：示例通过imports: [FormsModule, NzRadioModule]引入NzRadioModule（定义于 radio.module.ts）与FormsModule，这是使用[(ngModel)]双向绑定所必需的。
2. 开启填底风格：在nz-radio-group上设置nzButtonStyle="solid"，即完成从默认描边到填底的全部切换，无需修改任何子选项。
3. 按钮选项：每个选项使用label nz-radio-button nzValue="..."声明，nzValue作为该选项的实际取值，与 group 的ngModel值进行匹配。
4. 双向绑定：[(ngModel)]="value"绑定组件内的信号值value，初始值为'A'，对应选中"Hangzhou"。

渲染后，选中项（Hangzhou）将以主题色整块填底、文字反白，其余选项保持白底描边；点击任意选项即可切换选中项并同步更新value。

提示：直接复制上面代码到 Angular 组件中即可运行，仓库中对应的演示组件文件为 solid.ts，演示文档说明见 solid.md。

三、源码级原理：solid 风格如何生效

3.1 样式类由 group 统一下发

填底风格并非在单个按钮上独立实现，而是由nz-radio-group统一控制。radio-group.component.ts 的宿主绑定如下：

host: { class: 'ant-radio-group', '[class.ant-radio-group-large]': `finalSize() === 'large'`, '[class.ant-radio-group-small]': `finalSize() === 'small'`, '[class.ant-radio-group-solid]': `nzButtonStyle === 'solid'`, '[class.ant-radio-group-rtl]': `dir() === 'rtl'` }

可以看到，当nzButtonStyle === 'solid'时，nz-radio-group宿主元素会被加上ant-radio-group-solid类。这正是 radio/style/index.less 中填底样式生效的选择器基础：

.@{radio-group-prefix-cls}-solid &-checked:not(&-disabled) { color: @radio-solid-checked-color; background: @radio-dot-color; border-color: @radio-dot-color; &:hover { color: @radio-solid-checked-color; background: @radio-button-hover-color; border-color: @radio-button-hover-color; } &:active { color: @radio-solid-checked-color; background: @radio-button-active-color; border-color: @radio-button-active-color; } &:focus-within { box-shadow: @radio-button-focus-shadow; } }

即：处于solid的 group 内、处于选中态且未禁用的按钮，其背景色、边框色、文字色全部切换为填底配色。

3.2 主题变量解析

上述 Less 中引用的颜色变量在 components/style/themes/default.less 中定义：

@radio-dot-color: @primary-color; // 选中主题色 @radio-solid-checked-color: @component-background; // 填底后文字反白为组件背景色 @radio-button-hover-color: @primary-5; // hover 态主题色 @radio-button-active-color: @primary-7; // active 态主题色 @radio-button-bg: @btn-default-bg; @radio-button-color: @btn-default-color; @radio-disabled-button-checked-bg: @disabled-active-bg; @radio-disabled-button-checked-color: @disabled-color;

从中可以读出 solid 风格的配色逻辑：

• 选中态：背景为@primary-color（主题色），文字为@radio-solid-checked-color（组件背景色，即白色系），形成"主题色填底 + 反白文字"；
• hover 态：背景过渡为主题色 5 号色（@primary-5）；
• active 态：背景过渡为主题色 7 号色（@primary-7）；
• 这些变量同时支持暗色主题（dark.less 中@radio-solid-checked-color: @white）与变量主题（variable.less），因此 solid 风格会随主题自动适配。

3.3 选中态如何联动到按钮

填底样式的呈现依赖每个按钮的选中态。在 radio.component.ts 中，每个nz-radio-button订阅nzRadioService的selected$流，通过this.nzValue === value判断自身是否选中，并据此切换isChecked：

this.nzRadioService.selected$.pipe(takeUntilDestroyed(this.destroyRef)).subscribe(value => { const isChecked = this.isChecked; this.isChecked = this.nzValue === value; ... });

选中态最终体现为按钮宿主上的ant-radio-button-wrapper-checked类（见 radio.component.ts 的'[class.ant-radio-button-wrapper-checked]': 'isChecked && isRadioButton'），该类的样式规则（index.less）再与 group 的ant-radio-group-solid叠加，就得到我们看到的填底效果。

四、与 outline 描边风格对比

默认的outline风格与solid风格的选中态样式在 index.less 中成对出现：

• outline（默认）：选中项color: @radio-dot-color; background: @radio-button-checked-bg; border-color: @radio-dot-color;（index.less），即主题色文字 + 主题色描边，背景保持浅色；
• solid（填底）：选中项background: @radio-dot-color;（主题色整块填充），文字反白。

两者在 DOM 结构、数据绑定逻辑上完全一致，唯一的差异就是 group 上的ant-radio-group-solid类。因此：

• 切换风格只需修改nzButtonStyle一个属性；
• 表单集成、禁用、尺寸等能力在两种风格下完全通用。

未选中项的样式（白底描边、hover 变主题色）在两种风格下相同，差异仅体现在选中项的视觉权重上——这正是 solid 适合强调当前状态的原因。

五、实战进阶：尺寸、禁用与表单结合

填底风格可与其他 group 级能力自由组合，下面给出几个实用变体。

5.1 结合尺寸（nzSize）

nzSize支持'large' | 'small' | 'default'，只对按钮样式生效（见 radio-group.component.ts）。与 solid 组合使用：

<nz-radio-group [(ngModel)]="value" nzButtonStyle="solid" nzSize="large"> <label nz-radio-button nzValue="A">Hangzhou</label> <label nz-radio-button nzValue="B">Shanghai</label> <label nz-radio-button nzValue="C">Beijing</label> </nz-radio-group>

尺寸类ant-radio-group-large/ant-radio-group-small同样由 group 宿主绑定统一添加（radio-group.component.ts），其高度与字号定义见 index.less。组内也可混用<nz-radio>（普通单选点）与<label nz-radio-button>（按钮形态），视觉上自动区分。

5.2 结合禁用（nzDisabled）

禁用可作用于整个 group（nzDisabled）或单个按钮：

<nz-radio-group [(ngModel)]="value" nzButtonStyle="solid"> <label nz-radio-button nzValue="A">Hangzhou</label> <label nz-radio-button nzValue="B" nzDisabled>Shanghai</label> <label nz-radio-button nzValue="C">Beijing</label> <label nz-radio-button nzValue="D" nzDisabled>Chengdu</label> </nz-radio-group>

填底样式规则中的:not(&-disabled)确保禁用的选中项不会套用填底配色，而是回退到@radio-disabled-button-checked-bg/@radio-disabled-button-checked-color（index.less），保持禁用态的可辨识度。group 级nzDisabled通过nzRadioService.setDisabled()向所有按钮广播禁用状态（radio-group.component.ts）。

5.3 结合表单（Reactive Forms / 模板驱动）

nz-radio-group实现了ControlValueAccessor（radio-group.component.ts），因此同时支持模板驱动（[(ngModel)]）与响应式表单（formControlName/formControl）：

// 响应式表单 import { Component } from '@angular/core'; import { FormBuilder, ReactiveFormsModule, Validators } from '@angular/forms'; import { NzRadioModule } from 'ng-zorro-antd/radio'; @Component({ selector: 'app-solid-radio-form', imports: [ReactiveFormsModule, NzRadioModule], template: ` <form [formGroup]="form"> <nz-radio-group formControlName="city" nzButtonStyle="solid"> <label nz-radio-button nzValue="A">Hangzhou</label> <label nz-radio-button nzValue="B">Shanghai</label> <label nz-radio-button nzValue="C">Beijing</label> </nz-radio-group> </form> ` }) export class SolidRadioFormComponent { readonly form = new FormBuilder().group({ city: ['A', Validators.required] }); }

group 的writeValue()会通过nzRadioService.select(value)同步选中态（radio-group.component.ts），selected$的变化再反向触发onChange()，实现完整的表单双向联动。

六、常见问题排查

Q1：设置了nzButtonStyle="solid"但没有任何变化？检查是否使用了按钮形态（label nz-radio-button），solid 只对按钮形态生效；普通nz-radio单选点始终是圆点样式。

Q2：选中项没有填底？确认该按钮未被禁用（禁用选中项刻意不套用填底配色），并确认 group 上确实绑定了nzButtonStyle="solid"。

Q3：填底颜色不是我想要的主题色？填底色取自@primary-color（即@radio-dot-color），可通过主题定制调整主色变量，见 components/style/themes/default.less；相关主题定制方式可参考仓库 customize-theme 文档。

Q4：尺寸没生效？nzSize只对按钮样式生效，且需设置在nz-radio-group上；如果组件处于表单上下文中，最终尺寸由NZ_FORM_SIZE决定（finalSize的计算见 radio-group.component.ts）。

七、参考与延伸阅读

• 演示文档与源码：solid.md、solid.ts
• 组件 API 文档：index.zh-CN.md、index.en-US.md
• 核心实现：radio-group.component.ts、radio.component.ts、radio.service.ts
• 样式实现：components/radio/style/index.less、entry.less、patch.less
• 相关演示：radiobutton.md（按钮形态基础用法）、size.md（大中小尺寸）、disable.md（禁用态）、radiogroup-options.md（options 配置方式）
• 主题变量：默认主题 default.less、暗色主题 dark.less、变量主题 variable.less

• UI组件
• 前端