syncfusion-javascript-stepper

Syncfusion TypeScript Stepper Control の実装

目次

1. はじめに

• はじめに
• インストールとセットアップ
• 最初の Stepper
• CSS テーマ

2. API リファレンス

• API リファレンス全文
  • Stepper のプロパティ（15 個のプロパティ）
  • Stepper のメソッド（12 個のメソッド）
  • Stepper のイベント（5 個のイベント）
  • Step のプロパティ（8 個のプロパティ）
  • 列挙型と型（4 個の列挙型）
  • アニメーション設定（3 個のプロパティ）
  • イベント引数（4 個の引数インターフェイス）

3. 基本概念

• Steps の設定

  • Steps の追加と管理
  • Step のプロパティ（label、iconCss、text、disabled、optional、status、isValid）
  • Steps の無効化
  • 読み取り専用モードの設定
  • アクティブな Step の設定
  • アイコンのみ、ラベルのみ、アイコンとラベルを組み合わせた Step
  • 検証状態

• Step の種類

  • デフォルトの種類（アイコン＋ラベル）
  • ラベルのみの種類
  • インジケーターのみの種類
  • ラベルの位置（上、下、左、右）
  • 種類の比較と選択
  • 種類の動的な切り替え

• 向きとレイアウト

  • 水平方向（デフォルト）
  • 垂直方向
  • レスポンシブ動作
  • レイアウトの動的な切り替え
  • レイアウト固有のスタイル設定

4. 高度な機能

• イベントと操作

  • 5 つすべてのイベント：
    • created
    • beforeStepRender
    • stepClick
    • stepChanging（キャンセル可能）
    • stepChanged
  • イベント引数とプロパティ
  • イベント処理のパターン
  • イベントを使った検証
  • ユーザー操作の検出

• テンプレートとアニメーション

  • カスタム Step テンプレート
  • テンプレートのコンテキスト変数
  • テンプレートのデータバインディング
  • ツールチップのカスタマイズ
  • アニメーションの設定
  • アニメーションの時間と遅延
  • アニメーションの有効化／無効化

• 検証とグローバリゼーション

  • Step の検証（isValid の状態）
  • 線形フローの強制
  • 無効な遷移の防止
  • ローカライズ（L10n、Locale）
  • 右から左（RTL）への表示のサポート
  • 多言語サポート
  • アクセシビリティ（ARIA、キーボード操作）

5. ユーティリティとパターン

• トラブルシューティングとベストプラクティス
  • よくあるセットアップの問題
  • イベント処理のベストプラクティス
  • フォーム検証のパターン
  • CSS のカスタマイズ
  • テーマの統合
  • パフォーマンスの最適化
  • エッジケースと解決策

---

このスキルを使用する場面

次のような場合は、Syncfusion TypeScript Stepper スキルを使用してください。

• 複数ステップのプロセスやウィザード形式のワークフローを表示する
• 完了状況を示す進行状況インジケーターを作成する
• ステップ間の検証機能を備えたフォームウィザードを構築する
• 段階的なガイド付き操作（購入手続き、オンボーディング、セットアップ）を表示する
• 戻る／進む操作によるステップナビゲーションを追加する
• 線形ワークフローの検証を実装する
• 追跡機能を備えたチェックポイントベースのプロセスを作成する
• アイコン、ラベル、テンプレートを使ったステップのカスタマイズを可能にする
• ステップのイベントとユーザー操作を処理する
• 複数の方向（水平／垂直レイアウト）に対応する

Stepper の概要

Stepper は、ワークフローの進行をユーザーに案内するため、一連の論理的なステップを表示するナビゲーションコントロールです。各 Step には、次の要素を設定できます。

• インジケーター（番号、アイコン、図形）
• ラベル（テキストによる説明）
• 状態の追跡（アクティブ、完了、無効）
• ステップ遷移用のイベントハンドラー
• リッチコンテンツ用のカスタムテンプレート
• テーマによる柔軟なスタイル設定

主な特長

項目	説明
コンポーネント	複数ステップのワークフロー向けナビゲーションコントロール
ステップ	プロパティを持つステップオブジェクトの配列
インジケーター	番号またはアイコンベースのステップマーカー
向き	水平（デフォルト）または垂直のレイアウト
種類	デフォルト（アイコン＋ラベル）、ラベルのみ、インジケーターのみ
イベント	created、beforeStepRender、stepClick、stepChanging、stepChanged
メソッド	12 個の制御メソッド（nextStep、previousStep、reset など）
プロパティ	ステッパーのプロパティ 15 個 ＋ ステップのプロパティ 8 個
カスタマイズ	テンプレート、アニメーション、テーマ、CSS スタイリング

---

ドキュメントとナビゲーションガイド

📚 学習パス（推奨順）

1. まずはこちら： はじめに

   • インストールと npm パッケージのセットアップ
   • 依存関係（ej2-navigations、ej2-base、ej2-popups）
   • 開発環境の設定
   • コード例を使った基本的なステッパーの初期化
   • CSS のインポートとテーマのセットアップ

2. 基礎： ステップの設定

   • ステッパーへのステップの追加
   • ステップのプロパティ（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 リファレンスをご覧ください。