FxRate 评分

用于评分场景。不依赖任何 UI 框架，图标走 FxIcon，样式走 @fx/styles token。

FxRate 属于 @fx/components。

基础用法

评分将分数划分为几个等级，可用不同背景色区分。默认颜色一致，可通过 colors 传入三元素数组反映三个等级（用 low-threshold 和 high-threshold 定义两个阈值），或传入对象（键为阈值、值为对应颜色）。

<template>
  <div class="demo-rate-block">
    <span class="demonstration">默认</span>
    <FxRate v-model="value1" />
  </div>
  <div class="demo-rate-block">
    <span class="demonstration">不同档位颜色</span>
    <FxRate v-model="value2" :colors="colors" />
  </div>
</template>

<script lang="ts" setup>
import { ref } from "vue"
import { FxRate } from "@fx/components"

const value1 = ref(0)
const value2 = ref(0)
// 等价于 { 2: '#99A9BF', 4: { value: '#F7BA2A', excluded: true }, 5: '#FF9900' }
const colors = ref(["#99A9BF", "#F7BA2A", "#FF9900"])
</script>

<style scoped>
.demo-rate-block {
  padding: 30px 0;
  text-align: center;
  border-right: solid 1px var(--fx-border-color);
  display: inline-block;
  width: 49%;
  box-sizing: border-box;
}
.demo-rate-block:last-child {
  border-right: none;
}
.demo-rate-block .demonstration {
  display: block;
  color: var(--fx-text-color-secondary);
  font-size: 14px;
  margin-bottom: 20px;
}
</style>

尺寸

size 取 'large' | 'default' | 'small'，控制图标与容器高度。

<template>
  <FxRate v-model="value" size="large" />
  <br />
  <FxRate v-model="value" />
  <br />
  <FxRate v-model="value" size="small" />
</template>

<script lang="ts" setup>
import { ref } from "vue"
import { FxRate } from "@fx/components"

const value = ref(0)
</script>

半选

添加 allow-half 属性即可允许选择半颗星。

<template>
  <FxRate v-model="value" allow-half />
</template>

<script lang="ts" setup>
import { ref } from "vue"
import { FxRate } from "@fx/components"

const value = ref()
</script>

自定义步进

step 控制键盘方向键与鼠标 hover/点击的共同步进粒度，0 < step ≤ 1。推荐字符串字面量 '1' / '0.X' / '0.XX'（最多 2 位小数，传 '0.001' 等会在 IDE 报类型错误）；也支持 number（如 :step="0.25"，不做小数位静态检查，越界 / 超精度运行时 console.warn 回落）。未传时按 allow-half 推断（true → 0.5，false → 1）；传了则优先于 allow-half。

适用于十分制（step="0.1"）、四分制（step="0.25"）等精细评分场景：鼠标在一颗星内按 step 量化位置（step="0.25"，第 3 颗左 1/4 处 = 2.25、中点 = 2.5、右 3/4 = 2.75、最右 = 3.0）。

<template>
  <FxRate v-model="value" step="0.01" show-score />
</template>

<script lang="ts" setup>
import { ref } from "vue"
import { FxRate } from "@fx/components"

const value = ref()
</script>

注意：step 不整除 1 时（如 0.3），一颗星内最右最多到 floor(1/0.3)*0.3 = 0.9，无法精确到整颗；若需触达整颗请用整除 1 的值（0.5 / 0.25 / 0.1 等）。step ≤ 0 或 > 1 时开发环境会 console.warn 并回落到 allow-half 推断。

辅助文字

用辅助文字直接地表达对应分数。

为组件设置 show-text 属性会在右侧显示辅助文字。通过设置 texts 可以为每一个分值指定对应的辅助文字。texts 为一个数组，长度应等于最大值 max。show-text 与 show-score 互斥。

<template>
  <FxRate
    v-model="value"
    :texts="['oops', 'disappointed', 'normal', 'good', 'great']"
    show-text
  />
</template>

<script lang="ts" setup>
import { ref } from "vue"
import { FxRate } from "@fx/components"

const value = ref()
</script>

清零

再次点击同值时可重置为 0。

<template>
  <FxRate v-model="value" clearable />
</template>

<script lang="ts" setup>
import { ref } from "vue"
import { FxRate } from "@fx/components"

const value = ref(3)
</script>

更多图标

可以用不同的图标区分不同的评分组件。

通过 icons 传入三元素数组（或对象，键为阈值、值为对应图标）自定义图标，本例同时用 void-icon 设置未选中图标，colors 同步调整填充色。图标可传字符串（FxIcon 图标名，如 'ep:star-filled'）或 SVG 组件。

<template>
  <FxRate
    v-model="value"
    :icons="icons"
    void-icon="ep:chat-round"
    :colors="['#409eff', '#67c23a', '#FF9900']"
  />
</template>

<script lang="ts" setup>
import { ref } from "vue"
import { FxRate, type RateIcon } from "@fx/components"

const value = ref()
// 等价于 { 2: 'ep:chat-round', 4: { value: 'ep:chat-line-round', excluded: true }, 5: 'ep:chat-dot-round' }
const icons: RateIcon[] = [
  "ep:chat-round",
  "ep:chat-line-round",
  "ep:chat-dot-round",
]
</script>

只读

只读评分用于展示评分，支持半星。

用 disabled 让组件只读，加 show-score 在右侧显示分值，score-template 提供分值模板（须含 {value}，会被替换为分值），text-color 控制分值文字色。

<template>
  <FxRate
    v-model="value"
    disabled
    show-score
    text-color="#ff9900"
    score-template="{value} points"
  />
