---
nav:
  title: 组件
  order: 1
group:
  title: General
  order: 1
title: PisellRating
order: 1
category: pro
---

# PisellRating 评分组件

星级评分组件，提供直观的评分交互体验，支持只读、编辑、禁用三种状态。

## 何时使用

- 用户评分场景
- 商品评价展示
- 满意度调查
- 等级展示
- KPI 指标展示

## 代码演示

### 基础用法

默认显示 5 颗星，可点击评分。

```tsx
import { PisellRating } from '@pisell/materials';
import { useState } from 'react';

export default () => {
  const [rating, setRating] = useState(0);
  
  return (
    <PisellRating 
      value={rating} 
      onChange={setRating} 
    />
  );
};
```

### 半星评分

支持更精细的评分（0.5, 1, 1.5, 2, ..., 5）。

```tsx
import { PisellRating } from '@pisell/materials';
import { useState } from 'react';

export default () => {
  const [rating, setRating] = useState(3.5);
  
  return (
    <PisellRating 
      value={rating} 
      onChange={setRating} 
      allowHalf
    />
  );
};
```

### 只读态展示

展示评分结果，不可编辑。

```tsx
import { PisellRating } from '@pisell/materials';

export default () => {
  return (
    <PisellRating 
      mode="read" 
      value={4.2} 
      allowHalf
    />
  );
};
```

### 显示数值文本

同时显示星星和数值。

```tsx
import { PisellRating } from '@pisell/materials';

export default () => {
  return (
    <PisellRating 
      mode="read" 
      value={4.2} 
      allowHalf
      showValue
    />
  );
};
```

### 显示评分人数

展示评分人数统计。

```tsx
import { PisellRating } from '@pisell/materials';

export default () => {
  return (
    <PisellRating 
      mode="read" 
      value={4.5} 
      allowHalf
      showValue
      showCount
      reviewCount={328}
    />
  );
};
```

### 带评分描述

悬停在不同星星上显示对应描述。

```tsx
import { PisellRating } from '@pisell/materials';
import { useState } from 'react';

export default () => {
  const [rating, setRating] = useState(0);
  
  return (
    <PisellRating 
      value={rating} 
      onChange={setRating}
      tooltips={['很差', '差', '一般', '好', '很好']}
    />
  );
};
```

### 自定义星星数量

设置不同的星星数量（如 10 星制）。

```tsx
import { PisellRating } from '@pisell/materials';
import { useState } from 'react';

export default () => {
  const [rating, setRating] = useState(6);
  
  return (
    <PisellRating 
      value={rating} 
      onChange={setRating} 
      max={10}
    />
  );
};
```

### 自定义图标

使用自定义图标代替星星。

```tsx
import { PisellRating } from '@pisell/materials';
import { HeartFilled, SmileFilled } from '@ant-design/icons';
import { useState } from 'react';

export default () => {
  const [rating1, setRating1] = useState(3);
  const [rating2, setRating2] = useState(4);
  
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
      {/* 爱心 */}
      <PisellRating 
        value={rating1} 
        onChange={setRating1}
        character={<HeartFilled />}
        color="#ff4d4f"
      />
      
      {/* 笑脸 */}
      <PisellRating 
        value={rating2} 
        onChange={setRating2}
        character={<SmileFilled />}
        color="#52c41a"
      />
    </div>
  );
};
```

### 不同尺寸

自定义星星大小。

```tsx
import { PisellRating } from '@pisell/materials';

export default () => {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
      <div>
        <span style={{ marginRight: 8 }}>小：</span>
        <PisellRating value={4} size={16} />
      </div>
      <div>
        <span style={{ marginRight: 8 }}>默认：</span>
        <PisellRating value={4} size={20} />
      </div>
      <div>
        <span style={{ marginRight: 8 }}>大：</span>
        <PisellRating value={4} size={24} />
      </div>
    </div>
  );
};
```

### 禁用态

禁用评分交互。

```tsx
import { PisellRating } from '@pisell/materials';

export default () => {
  return (
    <PisellRating 
      value={3} 
      disabled
    />
  );
};
```

### 商品评分场景

完整的商品评分示例。

```tsx
import { PisellRating } from '@pisell/materials';
import { useState } from 'react';
import { Form, Button, Input } from 'antd';

export default () => {
  const [userRating, setUserRating] = useState(0);
  const averageRating = 4.2;
  const reviewCount = 328;
  
  return (
    <div>
      {/* 商品平均评分展示 */}
      <div style={{ marginBottom: 24 }}>
        <div style={{ fontSize: 16, fontWeight: 'bold', marginBottom: 8 }}>
          商品评分
        </div>
        <PisellRating
          mode="read"
          value={averageRating}
          allowHalf
          showValue
          showCount
          reviewCount={reviewCount}
        />
      </div>
      
      {/* 用户评分表单 */}
      <Form layout="vertical">
        <Form.Item label="您的评分">
          <PisellRating
            value={userRating}
            onChange={setUserRating}
            allowHalf
            tooltips={['非常差', '差', '一般', '满意', '非常满意']}
          />
        </Form.Item>
        
        <Form.Item label="评价内容">
          <Input.TextArea rows={4} placeholder="请输入您的评价" />
        </Form.Item>
        
        <Form.Item>
          <Button type="primary">提交评价</Button>
        </Form.Item>
      </Form>
    </div>
  );
};
```

## API

### Props

