ant-design-blazor Rate 评分组件基础用法与源码实现解析

原创2026-10-11 12:52:391,836 阅读
文章标签:前端UI组件设计系统WebAssembly

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 后的自然形态:

  1. 受控值用 Value / ValueChanged 而非 OnChange:官方文档中的 onChange 对应到 Blazor 组件就是 EventCallback<decimal> ValueChanged,配合 @bind-Value 即可实现双向绑定;
  2. 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 的源码中找到确切依据。

登录后查看全文
ant-design-blazor