Ant Design Blazor Rate 评分组件文案展现(Show Copywriting)实战指南

原创2026-10-11 09:53:082,314 阅读
文章标签:前端UI组件设计系统WebAssembly

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;
}

这段代码由两部分组成:

  1. 评分组件:<Rate @bind-Value="value" Tooltips="@desc" />。Tooltips 传入 5 个文案,使鼠标悬停到每一颗星时显示对应的提示文字;
  2. 静态文案:一个 <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 的完整更新链路:

  1. 点击星星:在 Rate.razor.cs 的 ItemClick(int index, bool isHalf) 中计算实际分值(整星为 index + 1,半星为 index + 0.5M),并写入 Value 属性;
  2. 值写入与事件触发:Value 的 setter(Rate.razor.cs)在值变化时更新内部状态并触发 ValueChanged.InvokeAsync(value),这正是 @bind-Value 双向绑定的底层机制;
  3. 页面重渲染:绑定到 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 的数组取值表达式 展示当前选中或回填的评分语义

七、参考资料

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