| 参数              | 说明            | 类型                        | 默认值          |
|-----------------|---------------|---------------------------|--------------|
| mode            | 显示模式          | `'read' \| 'edit'`        | `'edit'`     |
| disabled        | 是否禁用          | `boolean`                 | `false`      |
| value           | 当前评分值（受控）     | `number`                  | -            |
| defaultValue    | 默认评分值（非受控）    | `number`                  | -            |
| onChange        | 评分变更回调        | `(value: number) => void` | -            |
| count           | 星星数量          | `number`                  | `5`          |
| max             | 最大评分值（同count） | `number`                  | `5`          |
| allowHalf       | 是否允许半星评分      | `boolean`                 | `false`      |
| allowClear      | 是否允许清除评分      | `boolean`                 | `true`       |
| character       | 自定义字符         | `ReactNode`               | `StarFilled` |
| tooltips        | 评分描述文本数组      | `string[]`                | -            |
| showValue       | 是否显示数值文本      | `boolean`                 | `false`      |
| showCount       | 是否显示评分人数      | `boolean`                 | `false`      |
| reviewCount     | 评分人数          | `number`                  | -            |
| size            | 星星尺寸（px）      | `number`                  | `20`         |
| color           | 星星颜色（已选中）     | `string`                  | `'#fadb14'`  |
| unselectedColor | 星星颜色（未选中）     | `string`                  | `'#d9d9d9'`  |
| onHoverChange   | 悬停评分值变化回调     | `(value: number) => void` | -            |
| onFocus         | 聚焦回调          | `() => void`              | -            |
| onBlur          | 失焦回调          | `() => void`              | -            |

## 核心功能说明

### 评分模式

**整星评分**（allowHalf=false，默认）：

- 可选值：0, 1, 2, 3, 4, 5
- 点击第 N 颗星 → 评分为 N
- 再次点击已选中的星 → 清除评分（如 allowClear=true）

**半星评分**（allowHalf=true）：

- 可选值：0, 0.5, 1, 1.5, 2, 2.5, 3, 3.5, 4, 4.5, 5
- 点击星星左半部分 → 0.5 星
- 点击星星右半部分 → 1 星

### 交互方式

**鼠标交互**：

- 悬停：悬停位置及之前的星星高亮
- 点击：设置评分值
- 再次点击：清除评分（如 allowClear=true）

**键盘交互**：

- 左箭头 ←：评分值 -1（或 -0.5）
- 右箭头 →：评分值 +1（或 +0.5）

### 自定义图标

支持使用不同图标：

```
import { HeartFilled, SmileFilled } from '@ant-design/icons';

// 爱心
<PisellRating 
  character={<HeartFilled />} 
  color="#ff4d4f"
/>

// 笑脸
<PisellRating 
  character={<SmileFilled />} 
  color="#52c41a"
/>
```

### 评分描述

通过 tooltips 为每个评分级别提供文字说明：

```
<PisellRating 
  tooltips={['非常差', '差', '一般', '好', '很好']}
/>
```

悬停在星星上时显示对应文字。

## 常见问题

### 如何禁止清除评分？

```
<PisellRating allowClear={false} />
```

### 如何使用 3 星制或 10 星制？

```
// 3 星制
<PisellRating max={3} />

// 10 星制
<PisellRating max={10} />
```

### 如何监听悬停变化？

```
<PisellRating 
  onHoverChange={(value) => {
    console.log('悬停在:', value);
  }}
/>
```

### 如何在只读态不显示评分人数？

```
<PisellRating 
  mode="read" 
  value={4.5}
  showCount={false}
/>
```

### 如何自定义星星颜色？

```
<PisellRating 
  color="#ff6b6b"           // 已选中颜色
  unselectedColor="#e0e0e0" // 未选中颜色
/>
```

### 如何在表单中使用？

```tsx
import { Form } from 'antd';
import { PisellRating } from '@pisell/materials';

export default () => {
  return (
    <Form>
      <Form.Item 
        label="您的评分"
        name="rating"
        rules={[{ required: true, message: '请进行评分' }]}
      >
        <PisellRating allowHalf />
      </Form.Item>
    </Form>
  );
};
```

## 注意事项

1. **评分范围**：评分值范围为 0 到 max（默认 5）
2. **半星精度**：allowHalf=true 时，值为 0.5 的倍数
3. **只读态实现**：mode="read" 映射为 Rate 组件的 disabled=true
4. **评分人数**：showCount=true 时需要传入 reviewCount
5. **tooltips 数量**：tooltips 数组长度应等于 max（星星数量）
6. **自定义图标**：character 可以是 ReactNode 或函数
7. **无障碍支持**：组件支持键盘导航和 ARIA 属性

## 设计规范

### 视觉规范

**已选中星星**：

- 颜色：`#fadb14`（金黄色）
- 填充：实心

**未选中星星**：

- 颜色：`#d9d9d9`（浅灰色）
- 填充：空心或实心

**禁用态**：

- 透明度：40%
- 颜色变灰
- 不响应交互

### 尺寸规范

| 尺寸 | size 值 | 使用场景  |
|----|--------|-------|
| 小  | 16     | 表格、卡片 |
| 默认 | 20     | 普通使用  |
| 大  | 24     | 重点展示  |

## 相关组件

- [PisellNumber](../pisellNumber/pisellNumber.md) - 数值输入组件
- [PisellPercent](../pisellPercent/pisellPercent.md) - 百分比组件
