# ProgressBar 进度条

一个灵活的进度指示器组件，支持圆形和线性显示模式，具有可自定义的状态和样式。

## 安装

```bash
npm install @ticatec/uniface-element
```

## 导入

```typescript
import ProgressBar, { ProgressStatus } from "@ticatec/uniface-element/ProgressBar";
```

## 基本用法

### 圆形进度条

```svelte
<script>
  import ProgressBar, { ProgressStatus } from "@ticatec/uniface-element/ProgressBar";
  
  let progress = 65;
  let status = ProgressStatus.progressing;
</script>

<ProgressBar {progress} {status} />
```

### 线性进度条

```svelte
<script>
  import ProgressBar, { ProgressStatus } from "@ticatec/uniface-element/ProgressBar";
  
  let progress = 45;
  let status = ProgressStatus.progressing;
</script>

<ProgressBar type="liner" {progress} {status} />
```

## 属性

| 属性 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `progress` | `number` | `0` | 进度值（0-100） |
| `size` | `number` | `100` | 圆形进度条的大小 |
| `type` | `"circular" \| "liner"` | `"circular"` | 进度条的显示类型 |
| `height` | `number` | `5` | 进度条的高度/厚度 |
| `showText` | `boolean` | `true` | 是否显示进度文本 |
| `status` | `ProgressStatus` | `ProgressStatus.progressing` | 进度的当前状态 |

## ProgressStatus 枚举

```typescript
enum ProgressStatus {
  progressing = 'progressing',  // 进行中
  successful = 'successful',    // 成功
  failure = 'failure',          // 失败
  canceled = 'canceled'         // 已取消
}
```

## 状态指示器

进度条根据状态显示不同的指示器：

- **进行中(progressing)**: 显示百分比（如 "65%"）
- **成功(successful)**: 显示对勾标记（✔）
- **失败(failure)**: 显示叉号标记（✕）
- **已取消(canceled)**: 显示感叹号（!）

## 示例

### 不同状态

```svelte
<script>
  import ProgressBar, { ProgressStatus } from "@ticatec/uniface-element/ProgressBar";
</script>

<!-- 进行中 -->
<ProgressBar progress={75} status={ProgressStatus.progressing} />

<!-- 成功完成 -->
<ProgressBar progress={100} status={ProgressStatus.successful} />

<!-- 失败 -->
<ProgressBar progress={45} status={ProgressStatus.failure} />

<!-- 已取消 -->
<ProgressBar progress={30} status={ProgressStatus.canceled} />
```

### 自定义尺寸

```svelte
<!-- 大型圆形进度条 -->
<ProgressBar size={150} height={8} progress={60} />

<!-- 细线性进度条 -->
<ProgressBar type="liner" height={2} progress={40} />
```

### 不显示文本

```svelte
<ProgressBar progress={80} showText={false} />
```

## CSS 自定义属性

组件使用 CSS 自定义属性进行主题定制：

```css
:root {
  /* 默认进度颜色 */
  --uniface-progress-bar-color: #22BDFF;
  
  /* 背景颜色 */
  --uniface-progress-bar-bg: #E2E8F0;
  
  /* 成功状态颜色 */
  --uniface-progress-bar-success-color: #2DC071;
  
  /* 失败状态颜色 */
  --uniface-progress-bar-failure-color: #FF685B;
  
  /* 取消状态颜色 */
  --uniface-progress-bar-canceled-color: #FFC532;
}
```

## 样式示例

### 自定义主题

```css
.custom-progress {
  --uniface-progress-bar-color: #8B5CF6;
  --uniface-progress-bar-success-color: #10B981;
  --uniface-progress-bar-failure-color: #EF4444;
}
```

```svelte
<div class="custom-progress">
  <ProgressBar progress={70} />
</div>
```

## 高级用法

### 动画进度

```svelte
<script>
  import { onMount } from 'svelte';
  import ProgressBar, { ProgressStatus } from "@ticatec/uniface-element/ProgressBar";
  
  let progress = 0;
  let status = ProgressStatus.progressing;
  
  onMount(() => {
    const interval = setInterval(() => {
      progress += 1;
      if (progress >= 100) {
        status = ProgressStatus.successful;
        clearInterval(interval);
      }
    }, 50);
    
    return () => clearInterval(interval);
  });
</script>

<ProgressBar {progress} {status} />
```

### 文件上传进度示例

```svelte
<script>
  import ProgressBar, { ProgressStatus } from "@ticatec/uniface-element/ProgressBar";
  
  let uploadProgress = 0;
  let uploadStatus = ProgressStatus.progressing;
  
  async function handleUpload() {
    uploadProgress = 0;
    uploadStatus = ProgressStatus.progressing;
    
    try {
      // 模拟上传进度
      for (let i = 0; i <= 100; i += 10) {
        uploadProgress = i;
        await new Promise(resolve => setTimeout(resolve, 200));
      }
      uploadStatus = ProgressStatus.successful;
    } catch (error) {
      uploadStatus = ProgressStatus.failure;
    }
  }
</script>

<ProgressBar 
  type="liner" 
  progress={uploadProgress} 
  status={uploadStatus} 
  height={6}
/>
```

## 无障碍访问

- 为屏幕阅读器使用适当的 ARIA 属性
- 文本内容根据状态变化，提供更好的无障碍访问
- 颜色变化伴随符号变化，适合色盲用户
- 所有状态都保持适当的对比度

## 最佳实践

1. **进度范围**: 保持进度值在 0-100 之间
2. **状态管理**: 根据操作结果适当更新状态
3. **视觉反馈**: 使用不同的状态提供清晰的用户反馈
4. **响应式设计**: 考虑使用基于百分比的尺寸实现响应式布局
5. **颜色无障碍**: 不要仅依赖颜色来传达状态信息

## 浏览器支持

- 支持 SVG 的现代浏览器（圆形类型）
- CSS 自定义属性支持
- 兼容 Svelte 5+

## 相关组件

- `ProgressStepBar` - 多步骤进度指示器
- `Button` - 用于触发显示进度的操作
- `Dialog` - 在模态框中显示进度