メインコンテンツまでスキップ

Step

Step は、明確な順序を持つ長いタスクを複数の段階に分割します。各ステップにはタイトル、状態、独自のコンテンツ領域があり、Form、入力、説明、操作ボタンを配置できます。

このガイドでは、次の設定方法を説明します。

  • Step コンテナと複数の StepItem を追加する
  • 横方向、縦方向、ナビゲーション、コンパクト表示を設定する
  • 既定の番号と自動状態アイコンを使う、または一貫した業務アイコンを設定する
  • 各ステップにフォームとボタンを配置する
  • コンポーネント関数で次へ、戻る、ジャンプ、リセットを実行する
  • 切り替え前に Form を検証し、onChange で現在のステップを読み取る

Step、Tab、Progress の役割は異なります。Step は順番に完了すべきタスク、Tab は同じ対象に関する並列コンテンツ、Progress は各段階のページ内容を持たない進捗率の表示に使用します。

1. サンプル：キャンペーン公開ウィザード​

Spark Sample の Step ページは、4 段階のキャンペーン公開ウィザードです。

ステップ内容主なポイント
Campaign detailsキャンペーン名、担当者、公開日、概要2 列 Form、必須検証、全行 TextArea
Audience & budget対象者、チャネル、予算、コンバージョン目標Back、Next、数値フィールド
Review前 2 ステップの読み取り専用サマリーステップ間で共有するページ状態と送信通知
Submittedキャンペーン番号と完了メッセージ完了状態とウィザードのリセット

このサンプルはバックエンド API に依存しません。ボタンは Step のコンポーネント API でステップを切り替えるため、構造と Interaction を直接確認できます。実データを送信する場合は、Review のボタン Interaction に Send Request を追加します。

2. Step コンテナを追加する​

  1. 対象ページを Page Designer で開きます。
  2. コンポーネントパレットの Containers を展開します。
  3. Step を Screen またはコンテナを受け入れる領域へドラッグします。
  4. Step を選択し、Steps に StepItem を追加します。
  5. 各 StepItem を選択し、Title を入力します。
  6. StepItem のコンテンツ領域に Form、Panel、入力を追加します。

Step と StepItem は 2 階層です。

Step
├── Campaign details
│   └── Form + Next button
├── Audience & budget
│   └── Form + Back / Next buttons
├── Review
│   └── Read-only Form + Back / Submit buttons
└── Submitted
    └── Result Form + Reset button

子要素リストはドラッグで並べ替えられます。StepItem の順序を変えると、番号と前後移動の順序も変わります。

3. Step コンテナを設定する​

外側の Step では次を設定できます。

プロパティ値説明
Initial Step1 から始まる整数初回表示するステップ。範囲外の値は先頭または末尾に補正
Directionhorizontal、verticalステップヘッダーを横または縦に配置
Step Styledefault、navigation、inline標準、ナビゲーション、コンパクトなインライン表示
Marker Sizesmall、medium、large全ステップの番号またはアイコンの大きさ。既定は Medium
Label Placementhorizontal、verticalタイトルをアイコンの右または下に配置
Progress Dotsオン / オフ番号やアイコンを点に置換。オンではタイトルを縦配置
Allow Step Clickオン / オフ利用者がヘッダーをクリックして切り替えられるか
Show Step Contentオン / オフ現在の StepItem のコンテンツを表示するか
Responsiveオン / オフ狭い画面で読みやすい縦レイアウトへ切り替えるか
Current Step Statusprocess、wait、finish、error現在ステップの既定状態
Current Step Progress0～100現在ステップ内の任意進捗。主に Default + Process で使用

3.1 Step Style​

  • Default：標準的なフォームウィザード向けで、状態と順序が最も明確です。
  • Navigation：ヘッダーをプロセスナビゲーションとして見せ、入力済みステップへ戻れるフローに適します。
  • Inline：短いタイトルと限られたスペース向けです。Vertical Direction では読みにくい組み合わせを避けるため Default を使用します。

順番どおりの完了が必須なら Allow Step Click をオフにし、コンテンツ領域の Back、Next、Submit だけを使用します。

4. StepItem を設定する​

プロパティ説明
Title必須の主タイトル。2～5 語を推奨
Subtitle段階名、所要時間、担当者などの補助情報
Description現在ステップの短い説明
Statusauto、wait、process、finish、error
Disabledクリックおよびコンポーネント関数での移動を禁止
Icon任意。共通 Icon 選択器で前景色/背景色付きシステムアイコンを選ぶか、画像をアップロード

Status が auto の場合、現在位置から自動判定します。前のステップは Finish、後のステップは Wait、現在項目は Step の Current Step Status を使用します。継続的なエラー、待機、特別な完了状態を示す場合だけ上書きします。

4.1 番号、状態、業務アイコン​

Icon を設定しない場合は 1、2、3… を表示します。フォームウィザードや承認フローではこの方式を推奨します。完了後は番号が自動的にチェックへ変わり、現在、待機、エラーも自動的に適切な色とマーカーで表示されます。

