X-Next

Appearance

Rate 评分 ​

用于评分、打星或展示满意度等级，适合评价表单、质量反馈和评分结果展示。

何时使用 ​

  • 需要用户快速给出等级评价时。
  • 需要在详情、列表或卡片中展示评分结果时。
  • 评分项数量较少，并且每个等级含义容易理解时。

基础用法 ​

当前评分：3
vue
<template>
  <x-rate v-model="value" />
</template>

<script setup lang="ts">
import { ref } from 'vue';

const value = ref(3);
</script>

半星评分 ​

当前评分：2.5
vue
<template>
  <x-rate v-model="value" allow-half />
</template>

<script setup lang="ts">
import { ref } from 'vue';

const value = ref(2.5);
</script>

可清除 ​

再次点击当前评分可清除：4
vue
<template>
  <x-rate v-model="value" allow-clear />
</template>

<script setup lang="ts">
import { ref } from 'vue';

const value = ref(4);
</script>

只读和禁用 ​

vue
<template>
  <x-rate v-model="readonlyValue" allow-half readonly />
  <x-rate v-model="disabledValue" disabled />
</template>

<script setup lang="ts">
import { ref } from 'vue';

const readonlyValue = ref(3.5);
const disabledValue = ref(2);
</script>

自定义数量 ​

当前评分：6 / 8
vue
<template>
  <x-rate v-model="value" :count="8" />
</template>

<script setup lang="ts">
import { ref } from 'vue';

const value = ref(6);
</script>

自定义字符 ​

当前评分：3
vue
<template>
  <x-rate v-model="value">
    <template #character="{ index }">
      <span>{{ index + 1 }}</span>
    </template>
  </x-rate>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const value = ref(3);
</script>

自定义颜色和笑脸分级 ​

vue
<template>
  <x-rate v-model="value" :color="scoreColors" />
  <x-rate v-model="value" grading />
</template>

<script setup lang="ts">
import { ref } from 'vue';

const value = ref(4);
const scoreColors = {
  2: '#f53f3f',
  4: '#ff7d00',
  5: '#00b42a',
};
</script>

提示文本 ​

还行
vue
<template>
  <x-rate v-model="value" :tooltips="tooltipTexts" />
  <p>{{ tooltipTexts[value - 1] }}</p>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const value = ref(3);
const tooltipTexts = ['很差', '一般', '还行', '不错', '很好'];
</script>

事件 ​

等待操作，hover：-
vue
<template>
  <x-rate
    v-model="value"
    allow-half
    allow-clear
    @change="(nextValue) => log = `change: ${nextValue}`"
    @hover-change="(nextValue) => hoverValue = nextValue"
  />
  <p>{{ log }}，hover：{{ hoverValue ?? '-' }}</p>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const value = ref(2);
const hoverValue = ref<number | undefined>();
const log = ref('等待操作');
</script>

表单组合 ​

点击校验查看结果

vue
<template>
  <x-form ref="formRef" :model="formModel" layout="vertical">
    <x-form-item label="服务评分" field="score" :rules="[{ type: 'number', min: 1, message: '请选择至少 1 分' }]">
      <x-rate v-model="formModel.score" allow-half allow-clear aria-label="服务评分" />
    </x-form-item>
    <x-form-item>
      <x-space>
        <x-button type="primary" @click="handleFormValidate">校验</x-button>
        <x-button @click="handleFormReset">重置</x-button>
      </x-space>
    </x-form-item>
  </x-form>
  <p role="status">{{ formResult }}</p>
</template>

<script setup lang="ts">
import { reactive, ref } from 'vue';
import type { FormInstance, FieldRule } from 'x-next';
const formRef = ref<FormInstance>();
const formModel = reactive({ score: 0 });
const formResult = ref('点击校验查看结果');
const handleFormValidate = async () => {
  const errors = await formRef.value!.validate();
  formResult.value = errors
    ? `校验失败：${Object.values(errors).map((error) => error.message).join('；')}`
    : '校验通过';
};
const handleFormReset = () => {
  formRef.value!.resetFields();
  formResult.value = '已重置';
};
</script>

按需导入 ​

ts
import { Rate } from 'x-next';

样式按需引入（base.css 为共享基础层，多个组件只需引入一次）：

ts
import 'x-next/style/base.css';
import 'x-next/style/rate.css';

Props ​

参数说明类型默认值
modelValue绑定值numberundefined
defaultValue默认值，非受控模式number0
count评分总数，grading 开启时固定为 5number5
allowHalf是否允许半选booleanfalse
allowClear是否允许再次点击清除booleanfalse
grading是否开启笑脸分级booleanfalse
readonly是否只读booleanfalse
disabled是否禁用booleanfalse
autofocus是否自动获取焦点booleanfalse
tabindex根节点 tabindexstring | number0
tooltips每项提示文本string[]undefined
color评分颜色，支持统一颜色或分段阈值颜色string | Record<number, string>undefined

Events ​

事件名说明参数
update:modelValue绑定值更新时触发value: number
change评分改变时触发value: number
hover-change鼠标移入评分项或移出组件时触发value: number | undefined
focus组件获得焦点时触发ev: FocusEvent
blur组件失去焦点时触发ev: FocusEvent
keydown键盘按下时触发ev: KeyboardEvent

Slots ​

插槽名说明参数
character自定义评分符号{ index, value, count, disabled }

Methods ​

方法名说明
focus()让评分组件获得焦点
blur()移除评分组件焦点

键盘交互 ​

allowClear 只影响重复点击同一评分；方向键、Home、End 和数字键始终定位到目标分值，在边界重复操作不会切换为 0。

按键行为
ArrowRight / ArrowUp增加评分
ArrowLeft / ArrowDown减少评分
Home清零
End选择最大评分
0-9在评分总数范围内快速设置对应分值