syncfusion-react-stepper

实现 Syncfusion React Stepper

Stepper 组件通过可视化指示器、步骤标签和灵活配置，引导用户完成多步骤工作流或流程。它非常适用于向导、结账流程、引导流程，以及任何需要按顺序导航的引导式用户体验。

何时使用此技能

在以下情况需要使用 Stepper 组件：

• 引导用户完成多步骤流程（结账、注册、设置向导）
• 显示带进度指示的分步工作流
• 在进入下一步之前验证用户输入
• 支持线性或非线性导航模式
• 使用图标、标签和模板自定义外观
• 为不同语言或地区本地化内容

组件概览

主要功能：

• 步骤导航： 支持水平和垂直方向，以及顺序导航或自由导航
• 步骤类型： 默认模式（图标 + 标签）、仅标签模式或仅指示器模式
• 事件： 跟踪步骤变更、验证和交互
• 样式： 动画、模板、自定义 CSS 和工具提示
• 无障碍性： 完整的键盘导航和 ARIA 支持
• 全球化： 多语言支持和 RTL 兼容性

文档与导航指南

开始使用与安装

📄 阅读： references/getting-started.md

• 安装程序包和依赖项
• 导入 CSS 并设置主题
• 创建首个 Stepper
• 初始配置和渲染

核心配置：步骤和属性

📄 阅读： references/steps-and-configuration.md

• 使用 StepDirective 添加和定义步骤
• 图标 CSS、文本和标签属性
• 管理当前活动步骤
• 禁用状态和自定义
• 配置 CSS 类

布局与外观：方向和类型

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

• 水平和垂直方向
• 步骤类型模式（Default、Label、Indicator）
• 标签位置（Top、Bottom、Start、End）
• RTL 支持和响应式设计

交互与行为：事件

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

• 生命周期事件：created、stepChanged、stepChanging
• 用户交互事件：stepClick、beforeStepRender
• 事件参数和处理模式
• 防止不需要的状态转换

工作流控制：线性流程和验证

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

• 配置线性 Stepper 以实现顺序导航
• 步骤验证和状态管理
• 防止无效状态转换
• 重置 Stepper 状态

高级样式与自定义

📄 阅读： references/animation-template-tooltip.md

• 动画配置和时长
• 自定义步骤模板
• 集成和显示工具提示
• 渲染自定义内容

方法和高级模式

📄 阅读： references/methods-and-advanced.md

• 组件方法（reset 等）
• 两种 API 模式（基于组件与基于属性）
• 高级用例和模式
• 性能优化提示

最佳实践：无障碍性与本地化

📄 阅读： references/accessibility-globalization.md

• 符合 WCAG 标准并使用 ARIA 属性
• 键盘导航指南
• 全球化和本地化
• RTL 支持实现

快速入门示例

模式 1：基于组件（StepsDirective）

import React from 'react';
import { StepperComponent, StepsDirective, StepDirective } from '@syncfusion/ej2-react-navigations';
import '@syncfusion/ej2-base/styles/tailwind3.css';
import '@syncfusion/ej2-navigations/styles/tailwind3.css';

function App() {
  return (
    <div>
      <StepperComponent>
        <StepsDirective>
          <StepDirective iconCss="sf-icon-cart" label="Cart" />
          <StepDirective iconCss="sf-icon-transport" label="Delivery" />
          <StepDirective iconCss="sf-icon-payment" label="Payment" />
          <StepDirective iconCss="sf-icon-success" label="Confirmation" />
        </StepsDirective>
      </StepperComponent>
    </div>
  );
}

export default App;

模式 2：基于属性（steps 数组）

import React from 'react';
import { StepperComponent } from '@syncfusion/ej2-react-navigations';
import '@syncfusion/ej2-base/styles/tailwind3.css';
import '@syncfusion/ej2-navigations/styles/tailwind3.css';

function App() {
  const steps = [
    { iconCss: 'sf-icon-cart', label: 'Cart' },
    { iconCss: 'sf-icon-transport', label: 'Delivery' },
    { iconCss: 'sf-icon-payment', label: 'Payment' },
    { iconCss: 'sf-icon-success', label: 'Confirmation' }
  ];

  return (
    <div>
      <StepperComponent steps={steps} />
    </div>
  );
}

