Ant Design Blazor Rate 评分组件文案展现(Show Copywriting)实战指南
Ant Design Blazor Rate 评分组件文案展现(Show Copywriting)实战指南
导读
本文聚焦 Ant Design Blazor 组件库中 Rate(评分)组件的"文案展现"用法:在星星评分的基础上,同步展示一段描述当前评分含义的文字,例如 terrible / bad / normal / good / wonderful。你将掌握 Tooltips 参数与 ant-rate-text 样式类的配合方式、文案数组与评分值的映射细节,并从组件源码层面理解工具提示与文案展现的实现原理,可直接复用到投票、满意度调查、内容评价等真实业务场景。
主题来源:text.md 演示文档
本主题对应仓库中的演示文档 text.md,其定义非常简洁:
- 中文说明:给评分组件加上文案展示;
- 英文说明:Add copywriting in rate components。
虽然描述只有一句话,但它指向的完整示例代码位于同目录的 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;
}
这段代码由两部分组成:
- 评分组件:
<Rate @bind-Value="value" Tooltips="@desc" />。Tooltips传入 5 个文案,使鼠标悬停到每一颗星时显示对应的提示文字; - 静态文案:一个
<span class="ant-rate-text">元素,根据当前评分value从数组desc中取出对应的文案并渲染出来。
运行效果:默认展示 3 颗星(value = 3M),页面同时显示文案 good;当用户点击其他星星时,value 随 @bind-Value 双向绑定更新,文案同步切换为对应的描述。
二、Tooltips 参数:悬停提示与文案数据源
2.1 参数定义
在组件源码 Rate.razor.cs 中,Tooltips 被定义为字符串数组:
/// <summary>
/// Tooltip to show for each increment of rating, in order of index of rating 0-n
/// </summary>
[Parameter]
public string[] Tooltips { get; set; }
注释明确指出:按评分档位 0-n 的顺序,为每一档提供提示信息。组件文档 index.zh-CN.md 中对应的 API 描述为"自定义每项的提示信息",类型为 string[]。
2.2 底层如何建立"星级 → 文案"的映射
Tooltips 不是一次性传给渲染树的,而是在初始化阶段被逐一映射到每一颗星。核心逻辑位于 Rate.razor.cs 的 OnInitialized:
RateMetaDatas = Enumerable.Range(1, Count)
.Select(c => new RateMetaData() { SerialNumber = c - 1, ToolTipText = this.Tooltips?[c - 1] });
Count默认值为 5(见 Rate.razor.cs),因此默认生成 5 个RateMetaData;- 每个
RateMetaData的ToolTipText按索引从Tooltips数组取值,即第 1 颗星对应Tooltips[0]; - 若未传
Tooltips,ToolTipText为null,此时不渲染任何提示。
随后在 Rate.razor 的渲染模板中,Tooltip="@item.ToolTipText" 被作为参数传递给每个 RateItem。
2.3 RateItem 内部的 Tooltip 渲染分支
RateItem.razor 根据是否有提示文字决定渲染结构:
@if (string.IsNullOrWhiteSpace(Tooltip))
{
<li class="@_starClassMapper.Class" @ref="Ref">
@template(this)
</li>
}
else
{
<Tooltip Title="@Tooltip">
<Unbound>
<li class="@_starClassMapper.Class" @ref="@context.Current">
@template(this)
</li>
</Unbound>
</Tooltip>
}
即:只要 Tooltips 中对应索引存在非空文案,该星就会被 Tooltip 组件包裹,悬停时弹出气泡提示。这是"文案展现"中悬停交互部分的来源。
三、ant-rate-text:固定文案的展示载体
除悬停提示外,官方示例还在评分组件右侧用 <span class="ant-rate-text"> 展示一行固定的当前文案。该样式类的定义位于样式源码 index.less:
&-text {
display: inline-block;
margin: 0 8px;
font-size: @font-size-base;
}
其关键行为:
display: inline-block:使文案与评分组件处于同一行内流布局;margin: 0 8px:在评分与文案之间保持 8px 的水平间距;font-size: @font-size-base:使用主题默认字号,与组件整体视觉保持一致。
因此你可以在任何需要展示评分对应文案的位置复用它,例如:
<span class="ant-rate-text">@(desc[(int)value-1])</span>
四、源码级原理:点击评分后文案如何联动
文案得以实时联动,依赖于 Rate 组件受控值 Value 的完整更新链路:
- 点击星星:在 Rate.razor.cs 的
ItemClick(int index, bool isHalf)中计算实际分值(整星为index + 1,半星为index + 0.5M),并写入Value属性; - 值写入与事件触发:
Value的 setter(Rate.razor.cs)在值变化时更新内部状态并触发ValueChanged.InvokeAsync(value),这正是@bind-Value双向绑定的底层机制; - 页面重渲染:绑定到
value的@(desc[(int)value-1])表达式随组件重渲染重新求值,文案随即切换。
需要注意的一个边界:示例中 desc<a href="https://link.gitcode.com/i/0cca13f542fc5d22e0757dd3635e99ca" target="_blank">(int)value-1] 的索引从 0 开始,因此当 value 为 0(例如启用 AllowClear 后点击已选中的星将其清零,见 [Rate.razor.cs)时,表达式会因 value - 1 = -1 产生数组越界。生产环境中建议对 value 为 0 的情况做保护,例如:
<span class="ant-rate-text">@(value > 0 ? desc[(int)value - 1] : string.Empty)</span>
五、组合进阶:文案展现与其它参数的搭配
文案展现可以自由地与 Rate 的其他参数组合,形成更丰富的交互形态:
| 参数 | 默认值 | 与文案展现的组合效果 |
|---|---|---|
Count |
5 | 文案数组长度应与 Count 对齐,否则部分星级无提示、desc 索引也可能越界 |
AllowHalf |
false | 开启后评分值可为 x.5,文案展示需考虑取整策略(如四舍五入) |
AllowClear |
true | 再次点击已选星会清零,需处理 value = 0 时的文案兜底 |
Disabled |
false | 只读展示场景下,文案同样随默认值渲染,适合做结果展示 |
Character |
星形图标 | 自定义字符时文案体系依然生效,两者互不冲突 |
例如一个"满意度调查"的只读展示:
<Rate Disabled="true" Value="4M" Tooltips="@desc" />
<span class="ant-rate-text">@(desc[3])</span>
@code {
string[] desc = new string[] { "非常不满意", "不满意", "一般", "满意", "非常满意" };
}
六、两种文案形式的分工小结
| 形式 | 触发方式 | 实现要素 | 适用场景 |
|---|---|---|---|
| 悬停提示(Tooltip) | 鼠标悬停到对应星 | Tooltips 数组参数 + RateItem.razor 的 Tooltip 包装分支 |
引导用户理解每一档评分的含义 |
| 固定文案(text) | 随当前 Value 常驻显示 |
ant-rate-text 样式类 + 基于 value 的数组取值表达式 |
展示当前选中或回填的评分语义 |
七、参考资料
- 演示文档:text.md
- 演示源码:Text.razor
- 组件实现:Rate.razor.cs、Rate.razor
- 子项实现:RateItem.razor、RateItem.razor.cs
- 样式定义:components/rate/style/index.less
- 完整 API 说明:index.zh-CN.md