ng-zorro-antd Rate 评分组件完全指南：API 详解、表单集成与源码实现原理

• UI组件
• 前端

本指南围绕 ng-zorro-antd（Angular UI 组件库）中的 Rate 评分组件展开，系统讲解其全部输入/输出属性、组件方法与全局配置能力，并结合 rate.component.ts 源码与 rate 组件演示用例 剖析评分交互、半星机制、键盘操作与双向绑定的底层实现。读完本文，你将掌握 Rate 组件的完整配置方式，并能基于nzCharacter模板与表单集成实现自定义的评分场景。

何时使用 Rate 组件

Rate 组件用于对某事物进行评分操作，在 ng-zorro-antd 中对应的选择器为nz-rate，官方使用场景界定如下：

• 展示评价：以星级形式直观呈现他人或系统对某对象（商品、内容、服务等）的评价结果；
• 快速评分操作：让用户通过点击或键盘快速完成一次打分，例如满意度调查、内容质量评分等。

从源码结构看，Rate 组件由两个文件构成：rate.component.ts（对外主组件，负责状态管理与事件分发）和 rate-item.component.ts（内部单颗星星渲染单元，负责半星与悬停反馈）。模块入口为 rate.module.ts，使用前在组件中引入NzRateModule即可，例如官方 basic 示例：

import { Component } from '@angular/core'; import { FormsModule } from '@angular/forms'; import { NzRateModule } from 'ng-zorro-antd/rate'; @Component({ selector: 'nz-demo-rate-basic', imports: [FormsModule, NzRateModule], template: `<nz-rate [ngModel]="0" />` }) export class NzDemoRateBasicComponent {}

API 属性详解

nz-rate组件的全部可配置属性如下表所示：

交互与显示类属性

• nzAllowClear（默认true）：决定用户点击当前已选中的分值后是否将评分清零。实现位于 rate.component.ts 的onItemClick：当nzValue与点击得到的actualValue相等且nzAllowClear为真时，将值重置为0并触发onChange。官方 clear 示例 展示了同一把评分在允许清除与禁止清除两种配置下的行为对比。

• nzAllowHalf（默认false）：是否支持半星评分。启用后ngModel可以携带如2.5这样的小数值，例如 half 示例 中的<nz-rate [ngModel]="2.5" nzAllowHalf />。半星的核心实现见下文「半星与悬停的源码剖析」。

• nzAutoFocus（默认false）：组件挂载后自动聚焦。源码中通过ngOnChanges监听该属性的变化，并在非首次变更时给内部<ul>元素动态添加或移除autofocus特性（见 rate.component.ts）。

• nzCount（默认5）：星星总数。变更时调用updateStarArray()重新生成星星索引数组starArray（见 rate.component.ts）。

• nzDisabled（默认false）：只读模式。除了在模板上为<ul>添加ant-rate-disabled类、并把tabindex置为-1外，源码还在onItemClick与onItemHover入口处直接拦截返回，确保禁用状态下点击与悬停均不生效（见 rate.component.ts）。官方 disabled 示例 用法为<nz-rate [ngModel]="2" nzDisabled />。

• nzTooltips（默认[]）：为每一颗星星配置 tooltip 文案的字符串数组。模板中每个<li>都挂载了nz-tooltip指令，并将nzTooltips[$index]作为提示标题（见 rate.component.ts）。官方 text 示例 中将其与ant-rate-text文本配合展示等级文案：

@Component({ selector: 'nz-demo-rate-text', imports: [FormsModule, NzRateModule], template: ` <nz-rate [(ngModel)]="value" [nzTooltips]="tooltips" /> @if (value(); as rate) { <span class="ant-rate-text">{{ rate ? tooltips[rate - 1] : '' }}</span> } ` }) export class NzDemoRateTextComponent { readonly tooltips = ['terrible', 'bad', 'normal', 'good', 'wonderful']; readonly value = signal(3); }

自定义字符nzCharacter

nzCharacter接受一个TemplateRef，用于替换默认的星形图标（默认渲染<nz-icon nzType="star" nzTheme="fill" />，见 rate-item.component.ts）。它可以把星星替换为字母、数字、图标字体甚至中文，character 示例 给出了三种典型用法：

<nz-rate [ngModel]="0" nzAllowHalf [nzCharacter]="characterIcon" /> <br /> <nz-rate [ngModel]="0" nzAllowHalf class="large" [nzCharacter]="characterEnLetter" /> <br /> <nz-rate [ngModel]="0" nzAllowHalf [nzCharacter]="characterZhLetter" /> <ng-template #characterIcon><nz-icon nzType="heart" /></ng-template> <ng-template #characterZhLetter>好</ng-template> <ng-template #characterEnLetter>A</ng-template>

更进一步，模板可以接收当前星星的索引（模板上下文中的$implicit为索引值），实现「按索引逐个定制字符」的 customize 示例，例如用表情图标表达渐进式满意度：

<ng-template #characterNumber let-index> {{ index + 1 }} </ng-template> <ng-template #characterIcon let-index> @switch (index) { @case (0) { <nz-icon nzType="frown" /> } @case (1) { <nz-icon nzType="frown" /> } @case (2) { <nz-icon nzType="meh" /> } @case (3) { <nz-icon nzType="smile" /> } @case (4) { <nz-icon nzType="smile" /> } } </ng-template>

$implicit索引的注入位置在 rate-item.component.ts：内部通过ngTemplateOutletContext将{ $implicit: index }传入自定义模板，同时在未提供自定义模板时回退到默认星形图标。

