Rate 评分
用一排星星打分或展示分数,例如商品评价、满意度调查。
引入
import { NsRate } from '@ns/ui'
基础用法
用 v-model 绑定一个数字。点第几颗星就是几分,鼠标移到星星上会先预览。
<script setup lang="ts">
import { ref } from 'vue'
import { NsRate } from '@ns/ui'
const value = ref(3)
</script>
<template>
<NsRate v-model="value" />
<p style="margin-top: 12px">当前 {{ value }} 分</p>
</template>
允许半星
加上 allow-half 以后,点一颗星的左半边是半分,右半边是整分。
<script setup lang="ts">
import { ref } from 'vue'
import { NsRate } from '@ns/ui'
const value = ref(2.5)
</script>
<template>
<NsRate v-model="value" allow-half />
<p style="margin-top: 12px">当前 {{ value }} 分</p>
</template>
清空评分
组件没有“再点一次取消”的功能。要清空就把绑定值设回 0,键盘操作时按 Home 键也可以清零。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsRate, NsSpace } from '@ns/ui'
const value = ref(3)
</script>
<template>
<NsSpace wrap>
<NsRate v-model="value" />
<NsButton size="small" @click="value = 0">清空</NsButton>
</NsSpace>
</template>
禁用和只读
disabled 会让整个组件变淡,不能操作也不能用 Tab 键聚焦。readonly 外观不变,只是不能改分,适合用来展示分数;配合 allow-half 可以展示半星。
<script setup lang="ts">
import { NsRate, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">disabled</span>
<NsRate :model-value="3" disabled />
<NsRate :model-value="3.5" disabled allow-half show-text />
</NsSpace>
<NsSpace wrap>
<span class="row-label">readonly</span>
<NsRate :model-value="3" readonly />
<NsRate :model-value="3.5" readonly allow-half show-text />
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 64px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
辅助文字
show-text 在星星右边显示当前分数对应的文字。texts 里第 N 项对应 N 分,不写时是“极差、失望、一般、满意、惊喜”。0 分时不显示文字,鼠标悬停预览时文字跟着变。
<script setup lang="ts">
import { ref } from 'vue'
import { NsRate, NsSpace } from '@ns/ui'
const byDefault = ref(3)
const custom = ref(4)
const texts = ['很差', '较差', '还行', '较好', '很好']
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsRate v-model="byDefault" show-text />
<NsRate v-model="custom" show-text :texts="texts" />
</NsSpace>
</template>
自定义最大值
max 决定一共有几颗星,也就是最高分。
<script setup lang="ts">
import { ref } from 'vue'
import { NsRate, NsSpace } from '@ns/ui'
const three = ref(2)
const ten = ref(7)
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<NsRate v-model="three" :max="3" />
<span>{{ three }} / 3</span>
</NsSpace>
<NsSpace wrap>
<NsRate v-model="ten" :max="10" />
<span>{{ ten }} / 10</span>
</NsSpace>
</NsSpace>
</template>
自定义颜色
colors 可以是数组,也可以是函数。数组里第 N 项是 N 分时的颜色;函数的参数是当前分数(半分向上取整),返回颜色。颜色按当前分数取一次,所有选中的星星用同一个颜色。改改分数看颜色怎么变:
<script setup lang="ts">
import { ref } from 'vue'
import { NsRate, NsSpace } from '@ns/ui'
const byArray = ref(2)
const byFunction = ref(4)
const colorList = ['#99A9BF', '#99A9BF', '#F7BA2A', '#F7BA2A', '#FF9900']
const colorFn = (value: number) => (value <= 2 ? '#F56C6C' : value <= 4 ? '#E6A23C' : '#67C23A')
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">数组</span>
<NsRate v-model="byArray" :colors="colorList" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">函数</span>
<NsRate v-model="byFunction" :colors="colorFn" />
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 40px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
自定义图标
icons 的第一项是图标名,取自 @ns/icons 里的图标。图标名不存在时显示默认的星星。
<script setup lang="ts">
import { ref } from 'vue'
import { NsRate, NsSpace } from '@ns/ui'
const heart = ref(3)
const like = ref(4)
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsRate v-model="heart" :icons="['heart']" :colors="['#F56C6C']" />
<NsRate v-model="like" :icons="['success']" :colors="['#67C23A']" allow-half />
</NsSpace>
</template>
尺寸
size 有 large、default、small 三种,图标分别是 24、18、14 像素,辅助文字是 16、14、12 像素。不写时跟随所在的 NsFormItem、NsForm、NsConfigProvider,都没有时是 default。
<script setup lang="ts">
import { ref } from 'vue'
import { NsRate, NsSpace } from '@ns/ui'
const value = ref(3)
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">large</span>
<NsRate v-model="value" size="large" show-text />
</NsSpace>
<NsSpace wrap>
<span class="row-label">default</span>
<NsRate v-model="value" show-text />
</NsSpace>
<NsSpace wrap>
<span class="row-label">small</span>
<NsRate v-model="value" size="small" show-text />
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 56px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
事件
用户点击或按键改分时触发 change(和 update:modelValue 同时),参数是新的分数;点当前分数那颗星不触发。
<script setup lang="ts">
import { ref } from 'vue'
import { NsMessage, NsRate } from '@ns/ui'
const value = ref(0)
const texts = ['很差', '较差', '还行', '较好', '很好']
const onChange = (score: number) => {
NsMessage.success(`感谢评价:${score} 分`)
}
</script>
<template>
<NsRate v-model="value" show-text :texts="texts" @change="onChange" />
</template>
在表单里使用
放在 NsFormItem 里时,值变化触发 change 规则,评分通过 aria-labelledby 关联表单项的标签。0 分不算空值,required 拦不住没打分,要写 validator 或用 min 规则。不需要校验时设 :validate-event="false"。
校验不通过时表单项下面显示错误信息,星星的颜色不变。点“提交”看看:
<script setup lang="ts">
import { reactive, ref } from 'vue'
import { NsButton, NsForm, NsFormItem, NsRate } from '@ns/ui'
import type { FormRule } from '@ns/ui'
const formRef = ref<InstanceType<typeof NsForm>>()
const model = reactive({ score: 0 })
const rules: Record<string, FormRule[]> = {
score: [{ min: 1, message: '请打分', trigger: 'change' }]
}
const submit = () => {
formRef.value?.validate()
}
</script>
<template>
<NsForm ref="formRef" :model="model" :rules="rules" @submit.prevent>
<NsFormItem label="服务评分" prop="score">
<NsRate v-model="model.score" show-text />
</NsFormItem>
<NsFormItem>
<NsButton type="primary" @click="submit">提交</NsButton>
</NsFormItem>
</NsForm>
</template>
键盘操作
用 Tab 键聚焦后:
| 按键 | 作用 |
|---|---|
→ ↑ | 加 1 分(开了 allow-half 时加半分) |
← ↓ | 减 1 分(开了 allow-half 时减半分) |
Home | 清零 |
End | 打满分 |
分数已经到了 0 或 max 时继续按不会触发事件。
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| modelValue | number | 0 | 绑定值,支持 v-model |
| max | number | 5 | 最大分值,也就是星星的数量 |
| disabled | boolean | false | 是否禁用 |
| readonly | boolean | false | 是否只读:正常显示,但不能改分 |
| allowHalf | boolean | false | 是否允许半星 |
| showText | boolean | false | 是否显示辅助文字 |
| texts | string[] | ['极差', '失望', '一般', '满意', '惊喜'] | 辅助文字,第 N 项对应 N 分。分数比数组长时用最后一项 |
| colors | string[] | ((value: number) => string) | 5 个 '#F7BA2A' | 选中的星星的颜色。数组时第 N 项对应 N 分,分数比数组长时用最后一项;函数时参数是当前分数 |
| icons | string[] | ['star', 'star'] | 图标名,只用第一项 |
| size | 'large' | 'default' | 'small' | - | 尺寸:星星 24 / 18 / 14px,辅助文字 16 / 14 / 12px。不写时跟随 FormItem、Form、ConfigProvider,都没有时是 default |
| validateEvent | boolean | true | 值变化时是否触发所在表单项的校验 |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:modelValue | (value: number) | 用户点击或按键改分时触发,v-model 用的就是它 |
| change | (value: number) | 用户点击或按键改分时触发,参数是新的分数 |
类型
import type { RateProps, RateSize } from '@ns/ui'
/** 评分的尺寸 */
type RateSize = 'large' | 'default' | 'small'
interface RateProps {
modelValue?: number
max?: number
disabled?: boolean
readonly?: boolean
allowHalf?: boolean
showText?: boolean
texts?: string[]
colors?: string[] | ((value: number) => string)
icons?: string[]
size?: RateSize
/** 值变化时是否触发所在表单项的校验,默认 true */
validateEvent?: boolean
}
另外还导出了 RateEmits。
注意事项
- 组件是受控的,不保存自己的分数。只写
:model-value不处理update:modelValue时,点击后显示不会变。 - 点击和键盘操作都只在分数有变化时触发
update:modelValue和change,点当前分数那颗星不触发。 - 辅助文字和颜色都是按分数向上取整以后取的:2.5 分用的是第 3 项。
- 没开
allow-half时,带小数的绑定值按向下取整显示(3.7 显示 3 颗星);开了以后按半星向下取(3.7 显示 3 颗半)。 icons虽然是数组,现在只用第一项,选中和未选中的星星是同一个图标,靠颜色区分。- 只读的评分仍然能用 Tab 键聚焦,但按键不起作用。
- 组件没有插槽,也没有暴露方法。
优化点
[ ] 支持自定义图标组件(现在只能用
@ns/icons里的图标名)[ ] 支持清除功能(再点一次当前分数清零,如
clearable)[ ] 支持动画效果
[ ] 选中和未选中用不同的图标(
icons的第二项现在没有用到)[ ] 展示用途下支持显示分数文字(如
show-score)