Step
Step은 명확한 순서가 있는 긴 작업을 여러 단계로 나눕니다. 각 단계에는 제목, 상태, 콘텐츠 영역이 있으며 Form, 입력 컨트롤, 설명, 작업 버튼을 배치할 수 있습니다.
이 가이드를 읽으면 다음을 구성할 수 있습니다.
- Step 컨테이너와 여러 StepItem 추가
- 가로, 세로, 내비게이션 및 컴팩트 스타일 설정
- 기본 번호와 자동 상태 아이콘 사용 또는 일관된 업무 아이콘 구성
- 각 단계에 폼과 버튼 조합
- 컴포넌트 함수를 이용한 다음, 이전, 특정 단계 이동 및 초기화
- 전환 전에 폼을 검증하고
onChange에서 현재 단계 읽기
Step, Tab, Progress는 용도가 다릅니다. Step은 반드시 또는 권장 순서대로 완료해야 하는 작업을 나타냅니다. Tab은 동일한 대상에 대한 병렬 콘텐츠를 구성합니다. Progress는 완료 비율만 보여 주며 각 단계의 페이지 콘텐츠를 포함하지 않습니다.
1. 예제: 캠페인 게시 마법사
Spark Sample의 Step 페이지는 4단계 캠페인 게시 마법사를 사용합니다.
| 단계 | 콘텐츠 | 주요 학습 내용 |
|---|---|---|
| Campaign details | 캠페인 이름, 담당자, 게시일, 요약 | 2열 Form, 필수 검증, 전체 행 TextArea |
| Audience & budget | 대상, 채널, 예산, 전환 목표 | 이전/다음 이동과 숫자 필드 |
| Review | 앞의 두 단계에 대한 읽기 전용 요약 | 단계 간 페이지 상태 공유와 제출 안내 |
| Submitted | 캠페인 번호와 완료 설명 | 완료 상태와 마법사 초기화 |
이 예제는 백엔드 엔드포인트에 의존하지 않습니다. 버튼이 Step 컴포넌트 API를 통해 단계를 전환하므로 구조와 Interaction을 바로 이해하기 좋습니다. 실제 데이터를 제출하려면 Review 단계 버튼의 인터랙션에 Send Request를 추가합니다.
2. Step 컨테이너 추가
- 대상 페이지를 열고 Page Designer로 이동합니다.
- 왼쪽 컴포넌트 패널에서 Containers를 펼칩니다.
- Step을 Screen 또는 컨테이너를 허용하는 영역으로 끌어 놓습니다.
- Step을 선택하고 Steps 하위 요소 영역에 StepItem을 추가합니다.
- 각 StepItem을 선택하고 Title을 입력합니다.
- 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 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…을 표시합니다. 이는 폼 마법사와 승인 흐름에 권장되는 방식입니다. 완료된 단계는 번호가 자동으로 체크 표시로 바뀝니다. 현재, 대기, 오류 상태에도 색상과 마커가 자동 적용되므로 각 단계에 빨강, 노랑, 초록 배경을 따로 설정할 필요가 없습니다.
User, Document, Payment, Review, Send, Milestone처럼 업무 단계를 분명하게 구분하는 경우에만 StepItem에 Icon을 추가합니다. 이때 전체 단계에 일관되게 아이콘을 적용하고 번호 단계와 아이콘 단계를 섞지 마십시오. Icon 선택기는 검색, 선택 미리보기, 전경색, 배경색, 배경 없음 옵션을 제공합니다. 속성 패널에는 현재 아이콘의 이름과 식별자가 표시됩니다.
Marker Size는 바깥쪽 Step에서 통합 관리하여 모든 번호와 아이콘 크기를 일관되게 합니다. 크기가 다른 이미지를 업로드해 특정 단계만 시각적으로 강조하지 마십시오.
Designer에서 다른 단계 편집
Design Mode에서 단계 바의 번호나 제목을 클릭하면 편집 중인 단계를 전환할 수 있습니다. 아래 콘텐츠 영역에는 해당 StepItem의 Form, Panel, 입력 컨트롤, 버튼이 표시되고 오른쪽 속성 패널도 해당 StepItem으로 함께 전환됩니다.
Allow Step Click과 StepItem의 Disabled는 저장된 페이지의 런타임 동작을 제어합니다. Designer에서 작성자가 단계를 열어 편집하는 것은 막지 않습니다. 왼쪽 페이지 구조에서 Steps → StepItem → Form을 펼쳐 뒤 단계의 Form이나 필드를 직접 선택할 수도 있습니다.
Disabled는 현재 조건이 아직 충족되지 않은 단계에 적합합니다. Next와 Previous는 비활성화된 단계를 자동으로 건너뜁니다. 현재 사용자에게 전혀 적용되지 않는 단계라면 Disabled만 설정하지 말고 공통 표시 조건으로 숨기십시오.
5. 단계 안에 폼 구성
먼저 StepItem에 Form을 추가한 다음 필드와 ButtonSet을 Form 안에 배치하는 방식을 권장합니다.
- Form이 Controls Per Row, Layout, Label Alignment 및 레이블/콘텐츠 비율을 통합 관리합니다.
- 필드 검증은 Form이 담당하고 Step은 프로세스 전환만 담당합니다.
- 각 중간 단계에 명확한 Next 버튼을 두고 두 번째 단계부터는 Back도 함께 제공합니다.
- 마지막 업무 단계에서 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 버튼을 예로 들면 다음과 같습니다.
- 버튼을 선택하고 Interaction을 엽니다.
onClick아래에 Trigger Form Validation을 먼저 추가하고 Form으로campaign_details_form을 선택합니다.- Component API 작업을 추가합니다.
- Target Component로
campaign_steps를 선택합니다. - Function으로
nextStep을 선택합니다.
작업은 위에서 아래 순서로 실행됩니다. 폼 검증이 실패하면 뒤의 nextStep은 실행되지 않으며 검증에 성공한 뒤에만 다음 단계로 이동합니다.
Back 버튼은 previousStep만 호출하면 됩니다. 완료 페이지의 “Create another campaign” 버튼은 resetSteps를 호출합니다.
7. 단계 전환 인터랙션 설정
Step은 두 계층의 인터랙션을 지원합니다.
- 바깥쪽 Step의
onChange - 개별 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. 시나리오 1: 백엔드 검증 실패 시 현재 단계에 머무르기
Step Validation Gate는 2단계 예제입니다. 초기 승인 코드 TRY-AGAIN은 백엔드에서 거부되며 1단계를 유지합니다. APPROVE-2026으로 수정한 뒤 성공 응답을 받아야만 2단계로 이동합니다.
- Submit request와 Accepted를 만들고 Initial Step을
1, Allow Step Click을 끔으로 설정합니다. validation_gate_form에requestTitle과approvalCode를 추가합니다.- Submit and continue의 첫 동작으로 Submit Form을 추가하고 Custom URL을
/spark/api/sample/step/validation-gate로 설정합니다. - 그 뒤에
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는 두 사람이 순서대로 처리하는 흐름입니다. Avery Chen이 1단계를 완료했고 Morgan Lee가 2단계를 담당합니다. Page onLoad가 워크플로 상태를 읽어 2단계를 기본으로 엽니다. Allow Step Click을 켜 두면 읽기 전용 1단계로 돌아가 내용을 확인할 수 있습니다.
- Requester submission과 Manager review를 만듭니다. 안전한 대체값으로 Initial Step을
1로 유지하고, Allow Step Click을 켜며 완료된 첫 번째 Form을 읽기 전용으로 설정합니다. - Page
onLoad에서caseId=CAM-2048과 함께GET /spark/api/sample/step/handoff/status를 호출합니다. - 응답의
activeStep을workflow.activeStep에 바인딩합니다. - 이어서
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 버튼에 다음 순서로 설정합니다.
- Trigger Form Validation
- Send Request 또는 Submit Form
- 성공 Toast
nextStep을 호출해 완료 페이지로 이동
페이지 요청에는 현재 환경과 렌더링 모드가 자동으로 포함됩니다. 개별 Step에서 프로토콜 Header를 수동으로 추가하지 마십시오. 전체 프로토콜은 페이지 요청 컨텍스트 및 백엔드 디버깅을 참고하십시오.
Send Request가 실패하면 이후 작업을 중단하고 현재 단계를 유지하여 사용자가 데이터를 수정하고 다시 시도할 수 있게 합니다. 완료 페이지로 먼저 이동한 뒤 제출 결과를 비동기로 기다리지 마십시오.
11. Spark Sample 재현
- Step을 추가하고 Horizontal, Default, Vertical Label, Responsive, Allow Step Click을 설정합니다.
- Marker Size를 Medium으로 설정하고 기본 번호 마커를 유지합니다.
- Icon 없이 Campaign details, Audience & budget, Review, Submitted StepItem 네 개를 추가합니다.
- 처음 세 단계에 2열 Horizontal Form을, 마지막 단계에 1열 읽기 전용 Form을 추가합니다.
- 첫 번째와 두 번째 단계의 Next 버튼은 현재 Form을 검증한 뒤
nextStep을 호출합니다. - 두 번째와 세 번째 단계의 Back 버튼은
previousStep을 호출합니다. - Review의 Submit 버튼은 성공 Toast를 표시한 뒤
nextStep을 호출합니다. - Submitted의 초기화 버튼은
resetSteps를 호출합니다. - 페이지를 저장하고 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, 완료 상태는 색상뿐 아니라 읽을 수 있는 설명도 함께 제공합니다.