xtf-rate

组件说明

xtf-rate 是评分组件，用于评价打分、满意度采集或商品/服务评分展示。支持星级、心形、点赞、皇冠、盾牌等十余种图形（display-mode），支持半星（allow-half）、滑动打分（allow-slide）、自定义图片、多项文案标签，以及 product / service / delivery / heat 等业务预设和只读展示（readonly），是评价反馈与数据展示的核心组件。

---

基础用法

1. 最简示例

通过 v-model 双向绑定评分值，count 控制总分：

<template>
  <view style="display: flex; flex-direction: column; gap: 32rpx; padding: 32rpx">
    <xtf-rate v-model="score" :count="5" />
    <xtf-text level="caption" color="secondary" :text="'当前评分: ' + score" />
  </view>
</template>

<script>
export default {
  data() {
    return { score: 3 }
  }
}
</script>

2. 半星与滑动打分

通过 allow-half 开启半星，通过 precision 控制精确度，allow-slide 支持滑动打分：

<template>
  <view style="display: flex; flex-direction: column; gap: 32rpx; padding: 32rpx">
    <xtf-rate v-model="score1" :count="5" allow-half />
    <xtf-text level="caption" color="secondary" :text="'半星评分: ' + score1" />
    <xtf-rate v-model="score2" :count="10" :precision="0.5" />
    <xtf-text level="caption" color="secondary" :text="'十分制滑动: ' + score2" />
  </view>
</template>

<script>
export default {
  data() {
    return { score1: 3.5, score2: 6.5 }
  }
}
</script>

3. 业务预设

通过 preset 一键应用业务预设（product / service / delivery / heat 等），自动携带文案与配色：

<template>
  <view style="display: flex; flex-direction: column; gap: 32rpx; padding: 32rpx">
    <xtf-rate v-model="p1" preset="product" />
    <xtf-rate v-model="p2" preset="service" />
    <xtf-rate v-model="p3" preset="heat" />
  </view>
</template>

<script>
export default {
  data() {
    return { p1: 4, p2: 5, p3: 7 }
  }
}
</script>

4. 图形切换

通过 display-mode 切换星形/心形/点赞/皇冠等图形，active-color / inactive-color 自定义配色：

<template>
  <view style="display: flex; flex-direction: column; gap: 32rpx; padding: 32rpx">
    <xtf-rate v-model="s1" display-mode="star" />
    <xtf-rate v-model="s2" display-mode="heart" active-color="#ef4444" />
    <xtf-rate v-model="s3" display-mode="crown" active-color="#eab308" />
    <xtf-rate v-model="s4" display-mode="bar" active-color="#f97316" :count="10" />
  </view>
</template>

<script>
export default {
  data() {
    return { s1: 4, s2: 3, s3: 5, s4: 8 }
  }
}
</script>

5. 自定义图片

通过 active-image / inactive-image 使用自定义图片代替图形：

<template>
  <view style="display: flex; flex-direction: column; gap: 32rpx; padding: 32rpx">
    <xtf-rate
      v-model="score"
      :count="5"
      active-image="/static/star-active.png"
      inactive-image="/static/star-inactive.png"
    />
  </view>
</template>

<script>
export default {
  data() {
    return { score: 4 }
  }
}
</script>

6. 只读展示

通过 readonly 开启只读展示，readonly-variant 切换 compact / panel 展示形态：

<template>
  <view style="display: flex; flex-direction: column; gap: 32rpx; padding: 32rpx">
    <xtf-rate
      :model-value="4.5"
      readonly
      readonly-variant="compact"
      :review-count="128"
      show-value
      label-mode="text"
    />
    <xtf-rate
      :model-value="4.8"
      readonly
      readonly-variant="panel"
      :review-count="356"
      show-value
      label-mode="text"
    />
  </view>
</template>

---

全部属性

