syncfusion-javascript-stepper

实现 Syncfusion TypeScript Stepper 控件

完整目录

1. 入门

• 入门指南
• 安装与设置
• 第一个 Stepper
• CSS 主题

2. API 参考

• 完整 API 参考
  • Stepper 属性（15 个属性）
  • Stepper 方法（12 个方法）
  • Stepper 事件（5 个事件）
  • Step 属性（8 个属性）
  • 枚举与类型（4 个枚举）
  • 动画设置（3 个属性）
  • 事件参数（4 个参数接口）

3. 核心概念

• 步骤配置

  • 添加与管理步骤
  • Step 属性（label、iconCss、text、disabled、optional、status、isValid）
  • 禁用步骤
  • 设置只读模式
  • 设置活动步骤
  • 仅图标、仅标签和混合步骤
  • 验证状态

• Step 类型

  • 默认类型（图标 + 标签）
  • 仅标签类型
  • 仅指示器类型
  • 标签位置（顶部、底部、起始、末尾）
  • 类型比较与选择
  • 动态切换类型

• 方向与布局

  • 水平方向（默认）
  • 垂直方向
  • 响应式行为
  • 动态切换布局
  • 特定布局的样式设置

4. 高级功能

• 事件与交互

  • 全部 5 个事件：
    • created
    • beforeStepRender
    • stepClick
    • stepChanging（可取消）
    • stepChanged
  • 事件参数与属性
  • 事件处理模式
  • 使用事件进行验证
  • 检测用户交互

• 模板与动画

  • 自定义步骤模板
  • 模板上下文变量
  • 模板数据绑定
  • 自定义工具提示
  • 动画配置
  • 动画持续时间与延迟
  • 启用/禁用动画

• 验证与全球化

  • 步骤验证（isValid 状态）
  • 强制线性流程
  • 阻止无效转换
  • 本地化（L10n、Locale）
  • 从右到左（RTL）支持
  • 多语言支持
  • 无障碍功能（ARIA、键盘导航）

5. 实用工具与模式

• 故障排查与最佳实践
  • 常见设置问题
  • 事件处理最佳实践
  • 表单验证模式
  • CSS 自定义
  • 主题集成
  • 性能优化
  • 边缘情况与解决方案

---

何时使用此技能

在以下情况下，请使用 Syncfusion TypeScript Stepper 技能：

• 显示多步骤流程或向导工作流
• 创建用于显示完成状态的进度指示器
• 构建在步骤之间进行验证的表单向导
• 展示分步引导体验（结账、引导入门、设置）
• 添加带有后退/前进控件的步骤导航
• 实现线性工作流验证
• 创建带跟踪功能的检查点式流程
• 支持使用图标、标签和模板自定义步骤
• 处理步骤事件和用户交互
• 支持多种方向（水平/垂直布局）

Stepper 概览

Stepper 是一种导航控件，用于显示一系列逻辑步骤，引导用户完成工作流。每个步骤可以包含：

• 指示器（数字、图标或形状）
• 标签（文本说明）
• 状态跟踪（活动、已完成、已禁用）
• 用于步骤转换的事件处理程序
• 用于丰富内容的自定义模板
• 使用主题进行的灵活样式设置

主要特征

方面	描述
组件	用于多步骤工作流的导航控件
步骤	包含属性的步骤对象数组
指示器	带编号或基于图标的步骤标记
方向	水平（默认）或垂直布局
类型	默认（图标 + 标签）、仅标签、仅指示器
事件	created、beforeStepRender、stepClick、stepChanging、stepChanged
方法	12 个控制方法（nextStep、previousStep、reset 等）
属性	15 个 stepper 属性 + 8 个 step 属性
自定义	模板、动画、主题、CSS 样式

---

文档与导航指南

📚 学习路径（推荐顺序）

1. 从这里开始： 入门指南

   • 安装和 npm 包设置
   • 依赖项（ej2-navigations、ej2-base、ej2-popups）
   • 开发环境配置
   • 使用代码示例初始化基本 stepper
   • CSS 导入和主题设置

2. 基础知识： 步骤配置

   • 向 stepper 添加步骤
   • 步骤属性（iconCss、text、label、cssClass、disabled、status）
   • 使用 StepModel 接口确保类型安全
   • 步骤数组和动态步骤更新
   • 在运行时访问和修改步骤

3. 数据组织： 步骤类型

   • 默认类型：带标签的图标
   • 仅标签类型：仅文本描述
   • 仅指示器类型：仅数字或图标
   • 标签位置（top、bottom、start、end）
   • 根据使用场景选择合适的类型

4. UI 布局： 方向与布局

   • 水平方向（默认，并排排列）
   • 垂直方向（堆叠排列，上下排列）
   • 响应式行为和方向切换
   • 特定布局的样式设置

5. 交互性： 事件与交互

   • stepChanged：步骤成功更改时触发
   • stepChanging：步骤更改前触发（可取消）
   • stepClick：用户点击步骤时触发
   • beforeStepRender：每个步骤渲染前触发
   • created：初始化完成时触发
   • 事件参数和模式

6. 增强功能： 模板与动画

   • 用于步骤内容的自定义 HTML 模板
   • 模板数据绑定
   • 动画设置和时间配置
   • 动画持续时间和延迟
   • 工具提示自定义

7. 生产环境： 验证与全球化

   • 表单验证模式
   • 强制线性工作流
   • 多语言支持
   • 从右到左（RTL）支持
   • 符合无障碍要求

