Grid 컴포넌트
Grid는 페이지를 안정적이고 재사용 가능한 반응형 영역으로 나누는 레이아웃 컴포넌트입니다. 대시보드, 상세 페이지, 본문과 사이드바, 동일 너비 카드 묶음에 적합합니다. 각 영역에는 Form, Common Panel, ProTable, DataList 등의 컴포넌트를 배치할 수 있습니다.
1. 예제: 캠페인 운영 대시보드
Spark Sample의 Grid 페이지는 자주 사용하는 세 가지 구성을 보여 줍니다.
| 행 | 열 너비 | 용도 |
|---|---|---|
| Equal Thirds | 8 + 8 + 8 | 동일 너비 KPI 카드 3개 |
| Main and Sidebar | 16 + 8 | 캠페인 상세와 배포 체크리스트 |
| Equal Halves | 12 + 12 | 일정과 대상 고객 영역 |
Screen
└── Grid
├── Row → 8/24 + 8/24 + 8/24
├── Row → 16/24 + 8/24
└── Row → 12/24 + 12/24
이 예제는 초기 필드 값만 사용하므로 백엔드 API가 필요하지 않습니다. 실제 데이터를 사용하려면 열 안에 Data Form, DataList 또는 ProTable을 배치합니다.
2. 3단계 구조
- Grid: 행 전체의 가로 배치와 세로 정렬을 제어합니다.
- Grid Row: 한 행을 나타내며 열 간격과 줄바꿈 간격을 제어합니다.
- Grid Column: 24열 중 일부를 차지하고 업무 컴포넌트를 담습니다.
다음 순서로 구성합니다.
Grid → Grid Row → Grid Column → Common Panel / Form / 데이터 컴포넌트
3. Grid 추가
- Page Designer에서 페이지를 열고 Screen을 선택합니다.
- Screen의 Grid 하위 요소 영역에 Grid를 추가합니다.
- Grid의 Rows에 Grid Row를 추가합니다.
- Row의 Columns에 하나 이상의 Grid Column을 추가합니다.
- 각 열의 Span Columns를 설정합니다.
- 열의 Panels에 Common Panel, Form, ProTable 등을 추가합니다.
- 저장한 뒤 디자인 미리보기와 실행 화면을 모두 확인합니다.
새 Grid Column은 기본적으로 24/24를 차지하므로 추가 직후 전체 너비로 표시됩니다.
4. 24열 그리드 사용
Span Columns는 1~24 사이의 값입니다.
| 레이아웃 | 값 |
|---|---|
| 전체 너비 | 24 |
| 동일한 두 영역 | 12 + 12 |
| 동일한 세 영역 | 8 + 8 + 8 |
| 동일한 네 영역 | 6 + 6 + 6 + 6 |
| 본문과 사이드바 | 16 + 8 또는 18 + 6 |
한 행의 합계는 보통 24로 맞춥니다. 24보다 작으면 빈 공간이 남고 Horizontal Alignment에 따라 배치됩니다. 24를 넘으면 뒤쪽 열이 다음 줄로 넘어갑니다. Column Gap은 시각적 간격이므로 24에서 뺄 필요가 없습니다.
5. 간격과 정렬
Grid Row에서 다음을 설정합니다.
| 속성 | 범위 | 설명 |
|---|---|---|
| Column Gap | 0~64 | 인접한 열 사이의 가로 간격(px) |
| Row Gap | 0~64 | 줄바꿈된 열 사이의 세로 간격(px) |
외부 Grid에서는 다음을 설정합니다.
- Horizontal Alignment:
start,end,center,space-between,space-around - Vertical Alignment:
top,middle,bottom
열 너비의 합이 24이면 남는 공간이 없어 가로 정렬 값이 같아 보일 수 있습니다. 차이를 확인할 때는 임시로 8 + 8을 사용합니다. 세로 정렬은 같은 행의 열 높이가 서로 다를 때 확인할 수 있습니다.
6. 열 최소 높이
Minimum Column Height는 0~1200px입니다.
0: 콘텐츠 높이에 맞춰 자동으로 늘어납니다. 기본 권장값입니다.- 양수: 지정한 높이를 최소로 확보합니다. 콘텐츠가 더 크면 열이 계속 늘어나며 잘리지 않습니다.
같은 행의 카드를 균형 있게 보이게 하려면 동일한 최소 높이를 사용합니다. 이 값은 최대 높이가 아닙니다.
7. 열 내부 콘텐츠
- Common Panel + Form: 제목이 있는 상세 카드 또는 KPI 카드
- Form: 별도 카드 제목이 필요 없는 입력 영역
- ProTable / DataList: 본문 목록, 필터 또는 사이드 영역
- Tree: 일반적으로 Screen의 Navigation Tree 영역을 사용하고, 일반 콘텐츠일 때만 Grid Column에 배치
Grid는 외부 영역의 너비를 결정합니다. Form의 Controls Per Row와 Form Grid Split은 해당 영역 안에서 다시 계산되며 페이지 전체 24열을 기준으로 하지 않습니다.
8. 예제 재현
- Grid를 추가하고
start,top을 설정합니다. - Column Gap과 Row Gap이
16인 Row를 추가합니다. 8 + 8 + 8열을 만들고 최소 높이를 각각156으로 설정합니다.16 + 8행을 만들고 최소 높이를228로 설정합니다.12 + 12행을 만들고 최소 높이를176으로 설정합니다.- 각 열에 Common Panel과 읽기 전용 Form을 배치합니다.
- 저장 후 브라우저 너비를 줄여 모바일 단일 열 배치를 확인합니다.
9. 반응형 동작
PC에서는 설정한 24열 너비를 사용합니다. 휴대전화나 좁은 화면에서는 카드와 폼이 지나치게 좁아지지 않도록 설정 순서대로 한 열에 쌓입니다. Page JSON과 Span Columns는 변경되지 않으며 화면이 넓어지면 원래 배치로 돌아옵니다.
10. 백엔드와 상호작용
Grid 자체는 요청을 보내지 않는 순수 레이아웃 컴포넌트입니다. Java 백엔드는 하위 데이터 컴포넌트나 Interaction이 업무 데이터를 사용할 때만 필요합니다. 페이지 요청에는 환경과 렌더링 모드가 자동으로 포함됩니다. 자세한 내용은 페이지 요청 컨텍스트와 백엔드 디버깅을 참조하세요.
상호작용은 Grid Row나 Grid Column이 아니라 실제 동작을 수행하는 버튼, 필드, 카드 또는 데이터 컴포넌트에 설정합니다.
11. 문제 해결
- 열이 다음 줄로 넘어감: Span Columns 합계가 24를 초과하는지 확인합니다.
- Horizontal Alignment가 달라 보이지 않음: 빈 공간이 생기도록
8 + 8로 시험합니다. - Vertical Alignment가 달라 보이지 않음: 높이가 다른 두 열을 사용합니다.
- Form 라벨 비율이 이상함: Grid Column 너비를 먼저 정한 뒤 Form 내부 분할을 설정합니다.
- 미리보기와 실행 화면이 다름: 페이지를 저장하고 현재
versionId를 사용하는지 확인합니다.