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>

---

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

Stepper のレンダリング完了後に発生します。

• 引数： イベントオブジェクト

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

• Stepper のレンダリング完了時に発生する 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. Eコマースのチェックアウト - カート → 住所 → 支払い → 確認
2. ユーザー登録 - アカウント情報 → メール認証 → プロフィール → 完了
3. アプリケーションウィザード - 要件 → 設定 → レビュー → デプロイ
4. オンボーディングフロー - ようこそ → プロフィール → 設定 → 開始
5. タスクワークフロー - 分析 → 計画 → 実行 → レビュー
6. 複数フォームのアンケート - 属性情報 → 質問その1 → 質問その2 → 概要