syncfusion-angular-stepper

实现 Syncfusion Angular Stepper

Syncfusion Angular Stepper 组件可显示分步流程或工作流，适用于向导、引导流程或多步表单。本技能将引导你实现、配置和自定义 Stepper 组件，并全面控制步骤的外观、验证、事件和动画。

何时使用此技能

在以下情况下使用此技能：

• 构建多步向导或工作流
• 创建分步表单或引导流程
• 配置步骤验证和线性流程
• 为步骤添加图标、标签和自定义模板
• 处理步骤事件（created、stepChanged、stepChanging、beforeStepRender、stepClick）
• 使用动画和样式自定义步骤外观
• 实现工具提示、全球化或 RTL 支持

组件概述

Stepper 组件提供：

• 多种步骤类型：默认（图标 + 标签）、仅指示器、仅标签
• 两种方向：水平（默认）和垂直
• 丰富的事件系统：created、stepChanged、stepChanging、beforeStepRender、stepClick
• 步骤验证：线性流程、完成状态、条件式进度控制
• 自定义选项：图标、标签、模板、动画、工具提示
• 无障碍支持：符合 WCAG 标准、键盘导航、RTL 支持

完整目录

🚀 入门

📄 阅读： references/getting-started.md

• 安装和包配置
• Angular CLI 设置和依赖项
• 在独立 Angular 中实现基本 Stepper
• CSS 导入和主题设置
• 首次渲染和初始配置

📋 API 参考

📄 阅读： references/api-reference.md

• Stepper 组件属性：activeStep、animation、cssClass、enablePersistence、enableRtl、labelPosition、linear、locale、orientation、readOnly、showTooltip、stepType、steps、template、tooltipTemplate
• 步骤模型属性：cssClass、disabled、iconCss、isValid、label、optional、status、text
• 动画设置：enable、duration、delay
• Stepper 方法：destroy()、nextStep()、previousStep()、refreshProgressbar()、reset()
• 事件概览：created、stepChanged、stepChanging、stepClick、beforeStepRender
• 枚举：StepType、StepStatus、StepLabelPosition、StepperOrientation

⚙️ 配置步骤

📄 阅读： references/steps-configuration.md

• 使用 <e-step> 指令添加步骤
• 使用 iconCss 属性配置图标
• 设置标签和文本内容
• 使用 activeStep 设置当前活动步骤
• 可选步骤和禁用步骤
• 步骤只读模式
• 跟踪步骤状态
• 使用 isValid 属性验证步骤
• 标签位置和对齐方式

🎨 选择步骤类型

📄 阅读： references/step-types.md

• 使用默认类型显示指示器和标签
• 在紧凑布局中使用仅指示器类型
• 使用仅标签类型进行文本导航
• 标签位置（顶部、底部、起始、末尾）
• 各类型的适用场景
• 类型选择模式

📐 设置方向

📄 阅读： references/orientations-and-layouts.md

• 水平方向（默认）
• 适用于高布局的垂直方向
• 布局配置和响应式设计
• 根据使用场景选择方向

🎯 处理事件和交互

📄 阅读： references/events-and-interactions.md

• 用于初始化的 created 事件
• 步骤变更后的 stepChanged 事件（含 EventArgs）
• 用于阻止步骤变更的 stepChanging 事件（含 EventArgs）
• 用于渲染前自定义的 beforeStepRender 事件（含 EventArgs）
• 用于处理点击的 stepClick 事件（含 EventArgs）
• 完整的 EventArgs 参考文档
• 事件处理模式和最佳实践

✅ 验证与流程控制

📄 阅读： references/validation-and-flow.md

• 用于按顺序推进的线性流程配置
• 步骤验证和完成状态
• 步骤状态管理
• 条件式步骤推进
• 错误处理和状态管理

🎭 模板与样式

📄 阅读： references/templates-and-customization.md

• 使用 <ng-template> 自定义步骤模板
• 模板绑定和数据上下文
• CSS 类自定义（cssClass 属性）
• 布局和外观自定义
• 响应式样式模式

🌟 高级功能

📄 阅读： references/advanced-features.md

