# ProgressStepBar 步骤进度条

一个多步骤进度指示器组件，用于可视化显示顺序流程中各步骤的完成状态。支持水平和垂直两种布局。

## 安装

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

## 导入

```typescript
import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from "@ticatec/uniface-element/ProgressStepBar";
```

## 基本用法

### 水平步骤进度

```svelte
<script>
  import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from "@ticatec/uniface-element/ProgressStepBar";
  
  let steps: Array<ProgressStep> = [
    {
      topic: '注册',
      comment: '完善您的资料',
      status: ProgressStepStatus.Completed
    },
    {
      topic: '验证',
      comment: '验证您的邮箱',
      status: ProgressStepStatus.Processing
    },
    {
      topic: '设置',
      comment: '配置偏好设置',
      status: ProgressStepStatus.Pending
    }
  ];
</script>

<ProgressStepBar {steps} />
```

### 垂直步骤进度

```svelte
<script>
  import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from "@ticatec/uniface-element/ProgressStepBar";
  
  let steps: Array<ProgressStep> = [
    {
      topic: '订单已下单',
      comment: '您的订单已收到',
      status: ProgressStepStatus.Completed
    },
    {
      topic: '处理中',
      comment: '正在准备您的商品',
      status: ProgressStepStatus.Processing
    },
    {
      topic: '已发货',
      comment: '正在送往您的地址',
      status: ProgressStepStatus.Pending
    },
    {
      topic: '已送达',
      comment: '包裹已送达',
      status: ProgressStepStatus.Pending
    }
  ];
</script>

<ProgressStepBar {steps} direction="vertical" />
```

## 属性

| 属性 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `steps` | `Array<ProgressStep>` | 必填 | 进度步骤数组 |
| `direction` | `"horizontal" \| "vertical"` | `"horizontal"` | 步骤布局方向 |
| `backgroundColor` | `string` | `"var(--uniface-progress-step-bar-bg, #ffffff)"` | 步骤条背景色 |
| `style` | `string` | `""` | 额外的CSS样式 |

## ProgressStep 接口

```typescript
interface ProgressStep {
  topic: string;        // 步骤标题/名称
  comment?: string;     // 可选描述
  status: ProgressStepStatus;  // 当前状态
}
```

## ProgressStepStatus 枚举

```typescript
enum ProgressStepStatus {
  Pending = 'pending',       // 未开始
  Processing = 'processing', // 进行中
  Completed = 'completed'    // 已完成
}
```

## 状态指示器

每个步骤根据其状态显示不同的视觉指示器：

- **待处理(Pending)**: 以柔和样式显示步骤编号
- **进行中(Processing)**: 以高亮样式显示步骤编号
- **已完成(Completed)**: 显示对勾标记(✔)，使用成功样式

## 示例

### 动态进度

```svelte
<script>
  import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from "@ticatec/uniface-element/ProgressStepBar";
  import { onMount } from 'svelte';
  
  let steps: Array<ProgressStep> = [
    { topic: '初始化', comment: '正在设置...', status: ProgressStepStatus.Pending },
    { topic: '数据加载', comment: '正在获取数据...', status: ProgressStepStatus.Pending },
    { topic: '处理中', comment: '正在分析...', status: ProgressStepStatus.Pending },
    { topic: '完成', comment: '正在完成...', status: ProgressStepStatus.Pending }
  ];
  
  let currentStep = 0;
  
  onMount(() => {
    const interval = setInterval(() => {
      if (currentStep < steps.length) {
        // 标记当前步骤为进行中
        steps[currentStep].status = ProgressStepStatus.Processing;
        steps = [...steps];
        
        setTimeout(() => {
          // 标记为已完成并移动到下一步
          steps[currentStep].status = ProgressStepStatus.Completed;
          currentStep++;
          
          if (currentStep < steps.length) {
            steps[currentStep].status = ProgressStepStatus.Processing;
          }
          steps = [...steps];
        }, 1500);
      } else {
        clearInterval(interval);
      }
    }, 2000);
    
    return () => clearInterval(interval);
  });
</script>

<ProgressStepBar {steps} />
```

### 自定义背景颜色

