Ant Design Blazor Rate 评分组件：API 详解与源码实现原理

• UI组件
• 前端

Rate 是 Ant Design Blazor 提供的数据录入型评分组件，用于对评价进行展示或对事物进行快速的星级评级操作。本文将基于仓库内官方文档 Rate 组件文档，结合 Rate.razor.cs 等源码实现，完整梳理其全部 API 参数、实例方法与六类典型用法，并深入讲解其渲染结构、事件处理、键盘交互与样式定制原理，帮助你在 Blazor 应用中正确、灵活地使用评分组件。

何时使用 Rate 评分组件

官方文档明确了 Rate 组件的两个典型应用场景：

• 对评价进行展示（Show evaluation）：例如商品评分、课程评分、内容质量反馈等只读展示场景；
• 对事物进行快速的评级操作（A quick rating operation on something）：例如用户打分、满意度调查、服务评价等可交互场景。

这两类场景分别对应组件的只读（Disabled）与可交互（默认）两种形态，配合Tooltips、Character等参数可以组合出丰富的业务表现。

快速上手：最简单的用法

Rate 组件最简单的用法只需一行代码：

<Rate />

它默认渲染 5 颗星，默认值为 0，用户点击任意一颗星即可完成评分。完整示例可参考官方 Demo 目录下的 Basic.razor。

API 参数详解

官方文档提供了一份完整的参数表。需要说明的是：文档中的className、style、onChange等为 Ant Design 生态通用的命名，在 Blazor 实现中对应 PascalCase 的组件参数（ClassName、Style、ValueChanged等）。以下为完整参数清单及源码确认的默认值：

以上表格以官方文档为准；其中部分参数（如OnHoverChange、OnKeyDown、ClassName、Style）目前主要依赖基类AntDomComponentBase提供的基础能力或仍处于 API 演进阶段，实际使用时请以当前 NuGet 包发布版本为准。

受控值 Value 与双向绑定

Value是组件的受控值，类型为decimal（而非文档示例中的 number），这意味着它支持 0.5 这类半星数值。从 Rate.razor.cs 的源码可以看到，Value的 setter 会同步更新内部状态并触发ValueChanged回调：

[Parameter] public decimal Value { get { return _currentValue; } set { _valueWasSet = true; if (_currentValue != value) { this._currentValue = value; this._hasHalf = !(_currentValue == (int)_currentValue); this._hoverValue = (int)Math.Ceiling(value); ValueChanged.InvokeAsync(value); } } }

_hasHalf用于标记当前值是否为非整数（半星），_hoverValue记录悬停位置。在 Blazor 中你通常直接使用双向绑定语法：

<Rate @bind-Value="score" />

组件实例方法

官方文档给出了两个实例方法：

在 Razor 中可通过@ref拿到组件实例后调用：

<Rate @ref="rate" /> @code { private Rate rate; private void ClearFocus() => rate.Focus(); }

六大典型用法与实战示例

官方 Demo 目录（Rate demo 目录）提供了 6 个可直接运行的示例，覆盖了组件的主要能力。

1. 基本用法

最简单的评分，见 Basic.razor：

<Rate />

2. 半星评分

通过AllowHalf="true"允许选择半星，DefaultValue可传入带小数点的值，注意 Blazor 中字面量需加M后缀表示 decimal，见 Half.razor：

<Rate AllowHalf="true" DefaultValue="3.5M" />

半星实现的关键在于每颗星被拆分为左右两个半区，具体原理见下文"渲染结构"一节。

3. 文案展示（Tooltips）

评分组件本身不显示文字，但可通过Tooltips为每一档评分配置提示文案，并结合双向绑定在页面中展示当前档位的文字，见 Text.razor：

<Rate @bind-Value="value" Tooltips="@desc" /> <span class="ant-rate-text">@(desc[(int)value-1])</span> @code { string[] desc = new string[] { "terrible", "bad", "normal", "good", "wonderful" }; decimal value = 3M; }

Tooltips是一个字符串数组，数组下标与星位一一对应（从 0 开始）。从 Rate.razor.cs 可以看出，组件在初始化时会按Count生成元数据并逐项取Tooltips中对应下标的文本：

RateMetaDatas = Enumerable.Range(1, Count).Select(c => new RateMetaData() { SerialNumber = c - 1, ToolTipText = this.Tooltips?[c - 1] });

当某一颗星配置了提示文本时，RateItem.razor 会用Tooltip组件包裹该星实现悬停提示，因此组件样式文件 entry.less 中额外引入了 tooltip 的样式依赖。

4. 只读模式

设置Disabled后组件只读，无法通过鼠标交互，适合评价展示场景，见 Disabled.razor：

<Rate Disabled DefaultValue="2" />

从源码看，Disabled的作用体现在两个层面：

• 交互层面：Rate.razor.cs 中的ItemHoverChange与ItemClick均在方法入口处直接return，屏蔽悬停和点击；
• 样式层面：SetClass() 会追加ant-rate-disabled类，index.less 中对该类下的星设置cursor: default并取消悬停放大效果。