• 使用 StepperAnimationSettingsModel 设置动画（时长、延迟、启用状态）
• 工具提示配置和工具提示模板
• 全球化和本地化（i18n）
• 使用 enableRtl 支持 RTL（从右向左）
• 无障碍功能和键盘导航
• 符合 WCAG 标准并支持屏幕阅读器

快速入门示例

import { Component } from "@angular/core";
import { StepperAllModule, StepperModule } from "@syncfusion/ej2-angular-navigations";

@Component({
  imports: [ StepperAllModule, StepperModule ],
  standalone: true,
  selector: 'app-root',
  template: `
    <div class="stepper-container">
      <ejs-stepper>
        <e-steps>
          <e-step label="Cart" iconCss="sf-icon-cart"></e-step>
          <e-step label="Delivery Address" iconCss="sf-icon-transport"></e-step>
          <e-step label="Payment" iconCss="sf-icon-payment"></e-step>
          <e-step label="Confirmation" iconCss="sf-icon-success"></e-step>
        </e-steps>
      </ejs-stepper>
    </div>
  `,
  styles: [`
    .stepper-container {
      padding: 20px;
      max-width: 800px;
      margin: 0 auto;
    }
  `]
})
export class AppComponent { }

常见模式

模式 1：带表单验证的向导

<ejs-stepper (stepChanging)="onStepChanging($event)">
  <e-steps>
    <e-step label="Personal Info"></e-step>
    <e-step label="Contact Details"></e-step>
    <e-step label="Address"></e-step>
    <e-step label="Confirmation"></e-step>
  </e-steps>
</ejs-stepper>

使用 stepChanging 事件，在允许步骤推进前验证表单数据。

模式 2：动态步骤图标

<ejs-stepper>
  <e-steps>
    <e-step *ngFor="let step of steps" 
            [label]="step.label" 
            [iconCss]="step.icon"></e-step>
  </e-steps>
</ejs-stepper>

使用 *ngFor 指令动态绑定步骤数据。

模式 3：线性工作流

<ejs-stepper [linear]="true">
  <e-steps>
    <e-step label="Step 1"></e-step>
    <e-step label="Step 2"></e-step>
    <e-step label="Step 3"></e-step>
  </e-steps>
</ejs-stepper>

启用 linear 属性以强制按顺序推进。

模式 4：事件处理

onStepChanged(args: StepperChangedEventArgs) {
  console.log(`Active step index: ${args.activeStep}`);
}

onStepChanging(args: StepperChangingEventArgs) {
  if (!isFormValid()) {
    args.cancel = true; // Prevent step change
  }
}

使用事件处理程序跟踪导航并验证进度。

关键属性摘要

属性	类型	默认值	使用场景
stepType	StepType	Default	更改显示样式：Default、Indicator、Label
orientation	Orientation	Horizontal	设置布局：Horizontal 或 Vertical
linear	boolean	false	强制按顺序推进
activeStep	number	0	设置当前活动步骤（从 0 开始索引）
animation	StepperAnimationSettingsModel	enabled	配置过渡动画
showTooltip	boolean	false	鼠标悬停在步骤上时显示工具提示
labelPosition	string	Bottom	设置标签位置：Top、Bottom、Start、End
readOnly	boolean	false	禁用所有步骤交互
cssClass	string	-	应用自定义 CSS 类
enableRtl	boolean	false	为阿拉伯语、希伯来语和乌尔都语启用 RTL
enablePersistence	boolean	false	在页面重新加载之间保留状态
locale	string	en-US	设置语言/区域文化

完整 API 参考和代码示例请参阅： 📚 API 参考

常见使用场景

向导表单：实现多步骤表单向导，并在每一步进行验证 引导流程：引导新用户完成设置或入门步骤 流程跟踪：显示工作流进度（订单处理、求职申请） 多步骤结账：创建包含地址和支付步骤的购物车工作流 设置助手：通过引导式逐步设置来配置工具或服务 文档提交：通过多步骤上传文档并进行验证

---

后续步骤： 根据需要实现的内容，选择上方的参考资料。如果这是你首次使用 Stepper 组件，请从 getting-started.md 开始。