```svelte
<script>
  import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from "@ticatec/uniface-element/ProgressStepBar";
  
  let steps: Array<ProgressStep> = [
    { topic: '步骤1', status: ProgressStepStatus.Completed },
    { topic: '步骤2', status: ProgressStepStatus.Processing },
    { topic: '步骤3', status: ProgressStepStatus.Pending }
  ];
</script>

<!-- 浅灰色背景 -->
<ProgressStepBar {steps} backgroundColor="#f8f9fa" />

<!-- 深色主题 -->
<ProgressStepBar {steps} backgroundColor="#2d3748" />
```

### 不显示说明

```svelte
<script>
  import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from "@ticatec/uniface-element/ProgressStepBar";
  
  let steps: Array<ProgressStep> = [
    { topic: '登录', status: ProgressStepStatus.Completed },
    { topic: '验证', status: ProgressStepStatus.Processing },
    { topic: '完成', status: ProgressStepStatus.Pending }
  ];
</script>

<ProgressStepBar {steps} />
```

### 工作流示例

```svelte
<script>
  import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from "@ticatec/uniface-element/ProgressStepBar";
  import Button from "@ticatec/uniface-element/Button";
  
  let currentStepIndex = 0;
  let steps: Array<ProgressStep> = [
    { topic: '账户设置', comment: '创建您的账户', status: ProgressStepStatus.Processing },
    { topic: '个人信息', comment: '添加个人信息', status: ProgressStepStatus.Pending },
    { topic: '偏好设置', comment: '选择您的设置', status: ProgressStepStatus.Pending },
    { topic: '确认', comment: '检查并确认', status: ProgressStepStatus.Pending }
  ];
  
  function nextStep() {
    if (currentStepIndex < steps.length - 1) {
      steps[currentStepIndex].status = ProgressStepStatus.Completed;
      currentStepIndex++;
      steps[currentStepIndex].status = ProgressStepStatus.Processing;
      steps = [...steps];
    }
  }
  
  function prevStep() {
    if (currentStepIndex > 0) {
      steps[currentStepIndex].status = ProgressStepStatus.Pending;
      currentStepIndex--;
      steps[currentStepIndex].status = ProgressStepStatus.Processing;
      steps = [...steps];
    }
  }
</script>

<ProgressStepBar {steps} />

<div style="margin-top: 20px;">
  <Button label="上一步" onClick={prevStep} disabled={currentStepIndex === 0} />
  <Button label="下一步" onClick={nextStep} disabled={currentStepIndex === steps.length - 1} />
</div>
```

## CSS 自定义属性

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

```css
:root {
  /* 背景颜色 */
  --uniface-progress-step-bar-bg: #ffffff;
  
  /* 步骤指示器颜色（在 uniface-progress-step-bar.scss 中定义） */
  --progress-step-pending-color: #e2e8f0;
  --progress-step-processing-color: #22bdff;
  --progress-step-completed-color: #2dc071;
}
```

## 样式示例

### 自定义步骤颜色

```css
.custom-steps {
  --progress-step-pending-color: #cbd5e0;
  --progress-step-processing-color: #8b5cf6;
  --progress-step-completed-color: #10b981;
}
```

```svelte
<div class="custom-steps">
  <ProgressStepBar {steps} />
</div>
```

## 布局考虑

### 水平布局
- 适合3-6个步骤的流程
- 占用容器全宽
- 步骤均匀分布
- 适合线性工作流

### 垂直布局
- 更适合详细的步骤描述
- 固定宽度，高度可变
- 适合侧边栏放置
- 适合多步骤流程

## 最佳实践

1. **步骤数量**: 保持步骤在3-7个之间以获得最佳用户体验
2. **清晰标题**: 使用简洁、描述性的步骤标题
3. **有用说明**: 在步骤注释中提供有用的上下文
4. **状态管理**: 在流程进行期间适当更新步骤状态
5. **视觉层次**: 使用一致的样式和间距
6. **响应式设计**: 根据可用空间考虑布局方向

## 无障碍访问

- 为屏幕阅读器提供适当的语义标记
- 步骤状态之间有清晰的视觉区别
- 颜色不是步骤状态的唯一指示器
- 为每个步骤状态提供描述性文本

## 浏览器支持

- 支持CSS Grid的现代浏览器
- 兼容 Svelte 5+
- 响应式设计原则

## 相关组件

- `ProgressBar` - 简单进度指示器
- `Wizard` - 分步表单导航
- `Breadcrumbs` - 导航层次显示