syncfusion-angular-stepper

Syncfusion Angular Stepper の実装

Syncfusion Angular Stepper コンポーネントは、ウィザード、オンボーディング、マルチステップフォームに最適な、段階的なプロセスやワークフローを表示します。このスキルでは、ステップの外観、検証、イベント、アニメーションを細かく制御しながら、Stepper コンポーネントを実装、設定、カスタマイズする方法を説明します。

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

次のような場合にこのスキルを使用します：

• 複数ステップのウィザードやワークフローを作成する
• 段階的なフォームやオンボーディングフローを作成する
• ステップの検証やリニアフローを設定する
• ステップにアイコン、ラベル、カスタムテンプレートを追加する
• ステップイベント（created、stepChanged、stepChanging、beforeStepRender、stepClick）を処理する
• アニメーションやスタイルでステップの外観をカスタマイズする
• ツールチップ、グローバリゼーション、RTL サポートを実装する

コンポーネントの概要

Stepper コンポーネントには、次の機能があります：

• 複数のステップタイプ：デフォルト（アイコン＋ラベル）、インジケーターのみ、ラベルのみ
• 2 種類の方向：水平（デフォルト）と垂直
• 豊富なイベントシステム：created、stepChanged、stepChanging、beforeStepRender、stepClick
• ステップの検証：リニアフロー、完了状態、条件付き進行
• カスタマイズ：アイコン、ラベル、テンプレート、アニメーション、ツールチップ
• アクセシビリティ：WCAG 準拠、キーボード操作、RTL サポート

目次

🚀 はじめに

📄 参照： references/getting-started.md

• インストールとパッケージの設定
• Angular CLI のセットアップと依存関係
• Angular スタンドアロンでの基本的な Stepper の実装
• CSS のインポートとテーマの設定
• 初回のレンダリングと初期設定

📋 API リファレンス

📄 参照： references/api-reference.md

• Stepper コンポーネントのプロパティ：activeStep、animation、cssClass、enablePersistence、enableRtl、labelPosition、linear、locale、orientation、readOnly、showTooltip、stepType、steps、template、tooltipTemplate
• Step モデルのプロパティ：cssClass、disabled、iconCss、isValid、label、optional、status、text
• アニメーション設定：enable、duration、delay
• Stepper メソッド：destroy()、nextStep()、previousStep()、refreshProgressbar()、reset()
• イベントの概要：created、stepChanged、stepChanging、stepClick、beforeStepRender
• 列挙型：StepType、StepStatus、StepLabelPosition、StepperOrientation

⚙️ ステップの設定

📄 参照： references/steps-configuration.md

• <e-step> ディレクティブでステップを追加する
• iconCss プロパティでアイコンを設定する
• ラベルとテキストコンテンツを設定する
• activeStep でアクティブなステップを設定する
• オプションのステップとステップの無効化
• ステップの読み取り専用モード
• ステップのステータス追跡
• isValid プロパティでステップを検証する
• ラベルの位置と配置

🎨 ステップタイプの選択

📄 参照： references/step-types.md

• インジケーターとラベルを表示するデフォルトタイプ
• コンパクトなレイアウト向けのインジケーターのみタイプ
• テキストベースのナビゲーション向けのラベルのみタイプ
• ラベルの位置（上、下、開始、終了）
• 各タイプの用途
• タイプ選択のパターン

📐 方向の設定

📄 参照： references/orientations-and-layouts.md

• 水平方向（デフォルト）
• 高さのあるレイアウト向けの垂直方向
• レイアウトの設定とレスポンシブデザイン
• ユースケースに応じた方向の選択

🎯 イベントとインタラクションの処理

📄 参照： references/events-and-interactions.md

• 初期化用の created イベント
• ステップ変更後の stepChanged イベント（EventArgs を含む）
• ステップ変更を防止する stepChanging イベント（EventArgs を含む）
• レンダリング前のカスタマイズ用 beforeStepRender イベント（EventArgs を含む）
• クリック処理用の stepClick イベント（EventArgs を含む）
• EventArgs の完全なリファレンスドキュメント
• イベントハンドラーのパターンとベストプラクティス

✅ 検証とフロー制御

📄 参照: references/validation-and-flow.md

• 順次進行のためのリニアフロー設定
• ステップの検証と完了状態
• ステップのステータス管理
• 条件付きステップ進行
• エラー処理と状態管理

🎭 テンプレートとスタイル設定

📄 参照: references/templates-and-customization.md

• <ng-template> を使用したカスタムステップテンプレート
• テンプレートのバインディングとデータコンテキスト
• CSS クラスのカスタマイズ（cssClass プロパティ）
• レイアウトと外観のカスタマイズ
• レスポンシブスタイルのパターン