User、Document、Payment、Review、Send、Milestone など、業務段階の識別に明確に役立つ場合だけ Icon を設定します。グループ全体で統一し、番号とアイコンを混在させないでください。Icon 選択器では検索、選択プレビュー、前景色、背景色、背景なしを利用でき、プロパティパネルには現在のアイコン名と識別子が表示されます。

Marker Size は外側の Step で一括管理します。異なるサイズの画像をアップロードして単一ステップを強調しないでください。

デザイナーで別のステップを編集する​

Design Mode ではステップバーの番号またはタイトルをクリックして編集対象を切り替えます。下のコンテンツ領域と右側のプロパティパネルは、その StepItem の Form、Panel、入力、ボタンへ同期します。

Allow Step Click と StepItem の Disabled は保存後の実行動作を制御し、デザイナーでの編集を妨げません。ページ構造の Steps → StepItem → Form を展開して、後続ステップの Form やフィールドを直接選択することもできます。

Disabled は条件がまだ満たされていないステップに使用します。Next と Previous は自動的にスキップします。現在の利用者にまったく適用されない場合は、Disabled ではなく共通表示条件で非表示にします。

5. ステップ内に Form を構成する​

StepItem に Form を追加してから、フィールドと ButtonSet を配置します。

  1. Form で Controls Per Row、Layout、Label Alignment、ラベル/内容比率を一括管理します。
  2. フィールド検証は Form が担当し、Step はフロー切り替えだけを担当します。
  3. 各中間ステップに明確な Next を置き、2 番目以降には Back も置きます。
  4. 最後の業務ステップを Review と Submit にし、送信後は独立した結果ステップへ進みます。

サンプルは Controls Per Row = 2、Label 4 / Content 8 を使用します。Campaign summary は Display Full Row を有効にしても Label が 4 列を占め、Launch date と揃います。Content は行の残り幅を自動的に使用します。

複数ステップで同じ値を読む場合は同じフィールド Name を使用します。編集フィールドと Review の読み取り専用フィールドを campaignName にすると、最初のステップで入力した最新値を表示できます。

6. 次へ、戻る、リセットを設定する​

関数パラメーター動作
nextStepなしDisabled をスキップして次の利用可能なステップへ進む
previousStepなしDisabled をスキップして前の利用可能なステップへ戻る
goToStepstepNumber指定ステップへ移動。番号は 1 から開始
resetStepsなしInitial Step へ戻る

最初の Next ボタンでは次の順に設定します。

  1. ボタンを選択し Interaction を開きます。
  2. onClick の先頭に Trigger Form Validation を追加し、Form に campaign_details_form を指定します。
  3. Component API アクションを追加します。
  4. Target Component に campaign_steps を選択します。
  5. Function に nextStep を選択します。

アクションは上から順に実行されます。検証に失敗すると nextStep は実行されず、成功した場合だけ次へ進みます。Back は previousStep、完了ページの “Create another campaign” は resetSteps を呼び出します。

7. ステップ切り替え Interaction​

Step には 2 層の Interaction があります。

  1. 外側 Step の onChange
  2. 個別 StepItem の onClick

切り替え前に対象ステップが step コンテキストへ書き込まれます。

step.id
step.index
step.number
step.previousIndex
step.previousNumber
step.name
step.description
step.status

index は式計算用に 0 から、number はパネルと利用者表示に合わせて 1 から始まります。

利用者がヘッダーをクリックすると StepItem の onClick が先に実行され、実際の変更後に外側 Step の onChange が実行されます。Next、Previous、Go to、Reset による切り替えでは外側 onChange だけが実行されます。Disabled ステップは切り替わらず、Interaction も実行しません。

Step の onChange に次の Toast を追加できます。

Now viewing step [[step.number]]: [[step.name]]

8. シナリオ 1：バックエンド検証に失敗したら現在のステップに留まる​

Step Validation Gate は 2 ステップのサンプルです。初期値 TRY-AGAIN はバックエンドで拒否され、ステップ 1 のままになります。APPROVE-2026 に修正すると成功し、その後にだけステップ 2 へ進みます。

  1. Submit request と Accepted を作成し、Initial Step を 1、Allow Step Click をオフにします。
  2. validation_gate_form に requestTitle と approvalCode を追加します。
  3. Submit and continue の先頭に Submit Form を置き、Custom URL に /spark/api/sample/step/validation-gate を設定します。
  4. その後に validation_gate_steps.nextStep を追加します。

HTTP エラーまたは success: false でアクションチェーンが中断されるため、nextStep は実行されません。送信より前にステップを切り替えないでください。

if (!StringUtils.equals("APPROVE-2026", StringUtils.trim(request.getApprovalCode()))) {
    throw new LatticeRuntimeException(Message.code("SPARK-SAMPLE-STEP-0003"));
}

