MasonryGrid
MasonryGrid(메이슨리그리드) 위젯은 높이가 제각각인 타일을 빈틈 없이 채워 배치하는 스태거드(staggered) 그리드입니다.
갤러리형 카드 목록처럼 항목마다 높이가 다른 콘텐츠를 여러 열로 정렬할 때 사용합니다.
정보
이 위젯은 Free 플랜에서 잠겨 있으며, Pro·Enterprise 플랜에서 사용할 수 있습니다.
정의 / 역할
MasonryGrid 위젯은 자식 항목을 지정한 열 개수(crossAxisCount)로 나눠, 각 타일의 높이에 맞춰 위에서부터 촘촘히 쌓아 올리는 그리드입니다. 일반 그리드와 달리 타일 높이가 균일하지 않아도 빈 공간 없이 채워집니다. 항목은 데이터 개수(itemCount)만큼 반복 생성되며, 반복되는 자식(child) 하나를 템플릿으로 사용합니다.
- 카테고리: Layouts
- 드롭 시 크기: 부모 레이아웃(Row·Column·Stack 등) 안에 넣으면 기본
200 x 150, 최상위(부모 없이)에 배치하면 캔버스를 채우도록 더 크게 표시됩니다.
기능
| 기능 | 설명 |
|---|---|
| 스태거드 배치 | 타일 높이가 서로 달라도 빈 공간 없이 위에서부터 촘촘하게 채웁니다. |
| 열 개수 지정 | crossAxisCount로 한 줄(교차축)에 배치할 열 개수를 정합니다. |
| 항목 반복 | itemCount 수만큼 자식 항목을 반복해서 렌더링합니다. |
| 간격 조정 | mainAxisSpacing·crossAxisSpacing으로 세로·가로 타일 간격을 조정합니다. |
| 스크롤 설정 | 스크롤 방향(scrollDirection)·역방향(reverse)·물리 효과(physics) 등을 설정합니다. |
사용 방법
- 왼쪽 위젯 팔레트에서 Layouts 카테고리를 엽니다.
- MasonryGrid 항목을 캔버스로 끌어다 놓습니다.
- 오른쪽 속성 패널에서
crossAxisCount로 열 개수를 지정합니다. itemCount로 반복할 항목 수를 정하고, 반복될 자식 위젯을 구성합니다.- 필요하면
mainAxisSpacing·crossAxisSpacing으로 타일 간격을 조정합니다.
속성 (Property)
| 속성 | 설명 | 기본값 | 값 / 타입 |
|---|---|---|---|
scrollDirection | 스크롤(배치) 방향 | vertical | horizontal, vertical |
reverse | 항목 배치 순서를 뒤집기 | 꺼짐(false) | 참 / 거짓 |
controller | 연결할 스크롤 컨트롤러 | 미지정 | 스크롤 컨트롤러 |
primary | 기본 스크롤 뷰로 사용 여부 | 미지정 | 참 / 거짓 |
physics | 스크롤 물리 효과 | 미지정 | 스크롤 물리 값 |
shrinkWrap | 내용 크기에 맞게 축소 배치 | 켜짐(true) | 참 / 거짓 |
padding | 그리드 안쪽 여백 | 미지정 | 여백 값 |
crossAxisCount | 한 줄(교차축)에 배치할 열 개수 | 1 | 숫자(1 이상) |
mainAxisSpacing | 주축(세로) 타일 간격 | 0 | 숫자(0 이상) |
crossAxisSpacing | 교차축(가로) 타일 간격 | 0 | 숫자(0 이상) |
itemCount | 반복 생성할 항목 수 | 0 | 숫자 |
addAutomaticKeepAlives | 화면 밖 항목 상태 유지 | 켜짐(true) | 참 / 거짓 |
addRepaintBoundaries | 항목별 리페인트 경계 추가 | 켜짐(true) | 참 / 거짓 |
addSemanticIndexes | 항목에 시맨틱 인덱스 부여 | 켜짐(true) | 참 / 거짓 |
cacheExtent | 미리 렌더링할 캐시 영역 크기 | 미지정 | 숫자 |
semanticChildCount | 시맨틱 자식 개수 | 미지정 | 숫자 |
dragStartBehavior | 드래그 시작 동작 기준 | start | down, start |
keyboardDismissBehavior | 스크롤 시 키보드 닫기 동작 | manual | manual, onDrag |
restorationId | 스크롤 위치 복원 ID | 미지정 | 문자열 |
clipBehavior | 자식 클리핑 방식 | hardEdge | none, hardEdge, antiAlias, antiAliasWithSaveLayer |
주의 / 팁
경고
crossAxisCount는 1 이상으로 지정해야 합니다. 값이 클수록 한 줄에 더 많은 열이 배치됩니다.
팁
shrinkWrap이 기본값 true이므로 그리드는 내용 높이만큼만 차지합니다. 다른 스크롤 영역 안에 넣을 때 유용합니다.
더 알아보기
팁
이 위젯을 스크립트로 제어하는 Widget Control(Property·Method·Event) 전체는 MasonryGrid (메이슨리그리드) Widget Control 문서에서 확인하세요.