</template>

<script lang="ts" setup>
import { ref } from "vue"
import { FxRate } from "@fx/components"

const value = ref(3.7)
</script>

自定义样式

可以通过 CSS / SCSS 修改全局或局部颜色。FxRate 暴露以下局部 CSS 变量：

变量	默认值
--fx-rate-void-color	var(--color-text-placeholder)
--fx-rate-fill-color	var(--color-warning)
--fx-rate-disabled-void-color	var(--color-text-placeholder)
--fx-rate-text-color	var(--color-text-primary)
--fx-rate-outline-color	var(--color-primary-light-5)

如：:root { --fx-rate-fill-color: red; --fx-rate-void-color: blue; }。也可通过 voidColor / colors / disabledVoidColor / textColor props 直接指定（会以 inline CSS 变量覆盖默认值）。

API

Attributes

参数	说明	类型	默认值
model-value / v-model	绑定值	number	0
id	原生 id	string	—
max	最大分值（星数）	number	5
size	尺寸	'large' | 'default' | 'small'	'default'
disabled	是否只读	boolean	false
allow-half	是否允许半选	boolean	false
step	步进值，键盘与鼠标共用（优先于 allow-half；'1'/'0.X'/'0.XX' 或 number，字符串最多 2 位小数）	RateStep | number	—
low-threshold	低档与中档分界值（本身归低档）	number	2
high-threshold	中档与高档分界值（本身归高档）	number	4
colors	填充色（数组三档 / 对象按阈值映射）	string[] | Record<number, string>	['', '', '']（走默认 warning 色）
void-color	未选中图标颜色	string	''（走 --color-text-placeholder）
disabled-void-color	只读时未选中图标颜色	string	''（走 --color-text-placeholder）
icons	填充图标（数组三档 / 对象按阈值映射）	RateIcon[] | Record<number, RateIcon>	['ep:star-filled', 'ep:star-filled', 'ep:star-filled']
void-icon	未选中图标	RateIcon	'ep:star'
disabled-void-icon	只读时未选中图标	RateIcon	'ep:star-filled'
show-text	是否显示辅助文字	boolean	false
show-score	是否显示当前分值（与 show-text 互斥）	boolean	false
text-color	文字颜色	string	''（走 --color-text-primary）
texts	辅助文字数组（长度应等于 max）	string[]	['极差', '失望', '一般', '满意', '惊喜']
score-template	分值模板（{value} 占位）	string	'{value}'
clearable	是否允许再次点击同值清零	boolean	false
aria-label	原生 aria-label	string	'rating'

RateIcon = string \| Component：字符串为 IconString 类型（即 FxIcon 图标名，如 ep:star-filled、ant-design:home、svg:xxx），亦可传 SVG / 组件。

Events

名称	说明	类型
update:modelValue	值变化时触发（含初始 0）	(value: number) => void
change	值实际变化时触发	(value: number) => void

Exposes

名称	说明	类型
setCurrentValue	设置当前值（hover 时由内部调用）	(value: number, event?: MouseEvent) => void
resetCurrentValue	重置当前值到 modelValue	() => void

键盘操作

聚焦后支持方向键调整分值（allow-half 时步长 0.5，否则 1）：

按键	动作
↑ / →	增加分值
↓ / ←	减少分值

实现说明

• 颜色 / 图标映射：colors 与 icons 数组按 lowThreshold / highThreshold / max 三个键转成对象表，命中时 excluded 用 <、否则 <=，取最小匹配键的值。对象形式可直接用键作为阈值。
• 半星渲染：allow-half 时通过 event.offsetX * 2 <= iconClientWidth 判断指针位于图标左/右半区，决定 value - 0.5 还是 value。半星由两层图标叠加——底层 void、上层 fill 通过 .fx-rate__decimal 的 overflow: hidden 与 width: 50% 裁剪出半颗。禁用 + 非整数 modelValue 时按 valueDecimal % 裁剪，呈现按比例填充的部分星。
• clearable：在 selectValue 中判断“再次点击同值”时清零，并触发 update:modelValue 与 change。
• step 步进：step 为字符串字面量（'1'/'0.X'/'0.XX'，最多 2 位小数，超过在 IDE 报类型错误），parseFloat 解析后参与计算。actualStep = parseFloat(step) ?? (allow-half ? 0.5 : 1)，step 优先于 allow-half。键盘 ↑→↓← 按 actualStep 增减；鼠标 hover 时 offsetX / iconWidth 先 clamp 到 0~1（__item 右侧 margin 区域算本颗满，避免跨颗）再量化 round(ratio / step) * step。当前值统一 Math.round(v*100)/100 规整到 2 位小数避免浮点累积。decimal 裁剪宽度按当前值小数部分百分比（统一 allow-half 50% 与自定义 step）。解析失败或越界时 dev 环境 console.warn 并回落 allow-half 推断。
• 图标色控制：FxIcon 默认 color: currentColor，图标色由外层 .fx-rate__icon / .fx-rate__decimal 的 color 决定；is-active 切到 --fx-rate-fill-color，未选中走 --fx-rate-void-color，禁用未选中走 --fx-rate-disabled-void-color。消费方传入的 voidColor / disabledVoidColor / colors 通过 inline CSS 变量覆盖默认 token。
• 固定容器宽度：.fx-rate__icon { width: 1em; height: 1em } 固定宽高，decimal 分支下子元素全 absolute 时容器不塌陷，是半星裁剪生效的前提。
• 默认填充色：未传 colors 时走 var(--color-warning)（黄星）。