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

# PisellPercent 百分比组件

## 组件介绍

PisellPercent 是基于 PisellNumber 派生的百分比组件，专门用于处理比例、完成度、增长率等百分比数据场景。它支持文本、进度条、环形进度三种展示变体，并提供范围转换、滑块调节等特性。

**核心特性**：

- ✅ 三种展示变体：text、progress、circle
- ✅ 范围自动转换：[0, 100]、[0, 1]、自定义
- ✅ 默认显示百分号
- ✅ 支持滑块+输入框组合编辑
- ✅ 继承 PisellNumber 的所有能力

---

## 基础用法

### Text 变体（纯文本）

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

export default () => {
    const [value, setValue] = useState<number | null>(85.5);

    return (
        <PisellPercent
            value={value}
            onChange={setValue}
        />
    );
};
```

### 只读态展示

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

export default () => {
    return (
        <PisellPercent
            mode="read"
            value={85.5}
        />
    );
};
```

---

## 展示变体

### Text 变体

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

export default () => {
    return (
        <PisellPercent
            mode="read"
            value={85.5}
            variant="text"
        />
    );
};
```

### Progress 变体（进度条）

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

export default () => {
    return (
        <PisellPercent
            mode="read"
            value={75}
            variant="progress"
            style={{width: 300}}
        />
    );
};
```

### Circle 变体（环形进度）

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

export default () => {
    return (
        <PisellPercent
            mode="read"
            value={80}
            variant="circle"
        />
    );
};
```

### 自定义进度条样式

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

export default () => {
    return (
        <div style={{display: 'flex', flexDirection: 'column', gap: 24}}>
            {/* 自定义颜色 */}
            <PisellPercent
                mode="read"
                value={90}
                variant="progress"
                progressProps={{
                    strokeColor: '#52c41a',
                    showInfo: true,
                    status: 'success',
                }}
            />

            {/* 自定义环形进度 */}
            <PisellPercent
                mode="read"
                value={75}
                variant="circle"
                circleProps={{
                    width: 150,
                    strokeColor: '#1890ff',
                    strokeWidth: 8,
                }}
            />
        </div>
    );
};
```

---

## 范围转换

### [0, 100] 范围（默认）

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

export default () => {
    const [value, setValue] = useState<number | null>(85.5);

    return (
        <PisellPercent
            value={value}
            onChange={setValue}
            range={[0, 100]}
        />
    );
};
```

### [0, 1] 范围

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

export default () => {
    const [value, setValue] = useState<number | null>(0.855);

    return (
        <div>
            <div style={{marginBottom: 8}}>??? � 100 ???????0.855 ? ?? 85.5%</div>
            <PisellPercent
                value={value}
                onChange={setValue}
                range={[0, 1]}
            />
        </div>
    );
};
```

### 自定义范围

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

export default () => {
    const [value, setValue] = useState<number | null>(855);

    return (
        <div>
            <div style={{marginBottom: 8}}>按比例转换：(855 / 1000) × 100 = 85.5%</div>
            <PisellPercent
                value={value}
                onChange={setValue}
                range={[0, 1000]}
            />
        </div>
    );
};
```

---

## 编辑态

### 仅输入框

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

export default () => {
    const [value, setValue] = useState<number | null>(null);

    return (
        <PisellPercent
            value={value}
            onChange={setValue}
            min={0}
            max={100}
            step={0.1}
            placeholder="请输入百分比"
        />
    );
};
```

### 滑块 + 输入框

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

export default () => {
    const [value, setValue] = useState<number | null>(50);

    return (
        <PisellPercent
            value={value}
            onChange={setValue}
            showSlider
            sliderProps={{
                marks: {
                    0: '0%',
                    50: '50%',
                    100: '100%',
                },
            }}
        />
    );
};
```

---

## 项目进度看板

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

export default () => {
    const tasks = [
        {name: '前端开发', completion: 85.5},
        {name: '后端开发', completion: 72},
        {name: '测试', completion: 45},
    ];

    return (
        <div>
            {tasks.map((task) => (
                <div key={task.name} style={{marginBottom: 24}}>
                    <div style={{display: 'flex', justifyContent: 'space-between', marginBottom: 8}}>
                        <span>{task.name}</span>
                        <PisellPercent mode="read" value={task.completion} variant="text"/>
                    </div>
                    <PisellPercent
                        mode="read"
                        value={task.completion}
                        variant="progress"
                        progressProps={{
                            strokeColor: task.completion === 100 ? '#52c41a' : '#1890ff',
                        }}
                    />
                </div>
            ))}
        </div>
    );
};
```

---

## API 文档

### Props 属性

| 属性名                 | 类型                                 | 默认值        | 说明                 |
|---------------------|------------------------------------|------------|--------------------|
| **百分比特有**           |                                    |            |                    |
| showPercentSymbol   | `boolean`                          | `true`     | 是否显示 % 符号          |
| range               | `[number, number]`                 | `[0, 100]` | 百分比范围              |
| variant             | `'text' \| 'progress' \| 'circle'` | `'text'`   | 展示变体               |
| progressProps       | `ProgressProps`                    | -          | 进度条配置              |
| circleProps         | `ProgressProps`                    | -          | 环形进度配置             |
| showSlider          | `boolean`                          | `false`    | 是否显示滑块             |
| sliderProps         | `SliderProps`                      | -          | 滑块配置               |
| **继承 PisellNumber** |                                    |            |                    |
| mode                | `'read' \| 'edit'`                 | `'edit'`   | 显示模式               |
| value               | `number \| null`                   | -          | 当前值                |
| min                 | `number`                           | `0`        | 最小值                |
| max                 | `number`                           | `100`      | 最大值                |
| precision           | `number`                           | `1`        | 小数精度               |
| ...                 | ...                                | ...        | 其他 PisellNumber 属性 |

---

## 常见问题

### 1. 三种变体的区别？

- **text**：纯文本，简单清晰
- **progress**：进度条，直观展示进度
- **circle**：环形进度，适合仪表盘

### 2. 如何使用 [0, 1] 范围？

```
<PisellPercent value={0.75} range={[0, 1]} />
// 显示: 75%
```

### 3. 如何隐藏百分号？

```
<PisellPercent showPercentSymbol={false} />
```

### 4. 如何自定义进度条颜色？

```
<PisellPercent
  variant="progress"
  progressProps={{ strokeColor: '#52c41a' }}
/>
```

---

## 最佳实践

1. **选择合适的变体**：

- 简单展示 → text
- 进度展示 → progress
- 仪表盘 → circle

2. **精度设置**：一般 1 位小数即可

3. **范围匹配**：根据数据源选择 range

4. **滑块使用**：需要快速调整时启用 showSlider

---

## 相关组件

- **PisellNumber** - 基础数值组件
- **PisellCurrency** - 货币组件
