WrapList
WrapList 위젯은 여러 개의 아이템을 한 방향으로 나열하다가 공간이 부족하면 다음 줄로 넘겨 배치하는 반복 레이아웃입니다.
크기가 서로 다른 아이템이 많을 때 스크롤 가능한 목록 형태로 보여주기에 적합합니다.
정의 / 역할
WrapList는 데이터 목록을 반복 렌더링하며, 각 아이템을 배치 방향(가로/세로)으로 나열하다가 공간이 부족하면 자동으로 줄바꿈합니다. maxLines를 지정하면 지정한 줄 수를 넘는 아이템을 잘라내고, 잘린 아이템 수(overflowCount)와 현재 줄 수(lineCount)를 이벤트로 보고합니다.
- 카테고리: Layouts
- 기본 배치 방향: 가로(
horizontal) - 드롭 시 크기: 부모 레이아웃(Row·Column·Stack 등) 안에 넣으면 기본
200 x 150으로 들어가고, 최상위(부모 없이)에 바로 배치하면 남는 공간을 채우도록 더 크게 표시됩니다.
기능
| 기능 | 설명 |
|---|---|
| 반복 배치 | 데이터 목록의 각 항목을 자식 위젯으로 반복 렌더링합니다. |
| 자동 줄바꿈 | 아이템이 한 줄에 다 들어가지 않으면 자동으로 다음 줄로 넘겨 배치합니다. |
| 간격 조정 | 아이템 간격(spacing)과 줄 간격(runSpacing)을 각각 설정합니다. |
| 정렬 | 메인축(alignment)·줄(runAlignment)·교차축(crossAxisAlignment) 정렬을 지정합니다. |
| 줄 수 제한 | maxLines로 표시할 줄 수를 제한하고, 잘린(초과한) 아이템 수를 이벤트로 알립니다. |
사용 방법
- 왼쪽 위젯 팔레트에서 Layouts 카테고리를 엽니다.
- WrapList 항목을 캔버스로 끌어다 놓습니다.
- 오른쪽 속성 패널에서 데이터 바인딩(또는
itemCount)으로 반복할 아이템 수를 지정합니다. - 안에 반복해서 표시할 자식 위젯을 배치합니다.
- 필요하면 배치 방향·간격·정렬·
maxLines등을 조정합니다.
속성 (Property)
| 속성 | 설명 | 기본값 | 값 / 타입 |
|---|---|---|---|
direction | 아이템 배치 방향 | horizontal (가로) | horizontal, vertical |
alignment | 메인축 방향 아이템 정렬 | start | start, end, center, spaceBetween, spaceAround, spaceEvenly |
spacing | 같은 줄 안 아이템 사이 간격(메인축) | 0 | 숫자(px) |
runAlignment | 줄(run)들의 정렬(교차축) | start | start, end, center, spaceBetween, spaceAround, spaceEvenly |
runSpacing | 줄과 줄 사이 간격(교차축) | 0 | 숫자(px) |
crossAxisAlignment | 줄 안에서 아이템의 교차축 정렬 | start | start, end, center |
textDirection | 메인축의 수평 진행 방향 | 미지정 | rtl, ltr |
verticalDirection | 줄이 쌓이는 수직 방향 | down | up, down |
clipBehavior | 영역을 벗어난 내용의 클립 방식 | none | none, hardEdge, antiAlias, antiAliasWithSaveLayer |
itemCount | 반복해서 표시할 아이템 개수 | 0 | 숫자 |
maxLines | 표시할 최대 줄 수 (미지정 = 무제한 = 자르지 않음) | 미지정 | 숫자 |
reservedTrailingExtent | maxLines가 설정된 경우 마지막 줄 끝에 예약할 메인축 폭 ("+N" 배지 자리 등) | 미지정 | 숫자(px) |
주의 / 팁
팁
maxLines를 지정하지 않으면(기본값 미지정) 줄 수 제한 없이 모든 아이템을 표시하며, 이때 overflowCount와 lineCount는 갱신되지 않습니다.
팁
반복할 데이터 목록은 속성(Property) 패널이 아니라 상단의 Data Binding 패널에서 연결합니다. 고정된 개수만 필요하면 itemCount로 지정합니다.
경고
overflowCount·lineCount는 편집 속성 패널에 노출되지 않는 출력(읽기 전용) 값입니다. 스크립트나 데이터 바인딩으로만 읽습니다.
더 알아보기
팁
이 위젯을 스크립트로 제어하는 Widget Control(Property·Method·Event) 전체는 WrapList (랩리스트) Widget Control 문서에서 확인하세요.