export default App;

常见模式

模式 1：带验证的向导

const [activeStep, setActiveStep] = React.useState(0);
const stepperRef = React.useRef(null);

const handleStepChanging = (args) => {
  // Validate current step before advancing
  if (!validateStep(activeStep)) {
    args.cancel = true; // Prevent transition
  }
};

<StepperComponent 
  ref={stepperRef}
  stepChanging={handleStepChanging}
>
  {/* steps */}
</StepperComponent>

模式 2：线性与非线性导航

// Linear: Users must complete steps sequentially
<StepperComponent linear={true}>

// Non-linear: Users can skip to any step
<StepperComponent linear={false}>

模式 3：响应式方向

// Auto-switch orientation based on screen size
const [orientation, setOrientation] = React.useState('horizontal');

React.useEffect(() => {
  const handleResize = () => {
    setOrientation(window.innerWidth < 768 ? 'vertical' : 'horizontal');
  };
  window.addEventListener('resize', handleResize);
  return () => window.removeEventListener('resize', handleResize);
}, []);

<StepperComponent orientation={orientation}>

主要属性和配置

组件属性

属性	类型	默认值	用途
activeStep	number	0	当前激活步骤的索引
animation	StepperAnimationSettingsModel	undefined	动画配置（启用、时长、延迟）
cssClass	string	''	用于自定义样式的 CSS 类
enablePersistence	boolean	false	页面重新加载时保留组件状态
enableRtl	boolean	false	启用从右到左的布局
labelPosition	string	'Bottom'	标签位置：'Top'、'Bottom'、'Start'、'End'
linear	boolean	false	强制按顺序导航步骤
locale	string	'en-US'	本地化区域性代码
orientation	string	'horizontal'	布局方向：'horizontal' 或 'vertical'
readOnly	boolean	false	禁止用户交互
showTooltip	boolean	true	悬停时显示工具提示
stepType	string	'Default'	视觉模式：'Default'、'Label'、'Indicator'
steps	StepModel[]	[]	步骤对象数组（基于属性的模式）
template	string | function	undefined	步骤的自定义模板
tooltipTemplate	string | function	undefined	工具提示的自定义模板

步骤属性（StepModel）

属性	类型	用途
cssClass	string	用于单个步骤样式设置的 CSS 类
disabled	boolean	禁用该步骤
iconCss	string	步骤的图标 CSS 类
isValid	boolean	步骤的验证状态
label	string	步骤标签文本
optional	boolean	将步骤标记为可选
status	string	步骤状态：'NotStarted'、'InProgress'、'Completed'
text	string	文本内容（通常为数字）

动画设置

属性	类型	默认值	用途
enable	boolean	true	启用动画
duration	number	400	动画时长，单位为毫秒
delay	number	0	动画开始前的延迟

事件

事件	触发时机	用途	参数
created	组件初始化后	设置、初始化	Event
stepChanged	步骤更改后	更新 UI、加载内容	StepperChangedEventArgs
stepChanging	步骤更改前	验证、阻止切换	StepperChangingEventArgs
stepClick	用户点击步骤时	跟踪交互	StepperClickEventArgs
beforeStepRender	渲染每个步骤前	自定义步骤外观	StepperRenderingEventArgs

方法

方法	参数	返回值	用途
reset()	无	void	将步骤导航器重置为初始状态（activeStep: 0）
nextStep()	无	void	以编程方式移至下一步
previousStep()	无	void	以编程方式移至上一步
refreshProgressbar()	无	void	容器大小调整时刷新进度条
destroy()	无	void	销毁组件并释放资源

事件参数参考：

• StepperChangedEventArgs： activeStep、previousStep、isInteracted、name、event、element
• StepperChangingEventArgs： activeStep、previousStep、cancel、isInteracted、name、event、element
• StepperClickEventArgs： activeStep、name、event、element
• StepperRenderingEventArgs： activeStep、name、element

常见用例

• 电子商务结账： 包含订单审核、配送和付款的多步骤结账流程
• 用户注册： 包含邮箱、个人资料和验证的多步骤注册流程
• 设置向导： 通过配置步骤引导用户熟悉软件
• 调查表单： 带有进度提示的分步问卷
• 安装指南： 包含说明和验证的安装步骤