完全な実装は StepWorkflowSampleController、StepWorkflowSampleService、step-validation-gate-page.json にあります。

9. シナリオ 2：バックエンド状態から現在の担当者のステップを開く​

Step Handoff は 2 人の順次処理を表します。Avery Chen がステップ 1 を完了し、Morgan Lee がステップ 2 を担当します。Page onLoad がワークフロー状態を読み、ページをステップ 2 で開きます。Allow Step Click をオンにすることで、読み取り専用のステップ 1 へ戻って確認できます。

  1. Requester submission と Manager review を作成します。Initial Step は安全なフォールバックとして 1 のままにし、Allow Step Click をオン、完了済みの最初の Form を読み取り専用にします。
  2. Page onLoad で caseId=CAM-2048 を付けて GET /spark/api/sample/step/handoff/status を送ります。
  3. activeStep を workflow.activeStep にバインドします。
  4. 続いて handoff_steps.goToStep を追加し、stepNumber を workflow.activeStep にバインドします。
Page onLoad
├── Send Request: GET /spark/api/sample/step/handoff/status
│   └── activeStep → workflow.activeStep
└── handoff_steps.goToStep([[workflow.activeStep]])

onLoad が完了するまでローディング状態を維持するため、ステップ 1 から 2 へのちらつきがありません。失敗時は Initial Step を維持します。バックエンドはログインユーザーの状態と権限を判定してください。activeStep は表示位置であり、認可情報ではありません。

10. バックエンドへ送信する​

実業務では Review の Submit ボタンを次の順に設定します。

  1. Trigger Form Validation
  2. Send Request または Submit Form
  3. 成功 Toast
  4. nextStep で完了ページへ進む

ページリクエストには現在の環境とレンダリングモードが自動的に付与されます。Step ごとに Header を追加する必要はありません。詳細はページリクエストコンテキストとバックエンドデバッグを参照してください。

Send Request が失敗した場合は後続アクションを停止し、現在ステップに留めて再試行できるようにします。結果を待たずに完了ページへ進まないでください。

11. Spark Sample を再現する​

  1. Step を追加し、Horizontal、Default、Vertical Label、Responsive、Allow Step Click を設定します。
  2. Marker Size を Medium にし、既定番号を使用します。
  3. Campaign details、Audience & budget、Review、Submitted の 4 StepItem を Icon なしで追加します。
  4. 最初の 3 ステップに 2 列 Horizontal Form、最後に 1 列の読み取り専用 Form を追加します。
  5. 最初の 2 つの Next は Form 検証後に nextStep を呼び出します。
  6. 2、3 番目の Back は previousStep を呼び出します。
  7. Review の Submit は成功 Toast の後に nextStep を呼び出します。
  8. Submitted のリセットは resetSteps を呼び出します。
  9. 保存し、Preview と実行時でフロー全体を確認します。

高度な 2 つのシナリオは step-validation-gate-page.json と step-handoff-page.json を参照してください。

12. トラブルシューティング​

12.1 Next をクリックしても変わらない​

  • Target Component が外側 Step か確認します。
  • Function が nextStep か確認します。
  • 後続がすべて Disabled または非表示でないか確認します。
  • Trigger Form Validation が空の必須項目で停止していないか確認します。
  • ページが保存済みで、実行時が現在の versionId を使用しているか確認します。

12.2 ヘッダーをクリックしても変わらない​

Allow Step Click がオンで、対象 StepItem が Disabled でないことを確認します。直接クリックを無効にした管理フローでは、コンテンツ領域のボタンを使用します。

12.3 Review に前の入力値が表示されない​

編集フィールドと Review の読み取り専用フィールドに同じ安定した Name を使用します。Display Name は表示タイトルだけを変更し、ページ状態を共有しません。

12.4 状態が想定と異なる​

通常は StepItem Status を auto にします。手動の Finish や Error は自動判定を上書きします。Auto に戻すと現在ステップへ追従します。

12.5 バックエンドが返したステップでページが開かない​

Page onLoad、workflow.activeStep へのレスポンスバインド、goToStep.stepNumber、および 1 始まりの整数値を確認してください。Send Request の失敗時は意図的にジャンプを中断します。

12.6 モバイルでステップが詰まる​

Responsive をオンにし、長い Title、Subtitle、Description を避けます。それでも読みにくい場合は Vertical Direction にするか表示テキストを減らします。

13. 設計上の推奨事項​

  • 1 つのウィザードは 3～7 ステップにします。7 を超える場合はページやグループを分けます。
  • Details、Audience、Review のような結果または業務段階をタイトルにし、長文を避けます。
  • Next は “Next: Review” のように遷移先を示すと “Continue” より理解しやすくなります。
  • スキップ不可なら Allow Step Click をオフにし、検証成功後だけ進めます。
  • 送信前に Review、送信後に独立した完了ページを用意し、短い Toast だけに依存しません。
  • Error、Disabled、完了状態には色だけでなく読める説明を付けます。
に最終更新