Step

Step 用於把較長且具有明確先後順序的任務拆成多個階段。每個步驟都有標題、狀態和自己的內容區，可放置 Form、輸入元件、說明與操作按鈕。

閱讀本手冊後，你可以完成以下設定：

• 新增 Step 容器和多個 StepItem
• 設定橫向、縱向、導覽和緊湊外觀
• 使用預設編號與自動狀態圖示，或依需要設定一致的業務圖示
• 在每個步驟中組合表單與按鈕
• 使用元件介面完成下一步、上一步、跳轉和重設
• 切換前驗證表單，並在 onChange 中讀取目前步驟

Step、Tab 和 Progress 用途不同。Step 表達必須或建議依序完成的任務；Tab 表達同一物件下的並列內容；Progress 只顯示完成比例，不承載每一步的頁面內容。

1. 範例：活動發佈精靈

Spark Sample 的 Step 頁面使用四步活動發佈精靈：

步驟	內容	展示重點
Campaign details	活動名稱、負責人、發佈日期和摘要	兩欄 Form、必填驗證、整列 TextArea
Audience & budget	受眾、管道、預算和轉換目標	上一步、下一步、數字欄位
Review	前兩步內容的唯讀彙總	跨步驟共用頁面狀態、提交提示
Submitted	活動編號和完成說明	完成狀態、重設精靈

此範例不依賴後端介面。按鈕透過 Step 的元件介面切換步驟，適合直接理解元件結構與 Interaction。若要真正提交資料，可在 Review 步驟的按鈕互動中加入 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 是兩層結構：

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 Step	從 1 開始的整數	頁面首次開啟時顯示的步驟；超出範圍時自動限制在第一或最後一步
Direction	horizontal、vertical	步驟標頭橫向或縱向排列
Step Style	default、navigation、inline	一般流程、導覽式流程或緊湊行內樣式
Marker Size	small、medium、large	統一控制整組步驟編號或圖示尺寸；預設為 Medium
Label Placement	horizontal、vertical	標題位於圖示右側或下方
Progress Dots	開／關	用圓點取代編號或圖示；開啟後標題採縱向顯示
Allow Step Click	開／關	是否允許最終使用者直接點擊步驟標頭切換
Show Step Content	開／關	是否顯示目前 StepItem 的內容區
Responsive	開／關	窄螢幕時是否自動切換為適合閱讀的縱向版面
Current Step Status	process、wait、finish、error	目前步驟的預設狀態
Current Step Progress	0～100	目前步驟內的選用進度；主要用於 Default + Process 狀態

3.1 三種 Step Style

• Default：適合一般表單精靈，狀態與步驟關係最清楚。
• Navigation：步驟標頭更像流程導覽，適合允許使用者返回已填寫步驟的情境。
• Inline：資訊更緊湊，適合空間有限且標題很短的流程。在 Vertical Direction 下會自動使用 Default，避免不可讀的組合。

若流程必須依序完成，請關閉 Allow Step Click，只保留內容區中的 Back、Next 和 Submit 按鈕。

4. 設定 StepItem

選取單一 StepItem，可設定：

屬性	說明
Title	步驟主標題，必填；建議 2～5 個詞
Subtitle	輔助資訊，例如階段名稱、預計時間或負責人
Description	目前步驟內容的簡短說明
Status	auto、wait、process、finish、error
Disabled	禁止點擊及透過元件介面跳轉至此步驟
Icon	選用。透過統一 Icon 選擇器選用系統圖示並設定前景色／背景色，或上傳自訂圖片

Status 設為 auto 時，系統會依目前位置推導狀態：目前步驟之前為 Finish，之後為 Wait，目前項目使用 Step 的 Current Step Status。只有需要持續表達錯誤、等待或特殊完成狀態時，才覆寫單一 StepItem 的 Status。

4.1 編號、狀態與業務圖示

未設定 Icon 時，Step 預設顯示 1、2、3……，這是表單精靈和審批流程的建議方式。步驟完成後系統會自動以勾號取代編號；目前、等待和錯誤狀態也會自動套用對應色彩與標記，不必逐步手動設定紅、黃、綠背景。

只有圖示能明顯協助辨識業務階段時，才為 StepItem 設定 Icon，例如 User、Document、Payment、Review、Send 或 Milestone。此時應為整組步驟統一設定圖示，避免一部分使用編號、另一部分使用圖示。Icon 選擇器提供搜尋、選取預覽、前景色、背景色和無背景選項；屬性面板會顯示目前圖示的名稱與識別碼。

Marker Size 由外層 Step 統一控制，確保所有編號與圖示尺寸一致。不要透過上傳不同尺寸的圖片來改變單一步驟的視覺權重。

在設計器中編輯不同步驟