事件回调

• (ngModelChange)：选中值变化时触发，配合[ngModel]完成双向绑定；
• (nzOnHoverChange)：悬停/离开某颗星星时触发，参数为当前悬停分值。onItemHover与onRateLeave均会发出该事件（见 rate.component.ts），适合做实时预览文案等联动效果；
• (nzOnFocus)/(nzOnBlur)：组件获得/失去焦点时触发。源码在ngOnInit中通过fromEventOutsideAngular订阅<ul>的focus与blur事件，仅在存在订阅者时才进入 Angular Zone 派发事件（见 rate.component.ts），兼顾性能；
• (nzOnKeyDown)：组件上发生键盘事件时触发，仅在键盘操作真正改变评分值时发出（见 rate.component.ts）。

组件方法

这两个方法直接作用于内部<ul>原生元素：focus()调用ulElement.nativeElement.focus()，blur()调用ulElement.nativeElement.blur()（见 rate.component.ts）。需要程序化控制焦点时，可通过@ViewChild(NzRateComponent)获取实例后调用。

全局配置

nzAllowClear与nzAllowHalf两项属性支持通过 ng-zorro-antd 的全局配置体系统一设置（表格中 Global Config 列为 ✅）。源码中这两项属性同时标注了@WithConfig()装饰器，并以rate作为配置模块名（见 rate.component.ts）。配置方式为调用NzConfigService的set方法，例如统一关闭清除并开启半星：

import { NzConfigService } from 'ng-zorro-antd/core/config'; constructor(private nzConfigService: NzConfigService) { this.nzConfigService.set('rate', { nzAllowClear: false, nzAllowHalf: true }); }

组件构造时还会通过onConfigChangeEventForComponent('rate', ...)订阅全局配置变更事件并触发重新检测（见 rate.component.ts），保证运行期修改全局配置能即时反映到已渲染的组件上。

半星与悬停的源码剖析

Rate 组件的半星与悬停反馈依赖内部nz-rate-item指令式组件实现。每个评分单元渲染为两层结构（见 rate-item.component.ts）：

• ant-rate-star-second：前半层，mouseover/click时以false上报事件；
• ant-rate-star-first：后半层，mouseover/click时以true上报事件。

事件是否被当作「半星」处理，由hoverRate(isHalf)与clickRate(isHalf)中的isHalf && this.allowHalf决定——只有开启了nzAllowHalf时，后半层悬停/点击才会计为半星（见 rate-item.component.ts）。父组件 rate.component.ts 的onItemClick据此计算实际分值：isHalf ? index + 0.5 : index + 1。

评分值到 CSS 类的映射集中在updateStarStyle()（见 rate.component.ts），通过为每颗星计算ant-rate-star-full/-half/-active/-zero/-focused等类名驱动 index.less 中的视觉样式，从而实现整星、半星、聚焦态的差异化渲染。

表单集成与键盘可访问性

Rate 组件实现了ControlValueAccessor（在providers中以NG_VALUE_ACCESSOR多提供项注册，见 rate.component.ts），因此可以无缝配合 Angular 的模板驱动表单与响应式表单：

• writeValue(value)：将外部值写入组件，同时更新星星样式（见 rate.component.ts）；
• registerOnChange/registerOnTouched：注册值变化与 touched 回调（见 rate.component.ts）；
• setDisabledState：响应表单的禁用状态，与nzDisabled输入叠加生效（见 rate.component.ts）。

键盘操作方面，源码在<ul>上监听了keydown，并阻止默认行为：RIGHT_ARROW在未达上限时增加分值（开启半星时每次0.5，否则每次1），LEFT_ARROW在大于0时相应减少；只有分值实际变化时才触发onChange、nzOnKeyDown与样式刷新（见 rate.component.ts）。结合[tabindex]="nzDisabled ? -1 : 0"（见 rate.component.ts），未禁用状态下用户可直接聚焦评分组件并用方向键打分，满足键盘可访问性要求。

样式与 RTL 支持

组件样式位于 style/index.less，组件自身采用ViewEncapsulation.None，允许外部通过全局样式或::ng-deep覆盖星星尺寸等细节，如 character 示例 中通过::ng-deep .ant-rate-star { font-size: 36px; }放大评分字符。此外，组件通过注入Directionality的valueSignal检测文档方向，并在模板中为<ul>添加ant-rate-rtl类（见 rate.component.ts），因此在 RTL 布局下评分方向会自动镜像，无需额外处理。

快速上手清单

1. 在组件中引入NzRateModule（必要时同时引入FormsModule以使用ngModel双向绑定）；
2. 基础评分：<nz-rate [(ngModel)]="value" />；
3. 需要半星：追加nzAllowHalf，并将初始值设为x.5形式；
4. 需要只读展示：追加nzDisabled，只传入[ngModel]即可；
5. 需要自定义图形或文字：通过[nzCharacter]传入ng-template，模板上下文$implicit为星星索引；
6. 需要星级文案：传入与nzCount等长的[nzTooltips]字符串数组，并配合(nzOnHoverChange)或(ngModelChange)展示当前等级文案；
7. 需要统一默认行为：通过NzConfigService.set('rate', ...)全局配置nzAllowClear与nzAllowHalf。

以上用法均有对应演示用例可供参考：基础见 basic.ts、半星见 half.ts、清除行为见 clear.ts、自定义字符见 character.ts 与 customize.ts、只读见 disabled.ts、提示文案见 text.ts。

• UI组件
• 前端