8. 故障排除： 最佳实践

   • 常见问题和解决方案
   • 性能优化
   • CSS 自定义
   • 主题集成
   • 边缘情况

🔍 按主题快速导航

按功能：

• 📄 步骤配置 - 使用步骤
• 📄 步骤类型 - 显示选项
• 📄 方向 - 布局选项
• 📄 事件与交互 - 处理用户操作

按使用场景：

• 🧩 表单向导： 参阅事件与交互和验证
• 🛒 结账流程： 参阅步骤配置和事件
• 🎨 自定义样式： 参阅模板与动画和最佳实践
• 🌍 多语言： 参阅验证与全球化

按 API 查询：

• 🔗 完整 API 参考 - 所有属性、方法、事件和枚举

---

快速入门示例

下面是一个最简步骤条设置，帮助你立即开始：

import { Stepper } from '@syncfusion/ej2-navigations';

// Create a basic stepper with 4 steps
let stepper: Stepper = new Stepper({
  steps: [
    { label: 'Cart' },
    { label: 'Shipping' },
    { label: 'Payment' },
    { label: 'Confirmation' }
  ]
});

// Render to DOM
stepper.appendTo('#stepper');

<nav id="stepper"></nav>

---

常见模式

模式 1：图标 + 标签步骤（默认）

import { Stepper, StepModel } from '@syncfusion/ej2-navigations';

let steps: StepModel[] = [
  { iconCss: 'sf-icon-cart', label: 'Cart' },
  { iconCss: 'sf-icon-truck', label: 'Shipping' },
  { iconCss: 'sf-icon-payment', label: 'Payment' }
];

let stepper: Stepper = new Stepper({ steps: steps });
stepper.appendTo('#stepper');

模式 2：带事件的纵向工作流

import { Stepper } from '@syncfusion/ej2-navigations';

let stepper: Stepper = new Stepper({
  steps: [{}, {}, {}, {}],
  orientation: 'Vertical',
  stepChanged: (args) => console.log('Changed to step:', args.activeStep),
  stepChanging: (args) => {
    if (!validateCurrentStep()) args.cancel = true;
  }
});
stepper.appendTo('#stepper');

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

import { Stepper, StepperChangingEventArgs } from '@syncfusion/ej2-navigations';

let stepper: Stepper = new Stepper({
  steps: [
    { label: 'Personal Info' },
    { label: 'Address' },
    { label: 'Review' }
  ],
  linear: true,  // Must complete steps in order
  stepChanging: (args: StepperChangingEventArgs) => {
    // Validate current step before allowing transition
    if (!isCurrentStepValid()) {
      args.cancel = true;  // Prevent step change
    }
  }
});
stepper.appendTo('#stepper');

模式 4：动态步骤管理

import { Stepper } from '@syncfusion/ej2-navigations';

let stepper: Stepper = new Stepper({
  steps: [{}, {}, {}, {}],
  activeStep: 0
});
stepper.appendTo('#stepper');

// Navigate with methods
stepper.nextStep();      // Move to next step
stepper.previousStep();  // Move to previous step
stepper.reset();         // Return to first step

// Update properties
stepper.activeStep = 2;
stepper.dataBind();      // Apply changes

---

主要属性一览

步骤条控件属性

属性	类型	默认值	说明
steps	StepModel[]	[]	步骤定义数组
activeStep	number	0	当前激活的步骤（从零开始计数）
stepType	string	'Default'	类型：Default、Label 或 Indicator
orientation	string	'Horizontal'	布局：Horizontal 或 Vertical
labelPosition	string	'Bottom'	标签位置：Top、Bottom、Start、End
linear	boolean	false	强制按顺序导航
readOnly	boolean	false	禁用所有交互
showTooltip	boolean	false	在步骤上显示工具提示
animation	object	{...}	动画设置（启用、时长、延迟）
locale	string	'en-US'	语言/地区代码
enableRtl	boolean	false	启用从右到左的渲染
enablePersistence	boolean	false	将状态保存到 localStorage

步骤属性

属性	类型	默认值	说明
label	string	''	步骤标签文本
text	string	''	步骤说明
iconCss	string	''	步骤图标 CSS 类
status	string	'NotStarted'	NotStarted、InProgress、Completed
isValid	boolean | null	null	验证状态（true/false/null）
disabled	boolean	false	禁用此步骤
optional	boolean	false	步骤为可选项
cssClass	string	''	自定义 CSS 类

---

常见用例

结账向导： 分为购物车、配送、付款和确认步骤的多步购买流程。

表单向导： 将长表单拆分为多个步骤，并在每个阶段进行验证。

新手引导流程： 引导新用户完成设置步骤，并显示进度。

任务工作流： 跟踪一系列任务或里程碑的进度。

流程跟踪器： 显示当前在已记录流程中的位置。

多页调查： 将调查问题分布到多个步骤中，并跟踪进度。

---

API 参考快速链接

• 完整 API 文档
  • 步骤条属性（共 15 项）
  • 步骤条方法（共 12 项）
  • 步骤条事件（共 5 项）
  • 步骤属性（共 8 项）
  • 枚举（4 种）
  • 动画设置
  • 事件参数

---

🚀 准备好开始实现了吗？ 从入门指南开始，设置你的第一个步骤条；也可以直接查看 API 参考，了解完整文档。