進入 Design Mode 後，直接點擊步驟列中的編號或標題即可切換目前設計步驟。下方內容區顯示該 StepItem 自己包含的 Form、Panel、輸入元件和按鈕；切換後，內容區與右側屬性面板會同步切換至對應 StepItem。

Allow Step Click 和 StepItem 的 Disabled 控制儲存後頁面的執行行為，不會阻止設計人員進入該步驟編輯內容。也可以在左側頁面結構展開 Steps → StepItem → Form，直接選取後續步驟的 Form 或欄位。

Disabled 適合「目前條件尚未滿足」的步驟。Next 和 Previous 會自動略過停用步驟；若該步驟完全不適用於目前使用者，應使用通用顯示條件隱藏，而非僅設為 Disabled。

5. 在步驟中組織表單

建議先在 StepItem 中新增 Form，再將欄位和 ButtonSet 放入 Form：

1. Form 統一控制 Controls Per Row、Layout、Label Alignment 和標籤／內容比例。
2. 欄位驗證由 Form 負責，Step 只負責流程切換。
3. 每個中間步驟提供明確的 Next；第二步以後同時提供 Back。
4. 最後一個業務步驟用於 Review 和 Submit；提交完成後再進入結果步驟。

範例 Form 使用 Controls Per Row = 2、Label 4 / Content 8。Campaign summary 開啟 Display Full Row，其 Label 仍占 4 欄並與 Launch date 對齊，Content 自動使用本列剩餘空間。

多個步驟需要讀取同一個值時，請使用相同的欄位 Name。例如編輯區與 Review 區都使用 campaignName，Review 中的唯讀欄位就能顯示使用者在第一步輸入的最新值。

6. 設定前進、後退和重設

Step 提供四個元件介面：

函式	參數	行為
nextStep	無	進入下一個可用步驟，並略過 Disabled 項目
previousStep	無	返回上一個可用步驟，並略過 Disabled 項目
goToStep	stepNumber	跳轉至指定步驟；編號從 1 開始
resetSteps	無	返回 Initial Step

以第一步的 Next 按鈕為例：

1. 選取按鈕，開啟 Interaction。
2. 在 onClick 下先新增 Trigger Form Validation，Form 選擇 campaign_details_form。
3. 再新增 元件介面。
4. Target Component 選擇 campaign_steps。
5. Function 選擇 nextStep。

動作依由上而下的順序執行。表單驗證失敗時，後續的 nextStep 不會執行；驗證成功後才會進入下一步。

Back 按鈕只需呼叫 previousStep。完成頁的「Create another campaign」按鈕呼叫 resetSteps。

7. 設定步驟切換互動

Step 支援兩層互動：

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，不會將程式化跳轉誤認為使用者點擊 StepItem。Disabled 步驟不會切換，也不會執行互動。

例如，在 Step 的 onChange 中新增 Toast，可顯示：

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

8. 情境一：後端驗證失敗時停留在目前步驟

Step Validation Gate 是兩步驟範例。第一步預設使用錯誤審批碼 TRY-AGAIN；後端拒絕後仍停留在第一步。改成 APPROVE-2026 並成功提交後，才會進入第二步。

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. 情境二：依後端狀態開啟目前處理人的步驟

Step Handoff 示範兩人依序處理。Avery Chen 已完成第一步，Morgan Lee 負責第二步。Page onLoad 會讀取流程狀態並預設開啟第二步；開啟 Allow Step Click 後，仍可回到唯讀的第一步查看內容。

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 完成，避免先顯示第一步再跳到第二步。請求失敗時保留 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 四個 StepItem，不設定 Icon。
4. 在前三個步驟加入兩欄 Horizontal Form；最後一步加入一欄唯讀 Form。
5. 第一、二步的 Next 按鈕先驗證本步驟 Form，再呼叫 nextStep。
6. 第二、三步的 Back 按鈕呼叫 previousStep。
7. Review 的 Submit 按鈕顯示成功 Toast，再呼叫 nextStep。
8. Submitted 的重設按鈕呼叫 resetSteps。
9. 儲存頁面，在 Preview 和執行階段分別走完一次完整流程。

兩個進階情境可參考 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. 設計建議

• 一個精靈通常維持 3～7 個步驟；超過 7 個時考慮拆成多個頁面或群組。
• 標題使用動作結果或業務階段，例如 Details、Audience、Review，避免使用長句。
• Next 按鈕明確提示下一步，例如「Next: Review」，比只寫「Continue」更容易理解。
• 不允許跳步的流程應關閉 Allow Step Click，並在每一步驗證成功後前進。
• 提交前提供 Review；提交後提供獨立完成頁，不要只顯示短暫 Toast。
• Error、Disabled 和完成狀態都應提供可讀說明，不能只依賴顏色。