daisyUI Rating 组件完全指南:用原生 Radio 打造可交互、可读、支持半星的评分控件
daisyUI Rating 组件完全指南:用原生 Radio 打造可交互、可读、支持半星的评分控件
本文基于 daisyUI 仓库中的 Rating 组件文档(组件文档/components/rating/+page.md)、skills 版速查)并结合其核心实现源码展开。Rating 是 daisyUI 提供的一组以原生
<input type="radio">为基础构建的评分控件,无需任何 JavaScript 即可实现点击选星、键盘操作、只读展示、清除评分、半星评分等完整交互。读完本文你将掌握 Rating 的全部类名体系、六种常见使用形态,以及底层 CSS 变量与 Mask 遮罩的工作机理,可以直接套用到你的表单与评价界面中。
Rating 是什么
在 daisyUI 中,Rating 被定义为一组"允许用户为某事物打分的单选按钮"。它的实现非常克制——核心就是一个加了 .rating 类的容器,里面摆放若干个带遮罩形状(mask)的单选按钮。选中态完全交给原生 radio 的行为驱动,因此天然支持键盘方向键切换、表单提交取值,不需要额外引入脚本。
从该组件的元信息(+page.md 的 frontmatter)可以提取出完整的类名体系:
| 类型 | 类名 | 说明 |
|---|---|---|
| 组件类 | rating |
包裹一组 radio 输入的容器 |
| 修饰类 | rating-half |
让每个形状只显示一半,用于半星评分 |
| 修饰类 | rating-hidden |
放在最前面的隐藏 radio,让用户能清除评分 |
| 尺寸类 | rating-xs |
超小尺寸 |
| 尺寸类 | rating-sm |
小尺寸 |
| 尺寸类 | rating-md |
中等尺寸(默认) |
| 尺寸类 | rating-lg |
大尺寸 |
| 尺寸类 | rating-xl |
超大尺寸 |
值得注意:rating 只是"排列"逻辑,形状本身来自 daisyUI 的另一套基础能力
mask(遮罩类)。文档示例中几乎每个星都用到了mask、mask-star、mask-star-2、mask-heart等类,它们的 SVG 剪影定义在 mask.css 中。因此阅读本文时建议同时参考 Mask 组件文档。
关于文档源码中的 $$ 前缀
如果你打开仓库里的原始组件文档,会发现示例代码写的是 class="$$rating"、class="$$mask $$mask-star"。这是 daisyUI 文档站生成的约定:$$ 是"类名前缀占位符",渲染示例时会被替换为当前用户配置的 daisyui 前缀(默认无前缀)。仓库中 missingClassnamePrefix.test.js 专门校验所有代码块内的组件类名都带上了 $$,确保示例代码在任何前缀配置下都正确。为了行文清晰,下文示例一律按默认(无前缀)写法展示。
基础交互式评分
最基本也最常见的用法,是给一组 radio 套上 .rating,让每颗星对应一个分值:
<div class="rating">
<input type="radio" name="rating-1" class="mask mask-star" aria-label="1 star" />
<input type="radio" name="rating-1" class="mask mask-star" aria-label="2 star" checked="checked" />
<input type="radio" name="rating-1" class="mask mask-star" aria-label="3 star" />
<input type="radio" name="rating-1" class="mask mask-star" aria-label="4 star" />
<input type="radio" name="rating-1" class="mask mask-star" aria-label="5 star" />
</div>
要点拆解:
name必须唯一:文档在显著位置给出提示——同一页面上的多个评分组应使用彼此不同的name,否则 radio 之间会互相干扰(选中一组会取消另一组)。这也是原生 radio 的天然约束,示例中rating-1、rating-2……依次递增就是遵守该约定的体现。- 默认选中值:通过给某一项加
checked="checked"设置初始评分(示例中默认 2 星)。 aria-label:每颗星都声明了 "1 star"~"5 star" 的可访问名称,方便读屏软件逐颗播报,请勿省略。mask mask-star的组合语义:mask提供通用的遮罩行为(按 SVG 形状裁切、居中、不重复),mask-star提供"四角星"轮廓(见下文形状一节)。radio 本身的原生圆点被.rating input的appearance-none抹掉,因此用户看到的就是形状裁切出的星。
只读评分
当不需要用户交互、只想展示一个已有评分(如商品评价快照、平均值)时,把 radio 换成普通的 <div> 即可。此时没有表单语义,选中高亮用 aria-current="true"(或 aria-checked="true")来标记当前值:
<div class="rating">
<div class="mask mask-star" aria-label="1 star"></div>
<div class="mask mask-star" aria-label="2 star"></div>
<div class="mask mask-star" aria-label="3 star" aria-current="true"></div>
<div class="mask mask-star" aria-label="4 star"></div>
<div class="mask mask-star" aria-label="5 star"></div>
</div>
从 rating.css 的选择器可以看出,控件内部对以下四种状态一视同仁地加亮(opacity: 100%):
:checked[aria-checked="true"][aria-current="true"]:has(~ :checked / [aria-checked="true"] / [aria-current="true"])——即"位于被选中元素之前的所有兄弟元素"
第 4 条是"逐颗点亮"的关键:当第 3 颗星被选中时,它前面的 1、2 号兄弟星也都会被点亮,这正是从低到高连续填充的视觉效果来源,且完全不依赖 JS。只读态复用同一套 :has() 规则,aria-current 前导星同样会亮起。
换颜色与换形状:Mask 与背景色的组合
Rating 中每一颗星默认显示的是 base-content(当前主题的前景色)且透明度只有 20%,这构成了"未选中为淡灰色"的外观。要给星上色,只需叠加任意 Tailwind 背景色工具类(如 bg-orange-400、bg-green-500),颜色会被裁切后的星形完整呈现。
经典示例:橙色警告星(mask-star-2)
mask-star-2 是另一种五角星轮廓(SVG 路径与 mask-star 不同),配合 bg-orange-400 是文档中最常用的暖色组合:
<div class="rating">
<input type="radio" name="rating-2" class="mask mask-star-2 bg-orange-400" aria-label="1 star" />
<input type="radio" name="rating-2" class="mask mask-star-2 bg-orange-400" aria-label="2 star" checked="checked" />
<input type="radio" name="rating-2" class="mask mask-star-2 bg-orange-400" aria-label="3 star" />
<input type="radio" name="rating-2" class="mask mask-star-2 bg-orange-400" aria-label="4 star" />
<input type="radio" name="rating-2" class="mask mask-star-2 bg-orange-400" aria-label="5 star" />
</div>
五彩爱心(mask-heart)
mask-heart 使用心形剪影。你可以给每一档配置不同颜色,营造"满意度从低到高渐变"的表达,此时只需在容器上追加一个水平间距工具类(如 gap-1)即可避免心形贴得太紧:
<div class="rating gap-1">
<input type="radio" name="rating-3" class="mask mask-heart bg-red-400" aria-label="1 star" />
<input type="radio" name="rating-3" class="mask mask-heart bg-orange-400" aria-label="2 star" checked="checked" />
<input type="radio" name="rating-3" class="mask mask-heart bg-yellow-400" aria-label="3 star" />
<input type="radio" name="rating-3" class="mask mask-heart bg-lime-400" aria-label="4 star" />
<input type="radio" name="rating-3" class="mask mask-heart bg-green-400" aria-label="5 star" />
</div>
纯绿评价(bg-green-500)
对"满意/推荐"这类语义,文档还给出了统一绿色的形态,把 bg-green-500 与 mask mask-star-2 组合即可:
<div class="rating">
<input type="radio" name="rating-4" class="bg-green-500 mask mask-star-2" aria-label="1 star" />
<input type="radio" name="rating-4" class="bg-green-500 mask mask-star-2" aria-label="2 star" checked="checked" />
<input type="radio" name="rating-4" class="bg-green-500 mask mask-star-2" aria-label="3 star" />
<input type="radio" name="rating-4" class="bg-green-500 mask mask-star-2" aria-label="4 star" />
<input type="radio" name="rating-4" class="bg-green-500 mask mask-star-2" aria-label="5 star" />
</div>
需要提醒的是:颜色类名的书写顺序不影响结果(上例故意写成 bg-green-500 mask mask-star-2),mask 只负责裁切、bg-* 只负责填充,二者正交。
尺寸控制与底层 CSS 变量
Rating 提供 5 档尺寸修饰类:rating-xs / rating-sm / rating-md / rating-lg / rating-xl,其中 rating-md 是默认值(不写尺寸类也等同 md)。
<!-- xs -->
<div class="rating rating-xs">
<input type="radio" name="rating-5" class="mask mask-star-2 bg-orange-400" aria-label="1 star" />
<input type="radio" name="rating-5" class="mask mask-star-2 bg-orange-400" aria-label="2 star" checked="checked" />
<!-- ...3~5 星略,类名与上文一致 -->
</div>
<!-- sm -->
<div class="rating rating-sm"><!-- 同结构,name="rating-6" --></div>
<!-- md -->
<div class="rating rating-md"><!-- 同结构,name="rating-7" --></div>
<!-- lg -->
<div class="rating rating-lg"><!-- 同结构,name="rating-8" --></div>
<!-- xl -->
<div class="rating rating-xl"><!-- 同结构,name="rating-9" --></div>
为节省篇幅上述省略号只是示意,实际使用时每个 input 均需补全 5 颗星及各自的
aria-label,并保持组内name一致、组间唯一。
尺寸在源码中如何实现
打开 rating.css,可以看到每个尺寸类本质是改写了一个 CSS 变量 --size:
| 尺寸类 | --size 计算式 |
换算值(按默认 0.25rem 基准) |
|---|---|---|
rating-xs |
var(--size-selector, 0.25rem) * 4 |
1rem(16px) |
rating-sm |
var(--size-selector, 0.25rem) * 5 |
1.25rem(20px) |
rating-md |
var(--size-selector, 0.25rem) * 6 |
1.5rem(24px,默认) |
rating-lg |
var(--size-selector, 0.25rem) * 7 |
1.75rem(28px) |
rating-xl |
var(--size-selector, 0.25rem) * 8 |
2rem(32px) |
两个值得留意的实现细节:
- 乘法写在 CSS 里:
--size的取值形如var(--size-selector, 0.25rem) * 6。在 daisyUI 的样式管线中会经过数学计算预处理(calc),最终得到以 rem 为单位的边长。子元素默认宽calc(var(--size) * 1)、高var(--size),因此改--size即等比缩放整组星。 - 全局统一的尺寸基准:
--size-selector是 daisyUI 跨组件共享的"控件尺寸选择器变量"(缺省回退0.25rem),在 checkbox.css、badge.css 等控件中同样承担尺寸锚点的角色。这意味着通过全局定义--size-selector可以成体系地缩放这些交互控件,而 rating 会自然跟随。
允许清除评分:rating-hidden
radio 一旦被选中就无法直接取消,这是个常见痛点。daisyUI 的解法是在组的最前面放置一个"看不见的 radio"——给第一个 input 加上 rating-hidden,点击它即相当于清空评分:
<div class="rating rating-lg">
<input type="radio" name="rating-10" class="rating-hidden" aria-label="clear" />
<input type="radio" name="rating-10" class="mask mask-star-2" aria-label="1 star" />
<input type="radio" name="rating-10" class="mask mask-star-2" aria-label="2 star" checked="checked" />
<input type="radio" name="rating-10" class="mask mask-star-2" aria-label="3 star" />
<input type="radio" name="rating-10" class="mask mask-star-2" aria-label="4 star" />
<input type="radio" name="rating-10" class="mask mask-star-2" aria-label="5 star" />
</div>
它的样式定义在 rating.css:宽度收缩为 w-2、背景设为 bg-transparent。因为它仍是组内第一个 radio,被 :has() 规则"前导点亮"的列表里没有可亮对象,视觉上完全透明、只承担"可点击清空"的职责。注意它不应再叠加 mask,否则会被裁切出图形。
半星评分:rating-half + mask-half-1/2
评分场景常有"4.5 星"这类精确到半步的需求。半星由两层组成:外层用 rating-half 把每个图形宽度减半(rating.css 将子元素宽改为 --size * 0.5),内层再用 mask-half-1 / mask-half-2 让遮罩只显示星形的左半或右半。
布局规律是:"0.5 星""1.5 星"……使用 mask-half-1(显示左半),"1 星""2 星"……使用 mask-half-2(显示右半),两者成对铺满同一颗星的左右两半:
<div class="rating rating-lg rating-half">
<input type="radio" name="rating-11" class="rating-hidden" aria-label="clear" />
<input type="radio" name="rating-11" class="bg-green-500 mask mask-star-2 mask-half-1" aria-label="0.5 star" />
<input type="radio" name="rating-11" class="bg-green-500 mask mask-star-2 mask-half-2" aria-label="1 star" />
<input type="radio" name="rating-11" class="bg-green-500 mask mask-star-2 mask-half-1" aria-label="1.5 star" checked="checked" />
<input type="radio" name="rating-11" class="bg-green-500 mask mask-star-2 mask-half-2" aria-label="2 star" />
<!-- 依此类推:2.5/3/3.5/4/4.5/5 star,每档一半为 half-1、一半为 half-2 -->
</div>
mask-half-* 的实现位于 mask.css:将 mask-size 放大到 200% 并让 mask-position 钉在 left(half-1)或 right(half-2),配合外层把盒宽减半,正好露出星形左/右各一半。最贴心的是它还内置了 RTL 处理:rtl:[mask-position:right] 与 rtl:[mask-position:left],在从右向左书写的语言环境下左右半边会自动对调,无需为阿拉伯语、希伯来语等界面另写样式。
形状与颜色背后的原理(源码纵深)
Mask 遮罩形状从哪来
Rating 示例中用到的所有图形都定义在 mask.css 中,方式是把内联 SVG 的 data:image/svg+xml URL 赋给 mask-image:
通用基类 .mask 负责设定 mask-size: contain、mask-repeat: no-repeat、mask-position: center,确保图形完整且居中;实际填充颜色则来自元素自身背景。于是"选中点亮"的实现可以完全脱离图片与字体图标:选中前透明度 20% 露出淡淡的 base-content,选中后透明度 100% 露出你叠加的 bg-* 颜色,两层都是纯 CSS。
选中、聚焦与动效细节
rating.css 还定义了若干容易被忽略的体验细节:
- 键盘可达:
input设置cursor: pointer与appearance: none,原生 radio 的 Tab/方向键行为全部保留;rating-hidden那个"清除项"同样在 Tab 序列中,方便键盘用户清空评分。 - 聚焦反馈:
:focus-visible时图形scale: 1.1,让键盘聚焦位置一目了然;:active:focus(鼠标按住的同时)取消入场动画并同样放大,点击反馈跟手。 - 入场动画:每个图形在状态变化时播放约 0.25s 的
rating关键帧(rating.css 只写了0%/40%两帧:轻微放大并提高亮度/对比度),营造"点亮"的弹性感。动画均被prefers-reduced-motion: no-preference守卫,尊重系统"减少动态效果"的无障碍设置。
无障碍与最佳实践清单
综合官方组件文档、skills 版文档与源码约束,落地时建议遵守以下规则:
- 为每个 radio/div 提供有意义的
aria-label(如 "1 star"),没有图标的纯形状对读屏用户等于隐形。 - 只读场景改用
<div>,并用aria-current="true"(或aria-checked="true")标记当前档位,不要塞入禁用的 radio,以免误导表单语义。 - 同一页面的不同评分组使用互不相同的
name,这是官方在文档顶部反复强调的硬性约定。 - 如需清除评分,使用
rating-hidden作为组内第一个 input,并给它aria-label="clear"。 - 半星需要成对出现:
rating-half配合mask-half-1(左半)与mask-half-2(右半)按顺序交替书写,并记得用rating-hidden提供清零入口(官方示例默认如此)。 - 尺寸优先级:
rating-md为默认中等尺寸,不写也可;需要覆盖时选择xs/sm/lg/xl之一即可,不要叠加多个尺寸类。
小结与进一步阅读
Rating 是"原生语义 + 纯 CSS 外观"的典型范本:.rating 提供状态管理所需的 radio 行为与选中加亮(:checked + :has(~…))规则,mask 体系负责把所有形状问题收敛为 SVG 遮罩,Tailwind 背景色工具类则让"配色自由"成为零成本操作——用户既不需要画图,也不需要一行脚本。
若想继续深入,可以在当前仓库中对照以下资源:
- 交互示例与完整尺寸/半星代码:Rating 组件页面文档/components/rating/+page.md)
- 组件核心样式(状态、尺寸变量、动画):rating.css
- 星形/心形遮罩与半星裁切定义:mask.css
- 面向 Agent 的精简语法与规则速查:skills/rating.md