🌟 高度な機能

📄 参照: references/advanced-features.md

• StepperAnimationSettingsModel によるアニメーション設定（duration、delay、enable）
• ツールチップの設定とツールチップテンプレート
• グローバル化とローカライズ（i18n）
• enableRtl による RTL（右から左）サポート
• アクセシビリティ機能とキーボードナビゲーション
• WCAG 準拠とスクリーンリーダーのサポート

クイックスタートの例

import { Component } from "@angular/core";
import { StepperAllModule, StepperModule } from "@syncfusion/ej2-angular-navigations";

@Component({
  imports: [ StepperAllModule, StepperModule ],
  standalone: true,
  selector: 'app-root',
  template: `
    <div class="stepper-container">
      <ejs-stepper>
        <e-steps>
          <e-step label="Cart" iconCss="sf-icon-cart"></e-step>
          <e-step label="Delivery Address" iconCss="sf-icon-transport"></e-step>
          <e-step label="Payment" iconCss="sf-icon-payment"></e-step>
          <e-step label="Confirmation" iconCss="sf-icon-success"></e-step>
        </e-steps>
      </ejs-stepper>
    </div>
  `,
  styles: [`
    .stepper-container {
      padding: 20px;
      max-width: 800px;
      margin: 0 auto;
    }
  `]
})
export class AppComponent { }

よく使われるパターン

パターン 1：フォーム検証付きウィザード

<ejs-stepper (stepChanging)="onStepChanging($event)">
  <e-steps>
    <e-step label="Personal Info"></e-step>
    <e-step label="Contact Details"></e-step>
    <e-step label="Address"></e-step>
    <e-step label="Confirmation"></e-step>
  </e-steps>
</ejs-stepper>

ステップの進行を許可する前にフォームデータを検証するには、stepChanging イベントを使用します。

パターン 2：動的なステップアイコン

<ejs-stepper>
  <e-steps>
    <e-step *ngFor="let step of steps" 
            [label]="step.label" 
            [iconCss]="step.icon"></e-step>
  </e-steps>
</ejs-stepper>

*ngFor ディレクティブを使用して、ステップデータを動的にバインドします。

パターン 3：リニアワークフロー

<ejs-stepper [linear]="true">
  <e-steps>
    <e-step label="Step 1"></e-step>
    <e-step label="Step 2"></e-step>
    <e-step label="Step 3"></e-step>
  </e-steps>
</ejs-stepper>

順次進行を強制するには、linear プロパティを有効にします。

パターン 4：イベント処理

onStepChanged(args: StepperChangedEventArgs) {
  console.log(`Active step index: ${args.activeStep}`);
}

onStepChanging(args: StepperChangingEventArgs) {
  if (!isFormValid()) {
    args.cancel = true; // Prevent step change
  }
}

イベントハンドラーを使用して、ナビゲーションを追跡し、進行状況を検証します。

主なプロパティの概要

プロパティ	型	デフォルト	使用する場面
stepType	StepType	Default	表示スタイルを変更：Default、Indicator、Label
orientation	Orientation	Horizontal	レイアウトを設定：Horizontal または Vertical
linear	boolean	false	順次進行を強制
activeStep	number	0	現在のアクティブなステップを設定（0 始まり）
animation	StepperAnimationSettingsModel	enabled	トランジションアニメーションを設定
showTooltip	boolean	false	ステップにカーソルを合わせたときにツールチップを表示
labelPosition	string	Bottom	ラベルの位置を設定：Top、Bottom、Start、End
readOnly	boolean	false	すべてのステップ操作を無効化
cssClass	string	-	カスタム CSS クラスを適用
enableRtl	boolean	false	アラビア語、ヘブライ語、ウルドゥー語向けに RTL を有効化
enablePersistence	boolean	false	ページの再読み込み後も状態を保持
locale	string	en-US	言語／地域設定を指定

コード例を含む完全な API リファレンスについては、こちらを参照してください： 📚 API リファレンス

よくあるユースケース

ウィザードフォーム：各ステップで検証を行う複数ステップのフォームウィザードを実装します
オンボーディングフロー：新しいユーザーをセットアップや紹介の各ステップに沿って案内します
プロセスの追跡：ワークフローの進行状況（注文処理、求人応募など）を表示します
複数ステップのチェックアウト：住所や支払いのステップを含むショッピングカートのワークフローを作成します
セットアップアシスタント：ガイド付きの手順でツールやサービスを設定します
ドキュメントの提出：検証を伴う複数ステップのドキュメントアップロードを実装します

---

次のステップ： 実装したい内容に応じて、上記のリファレンスを選択してください。Stepper コンポーネントを初めて使用する場合は、getting-started.md から始めてください。