5. 支持清除 / 禁止清除

AllowClear控制再次点击当前选中值时是否将评分清零，默认true。对比示例见 Clear.razor：

<Rate AllowClear="true" DefaultValue="2" /> <span class="ant-rate-text">AllowClear: true</span> <br /> <Rate AllowClear="false" DefaultValue="3"></Rate> <span class="ant-rate-text">AllowClear: false</span>

清除逻辑实现在 ItemClick：当本次点击计算出的actualValue与当前Value相等，且AllowClear为 true 时，将Value置为 0；否则写入新值。

6. 自定义字符

Character参数允许把默认的星形图标替换为任意内容，比如字母、数字、图标字体甚至中文，见 Character.razor：

<Rate Character="@Character1" AllowHalf="true" DefaultValue="3" /> <br /> <Rate Character="@Character2" AllowHalf="true" DefaultValue="3" /> <br /> <Rate Character="@Character3" AllowHalf="true" DefaultValue="3" /> @code { RenderFragment<RateItemRenderContext> Character1 = (builder) => @<Template> <Icon Type="@IconType.Fill.Heart" /> </Template>; RenderFragment<RateItemRenderContext> Character2 = (builder) => @<Template> A </Template>; RenderFragment<RateItemRenderContext> Character3 = (builder) => @<Template> 好 </Template>; }

Character的类型是RenderFragment<RateItemRenderContext>，组件会通过CascadingValue将自定义模板下发到每一颗星（见 Rate.razor），并在 RateItem.razor 中优先渲染自定义内容，否则回退到默认的Star填充图标。

源码实现原理

渲染结构：UL 列表 + 每星双半区

Rate 组件的渲染结构在 Rate.razor 中定义：外层是一个ul元素（role="radiogroup"），内部按Count循环渲染RateItem。每个RateItem再渲染为一个li，li内部又分为两个相邻的div：

• ant-rate-star-first：星的左半区（占宽 50%），点击/悬停时表示选中半星；
• ant-rate-star-second：星的右半区，点击/悬停时表示选中整星。

这种"一星两半"的结构是半星能力的基础。样式上，index.less 中ant-rate-star-first默认opacity: 0且绝对定位叠在左半区，只有处于-half状态时才显示为选中色，从而实现左半颗星点亮、右半颗星灰置的半星视觉效果。

点击与悬停的事件链路

以点击为例，完整的事件链路是：

1. 用户在某一半区触发onclick，RateItem.razor.cs 的OnClick将isHalf && AllowHalf的结果通过OnItemClick回调上抛；
2. Rate.razor.cs 的ItemClick根据半区标识计算actualValue（isHalf ? index + 0.5M : index + 1），再依据AllowClear决定清零还是写入新值；
3. 写入Value时触发ValueChanged，并通过级联参数通知每个RateItem更新自身高亮类。

悬停链路的逻辑对称：ItemHoverChange更新_hoverValue与_hasHalf，而MouseLeave在鼠标离开整个组件时把悬停状态还原为当前选中值（Rate.razor.cs）。

键盘交互与无障碍

ul上绑定了onkeydown（并preventDefault）。KeyDown 实现了键盘操作：

• 按ArrowRight：值加 1（AllowHalf开启时加 0.5），上限为Count；
• 按ArrowLeft：值减 1（AllowHalf开启时减 0.5），下限为 0。

在无障碍方面，组件外层ul带有role="radiogroup"与tabindex="0"，每颗星渲染为role="radio"并携带aria-checked、aria-posinset、aria-setsize等属性（见 RateItem.razor）；聚焦相关样式在 index.less 中以虚线描边呈现。

样式变量与主题定制

Rate 的默认外观由 Less 主题变量控制，定义在 default.less：

@rate-star-color: @yellow-6; // 星形选中色（黄色系） @rate-star-bg: @border-color-split; // 未选中底色 @rate-star-size: 20px; // 星形尺寸 @rate-star-hover-scale: scale(1.1); // 悬停放大比例

不同内置主题对变量做了差异化覆盖：

• 紧凑主题（compact）：compact.less 将@rate-star-size调整为 16px；
• 暗色主题（dark）：dark.less 将未选中底色改为fade(@white, 12%)。

此外，组件支持 RTL 布局：当全局ConfigProvider的方向设置为 RTL 时，SetClass()会追加ant-rate-rtl类（判断逻辑来自基类 AntDomComponentBase.cs），rtl.less 会翻转星间距与半星半区的位置。

总结

Rate 是 Ant Design Blazor 中一个实现精巧的评分组件：通过"一星两半"的渲染结构低成本地支持了半星评分，通过ul/li语义化结构与键盘事件保证了无障碍体验，并通过AllowClear、Disabled、Tooltips、Character、Value双向绑定等参数覆盖了从只读展示到可交互评级的全部常见业务场景。掌握其 API 与源码实现，你就能在表单、商品详情、满意度调查等页面中灵活搭建评分功能，并根据需要定制字符、提示与主题样式。

• UI组件
• 前端