StarRating
交互式星级评分组件
简介
MStarRating 是一个功能丰富的星级评分组件。支持整星和半星评分、只读展示、自定义星星数量等多种模式，适用于评价、评级等场景。
基础用法
默认 5 星评分系统：
3/5
<script setup lang="ts">
const rating = ref(3)
</script>
<template>
<MStarRating v-model="rating" />
</template>
自定义星星数量
通过 max 设置星星总数：
7/10
<script setup lang="ts">
const rating = ref(7)
</script>
<template>
<MStarRating v-model="rating" :max="10" />
</template>
只读模式
用于展示评分结果，不可交互：
4.5/5
<script setup lang="ts">
const productRating = ref(4.5)
</script>
<template>
<MStarRating :model-value="productRating" readonly />
</template>
半星评分
通过 allow-half 启用半星评分：
3.5/5
<script setup lang="ts">
const rating = ref(3.5)
</script>
<template>
<MStarRating v-model="rating" allow-half />
</template>
可清除评分
通过 clearable 允许点击已选星星清除评分：
4/5
<script setup lang="ts">
const rating = ref(4)
</script>
<template>
<MStarRating v-model="rating" clearable />
</template>
隐藏评分徽章
通过 show-badge 控制评分数字徽章的显示：
显示徽章
3/5
隐藏徽章
<script setup lang="ts">
const rating = ref(3)
</script>
<template>
<div class="flex flex-col gap-4">
<div>
<div class="text-sm text-gray-500 mb-2">
显示徽章
</div>
<MStarRating v-model="rating" :show-badge="true" />
</div>
<div>
<div class="text-sm text-gray-500 mb-2">
隐藏徽章
</div>
<MStarRating v-model="rating" :show-badge="false" />
</div>
</div>
</template>
不同尺寸
通过 size 调整星星大小：
4/5
4/5
4/5
4/5
<script setup lang="ts">
const rating = ref(4)
</script>
<template>
<div class="flex flex-col gap-4">
<MStarRating v-model="rating" size="xs" />
<MStarRating v-model="rating" size="sm" />
<MStarRating v-model="rating" size="md" />
<MStarRating v-model="rating" size="lg" />
</div>
</template>
自定义颜色
通过 color 设置选中星星的颜色：
4/5
4/5
4/5
<script setup lang="ts">
const rating = ref(4)
</script>
<template>
<div class="flex flex-col gap-4">
<MStarRating v-model="rating" color="error" />
<MStarRating v-model="rating" color="success" />
<MStarRating v-model="rating" color="primary" />
</div>
</template>
自定义图标
通过图标属性使用不同的图标样式：
3/5
<script setup lang="ts">
const rating = ref(3)
</script>
<template>
<MStarRating
v-model="rating"
filled-icon="i-lucide-heart"
empty-icon="i-lucide-heart"
half-icon="i-lucide-heart"
color="error"
/>
</template>
事件监听
通过事件监听评分和悬停状态：
当前评分: 0
悬停星级: -
<script setup lang="ts">
const toast = useToast()
const rating = ref(0)
const hovering = ref<number | null>(null)
function handleChange(value: number) {
toast.add({
title: '评分已更改',
color: 'success',
description: `您选择的评分是 ${value} 星`
})
}
function handleHover(value: number | null) {
hovering.value = value
}
</script>
<template>
<div class="space-y-2">
<MStarRating v-model="rating" @change="handleChange" @hover="handleHover" />
<div class="text-sm text-gray-500">
<div>当前评分: {{ rating }}</div>
<div>悬停星级: {{ hovering ?? '-' }}</div>
</div>
</div>
</template>
键盘导航
组件支持完整的键盘交互，提升无障碍访问性：
- 方向键：
←→↑↓增减评分（支持半星步进） - 快捷键：
Home设置最小评分，End设置最大评分 - 数字键：
0-9直接跳转到对应评分 - 清除键：
Backspace/Delete清除评分（需启用clearable）
组件遵循 WCAG 无障碍规范，包含完整的 ARIA 属性和键盘焦点管理
禁用状态
通过 disabled 禁用交互：
4/5
<script setup lang="ts">
const rating = ref(4)
</script>
<template>
<MStarRating v-model="rating" disabled />
</template>
自定义插槽
通过插槽添加前缀、后缀或自定义徽章：
评分:4/5 分 (128 评价)
<script setup lang="ts">
const rating = ref(4)
</script>
<template>
<MStarRating v-model="rating">
<template #prefix>
<span class="text-sm text-gray-500 mr-2">评分:</span>
</template>
<template #badge="{ label }">
<span class="text-sm text-primary font-semibold ml-2">
{{ label }} 分
</span>
</template>
<template #suffix>
<span class="text-xs text-gray-400 ml-2">(128 评价)</span>
</template>
</MStarRating>
</template>
API
Props
| Prop | Default | Type |
|---|---|---|
modelValue | 0 | number当前评分值 |
max | 5 | number最大星级数 |
disabled | false | boolean 是否禁用 |
readonly | false | boolean 是否只读 |
showBadge | true | boolean 是否显示评分徽章 |
buttonProps | Partial<ButtonProps>自定义星星按钮属性 | |
emptyIcon | 'i-lucide-star' | string未选中星星的图标 |
filledIcon | 'i-lucide-star' | string选中星星的图标 |
halfIcon | 'i-lucide-star-half' | string半星图标 |
color | 'warning' | "error" | "primary" | "secondary" | "success" | "info" | "warning" | "neutral"选中星星的颜色 |
size | 'sm' | "xs" | "sm" | "md" | "lg" | "xl"星星大小 |
allowHalf | false | boolean 是否允许半星 |
clearable | false | boolean 是否允许清除评分 |
Emits
| Event | Type |
|---|---|
change | [value: number] |
update:modelValue | [value: number] |
hover | [value: number | null] |
Slots
| Slot | Type |
|---|---|
prefix | { value: number; max: number; } |
badge | { value: number; max: number; label: string; } |
suffix | { value: number; max: number; } |