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 など）
• 2 つの 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}>

主な Props と設定

コンポーネントのプロパティ

Prop	Type	Default	Purpose
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）

Property	Type	Purpose
cssClass	string	個々のステップのスタイル設定用 CSS クラス
disabled	boolean	ステップを無効にします
iconCss	string	ステップのアイコン用 CSS クラス
isValid	boolean	ステップの検証状態
label	string	ステップのラベルテキスト
optional	boolean	ステップを任意としてマークします
status	string	ステップの状態：'NotStarted'、'InProgress'、'Completed'
text	string	テキスト内容（通常は数値）

アニメーションの設定

Property	Type	Default	Purpose
enable	boolean	true	アニメーションを有効にします
duration	number	400	アニメーションの期間（ミリ秒）
delay	number	0	アニメーション開始前の遅延時間

イベント

Event	Fires	Use For	Arguments
created	コンポーネントの初期化後	セットアップ、初期化	Event
stepChanged	ステップの変更後	UI の更新、コンテンツの読み込み	StepperChangedEventArgs
stepChanging	ステップの変更前	検証、遷移の防止	StepperChangingEventArgs
stepClick	ユーザーがステップをクリックしたとき	操作の追跡	StepperClickEventArgs
beforeStepRender	各ステップの描画前	ステップの外観のカスタマイズ	StepperRenderingEventArgs

メソッド

Method	Parameters	Returns	Purpose
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

よくあるユースケース

• E コマースのチェックアウト： 注文確認、配送、支払いを含む複数ステップのチェックアウトフロー
• ユーザー登録： メールアドレス、プロフィール、確認を含む複数ステップの登録
• セットアップウィザード： 設定手順を含むソフトウェアのオンボーディング
• アンケートフォーム： 進行状況を示す、ステップごとに進む質問票
• インストールガイド： 手順と検証を含むインストールの各ステップ