syncfusion-aspnetcore-stepper

实现 ASP.NET Core Stepper 控件

Syncfusion ASP.NET Core Stepper 是一个导航组件，可在顺序工作流中引导用户完成一系列逻辑步骤。可将其用于向导、多步骤表单、结账流程，以及任何需要逐步推进的体验。

何时使用此技能

• 多步骤表单或向导 - 引导用户按顺序收集数据
• 结账流程 - 显示购物车 → 配送 → 付款 → 确认
• 进度跟踪 - 显示任务或流程的完成状态
• 线性工作流 - 强制按顺序推进步骤（例如，注册、入门引导）
• 状态可视化 - 显示哪些步骤已完成、正在进行或尚未开始
• 步骤验证 - 显示每个步骤的验证状态（成功/错误）

控件概览

主要功能：

• 支持自动或手动推进的顺序步骤导航
• 多种步骤显示类型（默认：指示器 + 标签、仅标签、仅指示器）
• 支持水平和垂直方向，适用于不同布局
• 步骤状态管理（NotStarted、InProgress、Completed）
• 使用成功/错误指示器进行步骤验证
• 线性模式，用于强制按顺序推进步骤
• 丰富的模板功能，可自定义步骤内容
• 支持步骤变更、验证和交互的事件
• 使用自定义模板的工具提示，提供额外指引
• 平滑过渡的动画效果
• 本地化和 RTL 支持

---

安装和设置

阅读： references/getting-started.md

• NuGet 包安装
• 在 _ViewImports.cshtml 中注册 TagHelper
• CDN 和 NPM 资源引入
• 基本项目设置

---

创建第一个 Stepper

快速入门示例 - 包含 4 个步骤的基本水平 Stepper：

<ejs-stepper id="stepper" activeStep="0">
    <e-stepper-steps>
        <e-stepper-step iconCss="sf-icon-cart" label="Shopping Cart" text="Review items"></e-stepper-step>
        <e-stepper-step iconCss="sf-icon-transport" label="Shipping" text="Enter address"></e-stepper-step>
        <e-stepper-step iconCss="sf-icon-payment" label="Payment" text="Select payment"></e-stepper-step>
        <e-stepper-step iconCss="sf-icon-success" label="Confirmation" text="Order complete"></e-stepper-step>
    </e-stepper-steps>
</ejs-stepper>

垂直 Stepper：

<ejs-stepper id="stepper" orientation="Vertical">
    <e-stepper-steps>
        <e-stepper-step iconCss="sf-icon-cart" label="Cart"></e-stepper-step>
        <e-stepper-step iconCss="sf-icon-transport" label="Shipping"></e-stepper-step>
        <e-stepper-step iconCss="sf-icon-payment" label="Payment"></e-stepper-step>
    </e-stepper-steps>
</ejs-stepper>

---

Stepper 属性

完整参考： references/stepper-properties-reference.md

Stepper 级别的主要属性（共 15 个）：

• activeStep - 当前步骤索引（从 0 开始）
• animation - 步骤过渡动画配置
• cssClass - 用于设置组件样式的 CSS 类
• enablePersistence - 在页面重新加载后保留状态
• enableRtl - 支持从右向左布局
• labelPosition - 标签位置（Top、Bottom、Start、End）
• linear - 仅按顺序推进模式
• locale - 本地化区域设置
• orientation - 水平或垂直布局
• readOnly - 禁用所有交互
• showTooltip - 悬停时显示工具提示
• stepType - 视觉样式（Default、Label、Indicator）
• steps - 步骤定义数组
• template - 自定义步骤内容模板
• tooltipTemplate - 自定义工具提示模板

---

步骤属性

完整参考： references/stepper-properties-reference.md

步骤级别的属性（共 8 个）：

• cssClass - 单个步骤的 CSS 类
• disabled - 禁用特定步骤
• iconCss - 图标 CSS 类
• isValid - 验证状态（true/false/null）
• label - 步骤标签文本
• optional - 将步骤标记为可选
• status - 步骤状态（NotStarted、InProgress、Completed）
• text - 步骤说明文本

---

动画属性

动画配置（3 个属性）：

• enable - 启用/禁用动画
• duration - 动画时长，单位为毫秒
• delay - 动画开始前的延迟

示例：

<ejs-stepper id="stepper">
    <e-stepper-animation enable="true" duration="1000" delay="500"></e-stepper-animation>
    <e-stepper-steps>
        <e-stepper-step label="Step 1"></e-stepper-step>
        <e-stepper-step label="Step 2"></e-stepper-step>
    </e-stepper-steps>
</ejs-stepper>

---

步进器方法

完整参考： references/stepper-methods-reference.md

可用方法（共 12 个）：

• nextStep() - 以编程方式转到下一步
• previousStep() - 转到上一步
• addEventListener(eventName, handler) - 添加事件侦听器
• removeEventListener(eventName, handler) - 移除事件侦听器
• dataBind() - 应用待处理的属性更改
• refresh() - 重新渲染组件
• refreshProgressbar() - 更新进度条位置
• reset() - 重置到第一步
• getRootElement() - 获取根 DOM 元素
• destroy() - 清理组件
• appendTo(selector) - 将组件附加到目标元素

