GridView
GridView(그리드뷰) 위젯은 항목을 격자(그리드) 형태로 배치해 보여주는 스크롤 가능한 목록 위젯입니다.
같은 크기의 셀을 여러 열로 반복 배치할 때 사용합니다.
정의 / 역할
GridView 위젯은 하나의 항목 템플릿을 반복해 격자로 그려주는 반복(iterator) 위젯입니다. 셀은 균일한 크기로 배치되며, 한 줄에 넣을 셀 개수 또는 셀 하나의 최대 크기를 기준으로 열 수를 정할 수 있습니다. 스크롤 방향·간격·셀 비율 등을 설정할 수 있습니다.
- 카테고리: Layouts (레이아웃)
- 드롭 시 크기: 부모 레이아웃(Row·Column·Stack 등) 안에 넣으면 기본
300 x 200, 최상위(부모 없이)에 배치하면 캔버스를 채우도록 더 크게 표시됩니다.
기능
| 기능 | 설명 |
|---|---|
| 격자 배치 | 항목을 여러 열의 격자로 배치합니다. 열 수 결정 방식은 crossAxisType으로 고릅니다. |
| 열 수 / 셀 크기 | crossAxisType이 count면 한 줄 셀 개수(crossAxisCount)로, extent면 셀 최대 크기(maxCrossAxisExtent)로 열 수가 정해집니다. |
| 간격 · 비율 | 주축·교차축 셀 간격(mainAxisSpacing·crossAxisSpacing)과 셀 가로/세로 비율(childAspectRatio)을 조정합니다. |
| 스크롤 | 스크롤 방향(scrollDirection)·역방향(reverse)·물리 효과(physics) 등을 설정합니다. |
| 스크립트 제어 | 항목 추가·삭제, 특정 항목으로 스크롤, 선택 이벤트 처리 등을 스크립트로 다룰 수 있습니다. |
사용 방법
- 왼쪽 위젯 팔레트에서 Layouts 카테고리를 엽니다.
- GridView 항목을 캔버스로 끌어다 놓습니다.
- 오른쪽 속성 패널에서
crossAxisType을 고르고,count면crossAxisCount(한 줄 셀 개수),extent면maxCrossAxisExtent(셀 최대 크기)를 설정합니다. childAspectRatio·mainAxisSpacing·crossAxisSpacing으로 셀 비율과 간격을 조정합니다.- 반복해 보여줄 항목 템플릿을 GridView 안에 배치합니다.
속성 (Property)
| 속성 | 설명 | 기본값 | 값 / 타입 |
|---|---|---|---|
crossAxisType | 열 수 결정 방식 (개수 기준 / 셀 최대 크기 기준) | count | count, extent |
crossAxisCount | 한 줄에 배치할 셀 개수 (crossAxisType이 count일 때 사용) | 2 | 숫자(정수, 최소 1) |
maxCrossAxisExtent | 셀 하나의 최대 교차축 크기 (crossAxisType이 extent일 때 사용) | 100 | 숫자 |
scrollDirection | 스크롤 방향 | vertical | horizontal, vertical |
reverse | 스크롤 방향 반전 여부 | false | 참 / 거짓 |
controller | 스크롤 컨트롤러 | 미지정 | 스크롤 컨트롤러 |
primary | 기본 스크롤 뷰 사용 여부 | 미지정 | 참 / 거짓 |
physics | 스크롤 물리 효과 | 미지정 | bouncing, clamping, alwaysScrollable, rangeMaintaining, neverScrollable, page |
shrinkWrap | 콘텐츠 크기에 맞춰 축소 여부 | true | 참 / 거짓 |
padding | 안쪽 여백 | 미지정 | 여백 값 |
mainAxisSpacing | 주축(스크롤 방향) 셀 간격 | 0 | 숫자(최소 0) |
crossAxisSpacing | 교차축 셀 간격 | 0 | 숫자(최소 0) |
childAspectRatio | 셀의 가로/세로 비율 | 2 | 숫자(최소 0.1) |
addAutomaticKeepAlives | 화면 밖으로 벗어난 항목 상태 유지 여부 | true | 참 / 거짓 |
addRepaintBoundaries | 리페인트 경계 추가 여부 | true | 참 / 거짓 |
addSemanticIndexes | 시맨틱 인덱스 추가 여부 | true | 참 / 거짓 |
cacheExtent | 미리 그려 둘 캐시 영역 크기 | 미지정 | 숫자 |
semanticChildCount | 시맨틱 자식 개수 | 미지정 | 숫자(정수) |
dragStartBehavior | 드래그 시작 판정 동작 | start | down, start |
keyboardDismissBehavior | 스크롤 시 키보드 닫힘 동작 | manual | manual, onDrag |
restorationId | 스크롤 위치 복원 ID | 미지정 | 문자열 |
clipBehavior | 영역 밖 클립 처리 방식 | hardEdge | none, hardEdge, antiAlias, antiAliasWithSaveLayer |
itemCount | 반복해 그릴 항목 개수 | 0 | 숫자(정수) |
주의 / 팁
팁
crossAxisType을 count로 두면 crossAxisCount가, extent로 두면 maxCrossAxisExtent가 열 수 결정에 쓰입니다. 편집 화면에서 crossAxisType을 바꾸면 쓰이지 않는 쪽 속성은 자동으로 숨겨집니다.
경고
controller를 지정하면서 primary를 참으로 두면 함께 쓸 수 없어 오류로 처리됩니다. 둘 중 하나만 사용하세요.
더 알아보기
팁
이 위젯을 스크립트로 제어하는 Widget Control(Property·Method·Event) 전체는 GridView (그리드뷰) Widget Control 문서에서 확인하세요.