属性	类型	默认值	作用描述	适用范围
value	String | Number	0	评分值（兼容低版本 v-model）	双向绑定
modelValue	String | Number	undefined	评分值（v-model 推荐）	双向绑定
count	String | Number	5	评分总数	设置星级数
preset	String	'default'	业务预设：'product' / 'service' / 'delivery' / 'flavor' / 'heat' / 'recommend' / 'safety' / 'quality' / 'mood' / 'ticket'	一键应用场景
size	String | Number	''	尺寸：'sm' / 'md' / 'lg' 或数值（rpx），默认继承 form / configProvider	控制大小
displayMode	String	'star'	图形：'star' / 'heart' / 'thumb' / 'diamond' / 'bolt' / 'flame' / 'crown' / 'shield' / 'dot' / 'pill' / 'bar' / 'block' / 'ticket'	切换图形
shapeStyle	String	''	图形风格：'filled' / 'outline'	空心/实心
activeColor	String	'var(--xtf-color-warning)'	激活色	自定义颜色
activeImage	String	''	激活态图片	图片评分
inactiveImage	String	''	未激活图片	图片评分
activeImages	Array	[]	每个激活态图片数组	逐项图片
inactiveImages	Array	[]	每个未激活图片数组	逐项图片
imageFit	String	'aspectFit'	图片填充模式	图片适配
color	String	''	自定义激活色（active-color 别名）	自定义颜色
inactiveColor	String	'var(--xtf-color-border)'	未激活色	自定义颜色
gutter	String | Number	8	项间距	间距
allowHalf	Boolean	false	是否支持半星	半星打分
precision	String | Number	1	精确度（0.5 / 1）	精确打分
allowSlide	Boolean	true	是否支持滑动打分	滑动交互
readonly	Boolean	false	是否只读	展示场景
disabled	Boolean	false	是否禁用	禁用交互
clearable	Boolean	false	点击当前值是否清零	重新打分
showValue	Boolean	false	是否显示数值	展示数值
showText	Boolean	false	是否显示文字	展示文案
readonlyVariant	String	'plain'	只读形态：'plain' / 'compact' / 'panel'	只读展示
reviewCount	String | Number	''	评分人数	只读展示
totalScore	String | Number	5	总分（用于计算百分比）	只读展示
reviewLabel	String	''	评分标签	只读展示
percentSuffix	String	'好评率'	百分比后缀	只读展示
labelMode	String	'auto'	文案模式：'value' / 'text' / 'both'	文案展示
texts	Array	[]	各档位文案	自定义文案
colorRanges	Array	[]	分段颜色：[{ min, max, color }]	分段配色
itemLabels	Array	[]	每项下方标签	标签展示
showItemLabels	Boolean	false	是否显示项标签	标签展示
itemLabelMode	String	'always'	项标签模式：'always' / 'ends'	标签模式
startText	String	''	起始附加文字	附加文案
endText	String	''	结束附加文字	附加文案
itemMinWidth	String | Number	''	每项最小宽度	布局
activeScale	String | Number	1	激活项缩放	视觉强调
inactiveScale	String | Number	1	未激活项缩放	视觉弱化
valueFormatter	Function	null	自定义文案格式化 ({ value, text, count }) => String	自定义文案
customClass	String	''	自定义类名	样式覆盖
customStyle	String | Object	''	自定义样式	动态样式覆盖

colorRanges 数组每项支持的字段

字段	类型	默认值	说明
min	Number	1	范围起始（含）
max	Number	count	范围结束（含）
color	String	''	该范围激活色

---

事件

事件名称	触发时机	回调参数	参数说明
change	评分变化时触发（点击/滑动）	(value: Number)	新的评分值
input	兼容低版本 v-model	(value: Number)	新的评分值
update:modelValue	v-model 同步	(value: Number)	新的评分值
update:selected	评分变化时触发	(payload: { value, source, text, count })	值、来源（tap / touch / mouse）、文案、总数

事件使用示例

<template>
  <view style="display: flex; flex-direction: column; gap: 32rpx; padding: 32rpx">
    <xtf-rate
      v-model="score"
      :count="5"
      show-value
      label-mode="both"
      @change="onChange"
      @update:selected="onSelected"
    />
    <xtf-text level="caption" color="secondary" :text="'当前评分: ' + score" />
  </view>
</template>

<script>
export default {
  data() {
    return { score: 0 }
  },
  methods: {
    onChange(val) {
      console.log('评分变化:', val)
    },
    onSelected(payload) {
      console.log('选择:', payload.value, payload.text, '来源:', payload.source)
      uni.showToast({ title: '评分: ' + payload.value + ' ' + payload.text, icon: 'none' })
    }
  }
}
</script>

---

插槽

xtf-rate 暂未开放插槽，评分图形与文案均通过属性配置。

---

主题说明

• 激活色使用 var(--xtf-rate-active)，未激活色使用 var(--xtf-rate-inactive)
• 项间距使用 var(--xtf-rate-gap)，总数使用 var(--xtf-rate-count)
• 图形/图片尺寸使用 var(--xtf-rate-shape-size) / var(--xtf-rate-symbol-size) / var(--xtf-rate-image-size)
• 激活/未激活缩放使用 var(--xtf-rate-active-scale) / var(--xtf-rate-inactive-scale)
• 附加文字尺寸使用 var(--xtf-rate-addon-size)，项标签尺寸使用 var(--xtf-rate-meta-size)
• 默认激活色为 --xtf-color-warning，未激活色为 --xtf-color-border

如需全局调整主题，请在 xtf-config-provider 或主题配置中覆盖上述 CSS 变量。