---

事件和事件参数

完整参考： references/events-and-interactions.md

可用事件（共 5 个）：

created

步进器渲染完成后触发。

• 参数： 事件对象

stepChanged

活动步骤成功更改后触发。

• 参数： activeStep、element、event、isInteracted、name

stepChanging

活动步骤更改前触发（允许取消更改以进行验证）。

• 参数： activeStep、cancel、element、event、isInteracted

stepClick

用户点击某一步时触发。

• 参数： activeStep、previousStep、element、event、name

beforeStepRender

渲染每一步前触发（允许动态修改）。

• 参数： index、element、name

---

步骤类型和方向

阅读： references/step-types-and-styles.md

• 默认步骤类型（图标 + 标签）
• 仅标签步骤类型及标签位置（Top、Bottom、Start、End）
• 仅指示器步骤类型
• 水平方向（步骤并排显示）
• 垂直方向（步骤堆叠显示）
• 自定义视觉外观

---

步骤配置

阅读： references/steps-configuration.md

• 使用 iconCss 属性定义步骤图标
• 为步骤添加文本内容和标签
• 可选的步骤指示器
• 禁用步骤以阻止交互
• 使用 activeStep 属性设置活动步骤
• 步骤状态值（NotStarted、InProgress、Completed）
• 应用 CSS 类进行自定义样式设置
• 使用 isValid 属性验证步骤

---

事件和交互

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

• 步进器完成渲染时触发 created 事件
• 活动步骤更改后触发 stepChanged 事件
• 步骤更改前触发 stepChanging 事件（验证点）
• 用户点击某一步时触发 stepClick 事件
• 用于动态修改步骤的 beforeStepRender 事件
• 仅允许按顺序前进的线性导航模式
• 事件模式示例

---

模板和自定义

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

• 使用步骤模型上下文的自定义步骤模板
• 工具提示配置和显示
• 用于显示详细步骤信息的工具提示模板
• CSS 类自定义
• 用于样式设置的 CSS 属性
• 主题和外观自定义
• 通过持续时间和延迟设置动画效果

---

高级功能

阅读： references/advanced-features.md

• 动画配置（启用、持续时间、延迟）
• 仅允许按顺序前进的线性流程
• 本地化和区域设置自定义
• RTL（从右向左）布局支持
• 禁用所有交互的只读模式
• 无障碍注意事项
• 性能优化

---

步骤验证

阅读： references/steps-validation.md

• 步骤验证模式（isValid 属性）
• 使用 stepChanging 事件进行表单验证
• 使用 fetch API 的异步验证模式
• 根据用户输入进行实时验证
• 验证状态值（true/false/null）

---

常见模式

带线性导航的向导模式

对于需要按顺序完成步骤的表单，请启用线性模式：

<ejs-stepper id="wizard" linear="true">
    <e-stepper-steps>
        <e-stepper-step iconCss="sf-icon-cart" label="Cart"></e-stepper-step>
        <e-stepper-step iconCss="sf-icon-transport" label="Shipping"></e-stepper-step>
        <e-stepper-step iconCss="sf-icon-payment" label="Payment"></e-stepper-step>
    </e-stepper-steps>
</ejs-stepper>

步骤验证模式

使用 stepChanging 事件，在允许进入下一步之前验证表单内容：

<ejs-stepper id="wizard" linear="true" stepChanging="validateStep">
    <e-stepper-steps>
        <e-stepper-step iconCss="sf-icon-cart" label="Cart"></e-stepper-step>
        <e-stepper-step iconCss="sf-icon-transport" label="Shipping"></e-stepper-step>
        <e-stepper-step iconCss="sf-icon-payment" label="Payment"></e-stepper-step>
    </e-stepper-steps>
</ejs-stepper>

<script>
function validateStep(args) {
    var form = document.getElementById('stepForm');
    if (!form.checkValidity()) {
        args.cancel = true;  // Prevent step change
        alert('Please complete all required fields');
    }
}
</script>

动态内容模式

根据当前步骤加载并显示不同的内容：

<ejs-stepper id="stepper" activeStep="@Model.CurrentStep" stepChanged="onStepChanged">
    <e-stepper-steps>
        
    </e-stepper-steps>
</ejs-stepper>

<div id="content">
    
</div>

<script>
function onStepChanged(args) {
    loadContentForStep(args.activeStep);
}

function loadContentForStep(stepIndex) {
    // Load content via AJAX or from pre-loaded data
}
</script>

---

常见用例

1. 电商结账 - 购物车 → 地址 → 付款 → 确认
2. 用户注册 - 账户信息 → 邮箱验证 → 个人资料 → 完成
3. 应用向导 - 需求 → 配置 → 审核 → 部署
4. 引导流程 - 欢迎 → 个人资料 → 偏好设置 → 开始
5. 任务工作流 - 分析 → 规划 → 执行 → 审核
6. 多表单调查 - 人口统计信息 → 问题第 1 部分 → 问题第 2 部分 → 摘要