> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/components/rate.html

> 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.

# Rate 评分

选择或展示评分。


## 基础用法

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


项目评分

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/rate/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

复制代码

```tsx lineNumbers file="../../src/examples/rate/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

复制代码

```tsx lineNumbers file="../../src/examples/rate/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

复制代码

```tsx lineNumbers file="../../src/examples/rate/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

复制代码

```tsx lineNumbers file="../../src/examples/rate/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](https://ifhover.github.io/leaf-ui/components/form.md)。

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


## API

### Rate API

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

| 属性             | 类型                                  | 默认值                                 | 说明                                 |
| -------------- | ----------------------------------- | ----------------------------------- | ---------------------------------- |
| `value`        | `number`                            | —                                   | 受控评分。                              |
| `defaultValue` | `number`                            | `0`                                 | 非受控模式的初始评分。                        |
| `onChange`     | `(value: number) => void`           | —                                   | 评分变化时返回新值，清空为 0。                   |
| `count`        | `number`                            | `5`                                 | 星星数量，最多 20                         |
| `allowHalf`    | `boolean`                           | `false`                             | 允许按半星选择。                           |
| `allowClear`   | `boolean`                           | `true`                              | 重复选择当前评分时清空为 0。                    |
| `disabled`     | `boolean`                           | `false`                             | 禁用交互。                              |
| `readOnly`     | `boolean`                           | `false`                             | 禁止修改评分，仍参与表单提交。                    |
| `size`         | `'sm' \| 'md' \| 'lg'`              | `'md'`                              | 星星尺寸                               |
| `color`        | `string`                            | —                                   | 固定评分颜色，优先于 colorByValue；均未设置时使用金色。 |
| `colorByValue` | `boolean`                           | `false`                             | 按分数比例使用低、中、高档颜色                    |
| `colors`       | `readonly [string, string, string]` | `['#ef5350', '#f49b23', '#ffc53d']` | 低、中、高档颜色；阈值为总分的 40% 和 70%          |
| `name`         | `string`                            | —                                   | 原生 FormData 中的字段名。                 |
| `form`         | `string`                            | —                                   | 关联的原生表单 ID。                        |
| `required`     | `boolean`                           | `false`                             | 要求评分不为 0。                          |
