企业官网建设流程全解析

• UI组件
• 前端

导读

Rate（评分）是 ng-zorro-antd 中用于“对事物进行评分操作”的数据录入组件，既能以只读方式展示评价结果，也能让用户通过鼠标或键盘快速完成星级评级。本文以 Rate 官方中文文档 为主体，完整展开其全部 API 与交互行为，并结合 rate.component.ts 与 rate-item.component.ts 源码，深入讲解半星、清除、键盘操作、自定义字符等能力的底层实现，最后给出仓库内全部 7 个官方示例的完整落地写法，帮助你从“会用”进阶到“懂原理”。

一、何时使用 Rate

根据官方文档，Rate 组件适用于两类典型场景：

• 对评价进行展示：例如商品详情页展示历史评分，此时通常配合nzDisabled只读模式使用；
• 对事物进行快速的评级操作：例如用户提交打分、问卷评分等交互场景，配合表单的双向绑定使用。

Rate 属于数据录入类组件，与 Input、Select 一样支持ngModel双向绑定与响应式表单（ControlValueAccessor）。

二、API 完整参考

以下为官方文档中nz-rate组件的全部属性、事件与方法，均已对照 rate.component.ts 源码核实默认值与类型。

2.1 输入属性（Properties）

几个值得注意的细节：

• nzAllowClear与nzAllowHalf在源码中通过@WithConfig()标记，属于支持全局配置的属性，可在NzConfigService中统一设置（见 rate.component.ts）；组件构造函数中注册了onConfigChangeEventForComponent('rate', ...)，当全局配置变化时会自动触发视图刷新（rate.component.ts）。
• nzCount使用numberAttribute转换、布尔属性使用booleanAttribute转换，因此在模板中可以直接写nzCount="10"、nzAllowHalf这种简洁写法。
• nzCharacter的类型在源码中实际上是TemplateRef<{ $implicit: number }>，即模板上下文会传入当前星标索引，可据此实现“按索引定制字符”（详见第五章）。

2.2 输出事件（Events）

源码中focus/blur事件通过fromEventOutsideAngular在 NgZone 之外监听，仅在存在订阅者时才通过ngZone.run派发事件，避免无谓的变更检测开销（见 rate.component.ts）。

2.3 方法（Methods）

对应源码实现为直接调用组件根元素（ul.ant-rate）的focus()与blur()（rate.component.ts）。若在模板中通过exportAs: 'nzRate'获取组件实例（<nz-rate #rate="nzRate" />），即可调用这两个方法。

三、快速上手：基础用法

3.1 模块引入

Rate 组件以独立模块发布，在 Angular 独立组件模式下直接导入即可：

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

对应的官方示例见 demo/basic.ts，这是 Rate 的最简用法：一个 5 星、默认实心星、支持点击清除的评分条。

3.2 双向绑定

nz-rate实现了ControlValueAccessor（见 rate.component.ts 的NG_VALUE_ACCESSOR提供者），因此可以无缝接入 Angular 表单体系：

<!-- 模板驱动表单 --> <nz-rate [(ngModel)]="score"></nz-rate> <!-- 响应式表单 --> <form [formGroup]="form"> <nz-rate formControlName="rating"></nz-rate> </form>

writeValue方法负责外部值写入时刷新星标样式，setDisabledState负责表单禁用状态与nzDisabled的合并（rate.component.ts）。

四、交互行为与源码原理

4.1 内部渲染结构

组件的 DOM 结构分为两层（见 rate.component.ts 模板）：

ul.ant-rate └── li.ant-rate-star × N（每颗星，可挂 nz-tooltip） └── div[nz-rate-item] ← 由 NzRateItemComponent 渲染

而每个nz-rate-item内部又拆成两个半区（见 rate-item.component.ts）：

• div.ant-rate-star-second：右半星区域，mouseover/click时上报isHalf = false；
• div.ant-rate-star-first：左半星区域，mouseover/click时上报isHalf = true。

hoverRate(isHalf)中做了isHalf && this.allowHalf的收窄——只有开启nzAllowHalf时，左半区才会被当作半星处理（rate-item.component.ts）。这从源码层面解释了“半星为何只在允许半选时生效”。

4.2 半星（Half star）

<nz-rate nzAllowHalf [(ngModel)]="score"></nz-rate>

开启nzAllowHalf后，点击左半区会得到index + 0.5的取值。在onItemClick中，实际值由isHalf ? index + 0.5 : index + 1计算得出（rate.component.ts）。

星标样式的核心在updateStarStyle（rate.component.ts）：根据hoverValue与hasHalf为每颗星计算ant-rate-star-full / -half / -active / -zero / -focused五个状态类。这也是实现“鼠标划过即时预览评分”的关键：onItemHover只更新内部hoverValue并刷新样式，并不改动表单值；只有真正点击时才写回ngModel（rate.component.ts）。

4.3 清除（Clear star）

<nz-rate nzAllowClear [(ngModel)]="score"></nz-rate>

