ant-design-blazor Rate 评分组件基础用法与源码实现解析
ant-design-blazor Rate 评分组件基础用法与源码实现解析
Rate(评分)是 ant-design-blazor 数据录入类组件中用于评价展示与快速评级操作的核心组件,在电商、内容社区、问卷等场景中承担着用户反馈收集的功能。本文以官方 demo「基本 / Basic」为切入点,完整讲解 <Rate /> 最简用法背后的参数体系、交互行为与底层实现原理,读完即可独立完成评分组件的接入、受控绑定与自定义定制。
从最简单的用法开始
在 ant-design-blazor 官方文档中,「基本」示例(对应文档 basic.md)的说明只有一句话:最简单的用法。其配套的演示代码更是极简:
<Rate />
组件目录位于 components/rate/,完整的演示文件见 Basic.razor。这行代码渲染出的就是一个默认配置的评分组件:5 颗星、无半选、允许再次点击清除、选中值可通过 Value 双向绑定获取。它是所有 Rate 进阶用法的地基,下面所有参数、事件与源码逻辑都围绕这行代码展开。
组件定位:何时该用 Rate
在 组件说明文档 中,Rate 被归类为「数据录入(Data Entry)」类型组件,官方明确了两类适用场景:
- 对评价进行展示:例如商品星级、服务满意度等静态评分结果展示(可配合
Disabled使用); - 对事物进行快速的评级操作:例如问卷打分、点评提交等需要用户交互采集评分的场景。
与之对应,组件在 Rate.razor.cs 中标注了 [Documentation(DocumentationCategory.Components, DocumentationType.DataEntry, ...)],即它在框架内被注册为数据录入类文档组件,说明其设计定位与文档分类一致。
完整参数表:官方 API 与 Blazor 实现对应
「基本」用法虽只写了一个标签,但 Rate 组件实际暴露了完整的参数体系。下表整理自官方 API 文档,并与 Rate.razor.cs 源码中的 [Parameter] 一一对应:
| 属性 | 说明 | 类型 | 默认值 | 源码位置 |
|---|---|---|---|---|
| AllowClear | 是否允许再次点击后清除 | bool | true | Rate.razor.cs#L31-L33 |
| AllowHalf | 是否允许半选 | bool | false | Rate.razor.cs#L38-L40 |
| AutoFocus | 自动获取焦点 | bool | false(源码默认 true,见下文说明) | Rate.razor.cs#L52-L54 |
| Character | 自定义字符 | RenderFragment<RateItemRenderContext> | 默认 StarFilled 图标 |
Rate.razor.cs#L59-L60 |
| ClassName | 自定义样式类名 | string | 空 | 继承自 AntDomComponentBase |
| Count | star 总数 | int | 5 | Rate.razor.cs#L66-L67 |
| DefaultValue | 默认值 | decimal | 0 | Rate.razor.cs#L98-L99 |
| Disabled | 只读,无法进行交互 | bool | false | Rate.razor.cs#L46-L47 |
| Style | 自定义样式对象 | string | 空 | 继承自 AntDomComponentBase |
| Tooltips | 自定义每项的提示信息 | string] | null | [Rate.razor.cs#L104-L105 |
| Value | 当前值(受控值) | decimal | 0 | Rate.razor.cs#L72-L87 |
| ValueChanged | 选择时的回调 | EventCallback<decimal> | — | Rate.razor.cs#L92-L93 |
| OnBlur | 失去焦点时的回调 | EventCallback<FocusEventArgs> | — | Rate.razor.cs#L110-L111 |
| OnFocus | 获取焦点时的回调 | EventCallback<FocusEventArgs> | — | Rate.razor.cs#L116-L117 |
注意:官方 API 文档将
AutoFocus默认值标为false,而源码 Rate.razor.cs#L53-L54 中AutoFocus { get; set; } = true。官方文档同时给出blur()与focus()两个方法(见 API 文档方法表),实际使用中应以当前仓库源码行为为准。
需要特别说明两点 Blazor 语境下的差异,这是把 React 版 Ant Design API 迁移到 Blazor 后的自然形态:
- 受控值用
Value/ValueChanged而非OnChange:官方文档中的onChange对应到 Blazor 组件就是EventCallback<decimal> ValueChanged,配合@bind-Value即可实现双向绑定; ClassName/Style直接继承自基类:Rate继承自AntDomComponentBase(见 Rate.razor.cs#L26),与框架内其他组件一致,通过ClassMapper与Style参数对外暴露样式定制能力。
源码级解析:一次点击背后的完整调用链
<Rate /> 能完成「点击选星、再点清除、悬停预览、键盘加减」这些交互,依靠的是 Rate.razor 与 RateItem.razor 两层的配合。
根组件:状态中枢
Rate.razor 渲染一个 <ul role="radiogroup"> 作为容器,遍历由 Count 生成的 RateMetaDatas(每颗星一个元数据,包含序号与 tooltip 文案),通过 CascadingValue 把用户自定义的 Character 模板传递给每个 RateItem。容器自身挂载了四类事件:
@onblur/@onfocus:维护_isFocused状态并触发OnBlur/OnFocus回调(Rate.razor.cs#L150-L160);@onkeydown(带preventDefault):支持键盘操作——ArrowRight加星、ArrowLeft减星,步长随AllowHalf在0.5M与1M之间切换(Rate.razor.cs#L162-L179);@onmouseout:鼠标离开时把悬停值同步回当前值(Rate.razor.cs#L181-L185)。
组件内部维护三个核心私有状态(Rate.razor.cs#L119-L148):
_currentValue:当前选中的星数,decimal类型以支持半星;_hasHalf:当前是否处于半星状态,判断依据是!(Value == (int)Value);_hoverValue:鼠标悬停时从最左到光标位置的星数。
点击逻辑:选中与清除
每颗星在 RateItem.razor 中被拆成左右两个半区:ant-rate-star-first 与 ant-rate-star-second,分别绑定 onclick(true) 与 onclick(false) 事件。由于只有 AllowHalf 为 true 时 RateItem 才会把 isHalf 透传给上层(RateItem.razor.cs#L34-L41),所以半星实际由「点击星星左半部分」触发。
上层 ItemClick 的完整决策流程:
if (Disabled) return; // 只读模式直接忽略
actualValue = isHalf ? index + 0.5M : index + 1;
if (Value == actualValue) { // 再次点击同一颗星
if (AllowClear) { Value = 0; } // 允许清除则归零
} else {
Value = actualValue; // 否则选中新值
}
这段逻辑同时解释了「基本」用法中 AllowClear 默认值 true 的交互体验:用户再次点击已选中的星即可清零评分。
悬停与半星渲染
ItemHoverChange(Rate.razor.cs#L187-L194)在悬停时更新 _hoverValue 与 _hasHalf,二者作为参数传入每颗 RateItem,由 UpdateClass 计算每颗星的四类状态 class:
ant-rate-star-full:星值小于等于悬停值(非半星场景)或小于悬停值;ant-rate-star-half/ant-rate-star-active:半星场景下等于悬停值的那颗星;ant-rate-star-zero:悬停值之后的星;ant-rate-star-focused:聚焦且半星命中。
这些 class 与样式文件联动,实现视觉上的填充效果。
初始化与默认值
OnInitialized 与 OnParametersSet(Rate.razor.cs#L219-L237)做了两件事:其一,若 DefaultValue > 0 且外部未通过 Value 赋值(通过 _valueWasSet 标记判断,该标记在 Value 的 setter 中被置为 true),则用 DefaultValue 初始化;其二,按 Count 生成 RateMetaDatas 列表。这就是为什么「基本」demo 中不传任何参数时,页面渲染出 5 颗空星、点击即得分的根本原因。
样式实现:星星如何「亮」起来
视觉层面,Rate 的样式位于 components/rate/style/,通过 index.less 定义核心规则,并被 entry.less 统一引入(同时依赖 tooltip/style/entry.less,因为 Tooltips 参数底层复用 Tooltip 组件)。
半星视觉的关键技巧在 index.less#L53-L81:每颗星被拆成 ant-rate-star-first(绝对定位、宽度 50%、overflow: hidden、默认 opacity: 0)与 ant-rate-star-second 两个半层;当命中 ant-rate-star-half 时两层同时 opacity: 1,且 -half &-first、-full &-second 继承主题色——由此实现「半个星亮、半个星灰」的经典半星效果。hover 时的 @rate-star-hover-scale 缩放与 transition: all 0.3s(index.less#L36-L51)则提供了平滑的反馈动画。
另外 rtl.less 提供 RTL(从右到左)布局支持,Rate 的 SetClass 中也会在 RTL 模式下追加 ant-rate-rtl class(Rate.razor.cs#L239-L247)。
基于「基本」用法的进阶速览
理解了 <Rate /> 的地基后,同一 demo 目录下的其余五个示例(文档均位于 site/AntDesign.Docs/Demos/Components/Rate/demo/)可以快速理解:
| demo | 对应文档 | 核心代码 | 说明 |
|---|---|---|---|
| 半星 Half star | half.md | <Rate AllowHalf="true" DefaultValue="3.5M" /> |
开启 AllowHalf 后支持 0.5 粒度取值 |
| 文案展现 Show copywriting | text.md | Tooltips="@desc" + @bind-Value |
通过 Tooltips 数组为每档评分提供说明文案 |
| 只读 Read only | disabled.md | <Rate Disabled DefaultValue="2" /> |
关闭全部鼠标交互,仅作结果展示 |
| 清除 Clear star | clear.md | AllowClear 置 true / false 对比 |
控制再次点击时是否允许清零 |
| 其他字符 Other Character | character.md | Character 自定义模板 |
用爱心图标、字母 A、汉字「好」等替换默认星形 |
其中「文案展现」demo(Text.razor)展示了 @bind-Value 双向绑定的标准写法,配合 Tooltips 数组即可实现评分等级的语义化展示,是「基本」用法在生产环境中最常见的直接延伸。
小结
<Rate /> 一行代码背后,是「容器组件 + 子星组件 + 样式系统」三层结构的完整协作:容器负责状态中枢与键盘/失焦事件,子星负责左右半区点击与视觉状态计算,样式系统负责半星与 hover 动画的呈现。理解这份调用链,无论是做基础评分接入、受控双向绑定,还是通过 Character 与 Tooltips 做深度定制,都能在 Rate.razor.cs 与 RateItem.razor.cs 的源码中找到确切依据。