ListView
ListView(리스트뷰) 위젯은 여러 항목을 한 축(기본 세로) 방향으로 나열해 스크롤할 수 있는 리스트입니다.
데이터 개수만큼 항목을 반복해서 그려주며, 목록·피드·검색 결과처럼 항목이 이어지는 화면에 사용합니다.
정의 / 역할
ListView 위젯은 자식 항목을 지정한 축을 따라 순서대로 배치하고, 화면을 넘어가면 스크롤로 이어 볼 수 있게 합니다. 반복 항목의 개수는 바인딩한 데이터에 맞춰 늘고 줄며, 항목 사이 간격·안쪽 여백·스크롤 방향·스크롤 물리 효과 등을 설정할 수 있습니다. 스크롤이 끝에 닿았을 때 이벤트를 받아 다음 데이터를 불러오는 무한 스크롤에도 쓸 수 있습니다.
- 카테고리: Layouts
- 기본 스크롤 방향:
vertical(세로) - 기본 항목 개수:
0
기능
| 기능 | 설명 |
|---|---|
| 항목 반복 렌더링 | 바인딩한 데이터 개수(itemCount)만큼 자식 항목을 반복해서 그립니다. |
| 스크롤 방향 | 세로(vertical) 또는 가로(horizontal)로 나열하고 스크롤합니다. |
| 항목 간격 | spacing 값으로 항목 사이에 일정한 간격을 넣습니다. |
| 스크롤 끝 감지 | 스크롤이 리스트 끝에 닿으면 onScrollEnd 이벤트가 발화해 추가 로딩(무한 스크롤)에 활용할 수 있습니다. |
| 오버플로우 클립 | overflowMode를 clip으로 두면 정해진 영역에 맞춰 항목을 자르고, 잘린 개수를 보고합니다. |
| 등장 애니메이션 | animation 설정으로 항목이 차례로 나타나는(staggered) 등장 효과를 줍니다. |
사용 방법
- 왼쪽 위젯 팔레트에서 Layouts 카테고리를 엽니다.
- ListView 항목을 캔버스로 끌어다 놓습니다.
- 리스트 안에 반복해서 보여줄 자식 항목(위젯)을 배치합니다.
- 오른쪽 속성 패널에서
itemCount를 데이터에 바인딩하거나 개수를 지정합니다. - 필요하면 스크롤 방향(
scrollDirection)·항목 간격(spacing)·여백(padding) 등을 조정합니다.
속성 (Property)
| 속성 | 설명 | 기본값 | 값 / 타입 |
|---|---|---|---|
scrollDirection | 항목을 나열하고 스크롤하는 방향 | vertical | horizontal, vertical |
reverse | 항목 순서를 뒤집어 표시 | 꺼짐(false) | 참 / 거짓 |
shrinkWrap | 내용 크기에 맞춰 리스트 크기를 줄임 | 켜짐(true) | 참 / 거짓 |
spacing | 항목 사이 간격 | 미지정 | 숫자 |
padding | 리스트 안쪽 여백 | 미지정 | 여백 |
controller | 스크롤을 제어하는 컨트롤러 | 미지정 | 스크롤 컨트롤러 |
primary | 화면의 기본 스크롤 뷰로 사용할지 여부 | 미지정 | 참 / 거짓 |
physics | 스크롤 물리 효과 | 미지정 | bouncing, clamping, alwaysScrollable, rangeMaintaining, neverScrollable, page |
itemExtent | 각 항목의 고정 크기(주 축 방향) | 미지정 | 숫자 |
addAutomaticKeepAlives | 화면 밖 항목의 상태를 자동으로 유지 | 켜짐(true) | 참 / 거짓 |
addRepaintBoundaries | 항목마다 다시 그리기 경계를 추가 | 켜짐(true) | 참 / 거짓 |
addSemanticIndexes | 항목에 접근성 인덱스를 자동 부여 | 켜짐(true) | 참 / 거짓 |
cacheExtent | 화면 밖에서 미리 만들어 둘 영역 크기 | 미지정 | 숫자 |
semanticChildCount | 접근성에 알릴 항목 개수 | 미지정 | 정수 |
itemCount | 반복해서 그릴 항목 개수 (데이터 바인딩 지원) | 0 | 정수 |
dragStartBehavior | 드래그 스크롤이 시작되는 기준 | start | start, down |
keyboardDismissBehavior | 스크롤 시 키보드를 내리는 방식 | manual | manual, onDrag |
restorationId | 스크롤 위치 복원에 사용할 식별자 | 미지정 | 문자열 |
clipBehavior | 영역을 벗어나는 내용의 잘림 처리 방식 | hardEdge | none, hardEdge, antiAlias, antiAliasWithSaveLayer |
animation | 항목 등장(staggered) 애니메이션 설정 | 미지정 | 애니메이션 설정 |
overflowMode | 영역을 넘는 항목 처리 방식 | none | none, clip |
reservedTrailingExtent | clip 모드에서 가용 폭에서 추가로 비워 둘 폭 | 미지정 | 숫자 |
주의 / 팁
팁
onScrollEnd는 스크롤이 리스트 끝에 닿을 때 한 번 발화하고, 끝에서 벗어나면 다시 발화할 수 있게 준비됩니다. 다음 페이지를 불러오는 무한 스크롤에 활용하세요.
경고
scrollToIndex와 getFirstVisibleIndex는 itemExtent(항목 고정 크기)가 설정돼 있어야 동작합니다. 값이 없으면 스크롤 이동은 아무 일도 하지 않고, 첫 항목 인덱스는 0을 반환합니다.
더 알아보기
팁
이 위젯을 스크립트로 제어하는 Widget Control(Property·Method·Event) 전체는 ListView (리스트뷰) Widget Control 문서에서 확인하세요.