默认nzAllowClear = true：当再次点击与当前值相同的星级时，评分被重置为 0（见 rate.component.ts 中this.nzValue === actualValue分支）。若设置为false，则重复点击不会清除，只能通过改选其他星级来变更。

4.4 键盘无障碍操作

组件根元素带tabindex（禁用时为-1），支持键盘操作（rate.component.ts）：

• 按→（RIGHT_ARROW）：分值加 1；若开启nzAllowHalf则每次加 0.5；
• 按←（LEFT_ARROW）：分值减 1；若开启nzAllowHalf则每次减 0.5；
• 按键引起数值变化时触发(nzOnKeyDown)事件。

配合nzAutoFocus（设为true时在组件初始化后给根元素加上autofocus属性）即可实现键盘即用、无需鼠标的评分体验。

4.5 鼠标离开复位

当鼠标移出整个组件（mouseleave）时，onRateLeave会把预览值复位为当前实际值：hasHalf根据当前值是否为小数重新计算，hoverValue取Math.ceil(nzValue)，并触发一次nzOnHoverChange（rate.component.ts）。这正是“划过时预览、离开后回弹”的视觉机制。

五、自定义：字符与文案

5.1 替换默认星星为任意字符

nzCharacter接收一个TemplateRef，可将默认的nz-icon nzType="star"替换为字母、数字、字体图标甚至中文。官方示例 demo/character.ts 展示了三种替换：

<!-- 爱心图标 --> <ng-template #characterIcon><nz-icon nzType="heart" /></ng-template> <!-- 中文单字 --> <ng-template #characterZhLetter>好</ng-template> <!-- 英文字母 --> <ng-template #characterEnLetter>A</ng-template> <nz-rate [ngModel]="0" nzAllowHalf [nzCharacter]="characterIcon" /> <nz-rate [ngModel]="0" nzAllowHalf [nzCharacter]="characterZhLetter" />

在 rate-item.component.ts 中，字符模板通过ngTemplateOutletContext注入{ $implicit: index }上下文，即模板内可拿到当前星标的索引。

5.2 按索引定制每个字符

因为模板上下文携带索引，可以做到“每一颗星各不相同”。官方示例 demo/customize.ts 用索引映射情绪图标：

<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> <nz-rate [ngModel]="3" [nzCharacter]="characterIcon" />

示例中还演示了通过::ng-deep .ant-rate-star { font-size: 36px; }放大字符尺寸的样式技巧。

5.3 文案展现与 Tooltip

通过nzTooltips传入与星级数量等长的文案数组，鼠标悬停与选中时即可展示对应提示；再配合(ngModelChange)或 signal 在组件旁输出当前文案。官方示例 demo/text.ts：

const tooltips = ['terrible', 'bad', 'normal', 'good', 'wonderful'];

<nz-rate [(ngModel)]="value" [nzTooltips]="tooltips" /> @if (value(); as rate) { <span class="ant-rate-text">{{ rate ? tooltips[rate - 1] : '' }}</span> }

底层实现中，每颗li.ant-rate-star都挂载了nz-tooltip，[nzTooltipTitle]绑定到nzTooltips[$index]（见 rate.component.ts），因此提示会逐星跟随鼠标出现。

六、只读展示与全局配置

6.1 只读模式

<nz-rate [ngModel]="3" nzDisabled></nz-rate>

设置nzDisabled后：

• 根元素获得ant-rate-disabled样式类并呈现灰化视觉（rate.component.ts）；
• onItemClick与onItemHover开头均直接return，点击、悬停、键盘改动全部失效（rate.component.ts）；
• tabindex变为-1，组件不可聚焦。

这正适用于“对评价进行展示”的场景，官方示例见 demo/disabled.md。

6.2 全局配置

nzAllowClear与nzAllowHalf支持全局配置。可在应用启动时通过provideNzConfig统一设置：

import { provideNzConfig } from 'ng-zorro-antd/core/config'; export const appConfig: ApplicationConfig = { providers: [ provideNzConfig({ rate: { nzAllowHalf: true, nzAllowClear: false } }) ] };

组件内部通过WithConfig()装饰器读取全局配置作为默认值，并在全局配置变化时自动重绘（rate.component.ts 与 rate.component.ts）。

七、示例速查

仓库 components/rate/demo 目录下共提供 7 个官方示例，覆盖了本文涉及的全部能力，可按需对照查阅：

组件的模块导出与样式入口分别位于 public-api.ts、index.ts 与 style/index.less；完整的行为测试用例可在 rate.spec.ts 中查看，其中覆盖了点击评分、半星、清除、禁用、键盘操作等核心交互的断言，是理解组件行为契约的最佳参考。

结语

Rate 组件的 API 看似简单，但通过阅读 rate.component.ts 可以看清其设计巧思：左右半区分离实现了半星、hoverValue与hasHalf双状态驱动样式预览、NgZone 外监听事件减少变更检测开销、ControlValueAccessor无缝接入表单。掌握了这些原理，无论是定制字符、配置全局默认值，还是排查交互异常，都能游刃有余。

• UI组件
• 前端