For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/llms-full.txt, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/components/rate.md.

Rate 评分

选择或展示评分。

基础用法

重复点击当前评分会清空为 0;设置 allowClear={false} 可禁止清除。悬停只预览评分,移出后恢复已选值。

basic.tsx
import { FormField, Rate } from '@ifhover/leaf-ui';

export function RateBasic() {
  return (
    <FormField label="项目评分" layout="vertical">
      <Rate defaultValue={3} />
    </FormField>
  );
}

示例

半星评分

开启 allowHalf 后可按 0.5 分选择,value 和 onChange 也使用对应的小数值。

half.tsx
import { FormField, Rate } from '@ifhover/leaf-ui';

export function RateHalf() {
  return (
    <FormField label="项目评分" layout="vertical">
      <Rate defaultValue={3.5} allowHalf />
    </FormField>
  );
}

只读与禁用

两者都禁止修改;需要仍参与表单提交时使用 readOnly。

只读
禁用
states.tsx
import { Flex, Grid, Rate, Text } from '@ifhover/leaf-ui';

export function RateStates() {
  return (
    <Grid columns={{ xs: 1, sm: 2 }} gap={16} align="center">
      <Text tone="muted">只读</Text>
      <Flex align="center" wrap>
        <Rate aria-label="只读评分" defaultValue={3} readOnly />
      </Flex>
      <Text tone="muted">禁用</Text>
      <Flex align="center" wrap>
        <Rate aria-label="禁用评分" defaultValue={3} disabled />
      </Flex>
    </Grid>
  );
}

受控评分

通过 value 和 onChange 管理评分。受控字段不会在表单重置时自行恢复,需同时重置应用状态。

当前评分:3
controlled.tsx
import { Button, FormField, Rate, Space, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function RateControlled() {
  const [value, setValue] = useState(3);

  return (
    <Space direction="vertical" align="start">
      <FormField label="项目评分" layout="vertical">
        <Rate value={value} onChange={setValue} />
      </FormField>
      <Text tone="muted" role="status">
        当前评分:{value}
      </Text>
      <Button variant="outline" onClick={() => setValue(3)}>
        重置
      </Button>
    </Space>
  );
}

评分颜色

colorByValue 随评分改变颜色;设置 color 可固定颜色,并优先于按评分配色。

按评分
固定颜色
colors.tsx
import { Flex, Grid, Rate, Text } from '@ifhover/leaf-ui';

export function RateColors() {
  return (
    <Grid columns={{ xs: 1, sm: 2 }} gap={16} align="center">
      <Text tone="muted">按评分</Text>
      <Flex align="center" wrap>
        <Rate aria-label="按评分配色" defaultValue={2} colorByValue />
      </Flex>
      <Text tone="muted">固定颜色</Text>
      <Flex align="center" wrap>
        <Rate aria-label="固定配色" defaultValue={2} color="#1d9bf0" />
      </Flex>
    </Grid>
  );
}

表单与键盘

使用 FormField 提供字段名称,设置 name 参与 FormData 提交;清空时提交空字符串。非受控评分支持表单重置,设置 required 可要求非零评分。表单接入见 Form。

方向键调整评分,Home / End 跳至首尾,允许清除时可用 Delete / Backspace 清空。

API

Rate API

配置评分值、步进精度以及只读和清除行为。

属性类型默认值说明
valuenumber—受控评分。
defaultValuenumber0非受控模式的初始评分。
onChange(value: number) => void—评分变化时返回新值,清空为 0。
countnumber5星星数量,最多 20
allowHalfbooleanfalse允许按半星选择。
allowClearbooleantrue重复选择当前评分时清空为 0。
disabledbooleanfalse禁用交互。
readOnlybooleanfalse禁止修改评分,仍参与表单提交。
size'sm' | 'md' | 'lg''md'星星尺寸
colorstring—固定评分颜色,优先于 colorByValue;均未设置时使用金色。
colorByValuebooleanfalse按分数比例使用低、中、高档颜色
colorsreadonly [string, string, string]['#ef5350', '#f49b23', '#ffc53d']低、中、高档颜色;阈值为总分的 40% 和 70%
namestring—原生 FormData 中的字段名。
formstring—关联的原生表单 ID。
requiredbooleanfalse要求评分不为 0。