PageView
PageView(페이지뷰) 위젯은 여러 페이지를 한 번에 한 개씩 넘겨 보는 스크롤 영역입니다.
온보딩·이미지 슬라이드·좌우로 넘기는 화면 등에 사용합니다.
정의 / 역할
PageView 위젯은 반복되는 자식 아이템을 페이지 단위로 배치하고, 한 번에 한 페이지씩 스와이프하거나 스크립트로 넘길 수 있게 해줍니다. 스크롤 방향(가로/세로)·페이지 스냅·스크롤 물리 효과·양끝 여백 등을 설정할 수 있습니다.
- 카테고리: Layouts
- 드롭 시 크기: 부모 레이아웃(Row·Column·Stack 등) 안에 넣으면 기본
300 x 200, 최상위(부모 없이)에 배치하면 캔버스를 채우도록 더 크게 표시됩니다.
기능
| 기능 | 설명 |
|---|---|
| 페이지 단위 스크롤 | 한 번에 한 페이지씩 표시하며, 스와이프로 페이지를 넘깁니다. |
| 스크롤 방향 | 가로 또는 세로 방향으로 페이지를 넘기도록 설정합니다. |
| 페이지 스냅 | 스크롤이 끝나면 가장 가까운 페이지에 자동으로 맞춰집니다. |
| 반복 아이템 | 자식을 반복 렌더링하며, 표시할 페이지 개수를 조절합니다. |
| 스크립트 제어 | goToPage·nextPage·previousPage 등으로 표시 페이지를 제어하고, 페이지가 바뀌면 onPageChanged 이벤트를 받습니다. |
사용 방법
- 왼쪽 위젯 팔레트에서 Layouts 카테고리를 엽니다.
- PageView 항목을 캔버스로 끌어다 놓습니다.
- 안에 페이지로 표시할 자식 위젯을 배치합니다.
- 오른쪽 속성 패널에서
scrollDirection·pageSnapping등을 원하는 값으로 조정합니다. - 필요하면
onPageChanged에 페이지 전환 시 실행할 동작을 연결합니다.
속성 (Property)
| 속성 | 설명 | 기본값 | 값 / 타입 |
|---|---|---|---|
scrollDirection | 페이지를 넘기는 방향 | 가로(horizontal) | horizontal, vertical |
itemCount | 표시할 페이지(아이템) 개수 | 0 | 숫자(정수) |
reverse | 스크롤 방향을 반대로 뒤집기 | false | 참/거짓 |
physics | 스크롤 물리 효과 | 미지정 | bouncing, clamping, alwaysScrollable, rangeMaintaining, neverScrollable, page |
pageSnapping | 스크롤 후 가장 가까운 페이지로 자동 정렬 | true | 참/거짓 |
dragStartBehavior | 드래그 시작 동작 방식 | start | down, start |
allowImplicitScrolling | 인접 페이지 미리 로드(접근성 스크롤 허용) | false | 참/거짓 |
restorationId | 스크롤 위치 복원 식별자 | 미지정 | 문자열 |
clipBehavior | 영역 밖 내용 잘라내기 방식 | hardEdge | none, hardEdge, antiAlias, antiAliasWithSaveLayer |
padEnds | 첫·마지막 페이지 양끝에 여백 추가 | true | 참/거짓 |
주의 / 팁
경고
physics를 neverScrollable로 설정하면 스와이프로 페이지를 넘길 수 없습니다. 이때는 스크립트(goToPage·nextPage·previousPage)로만 페이지를 이동할 수 있습니다.
팁
페이지가 바뀔 때 실행할 동작은 onPageChanged에 연결합니다. 현재 페이지 번호는 스크립트에서 getCurrentPage()로 확인할 수 있습니다.
더 알아보기
팁
이 위젯을 스크립트로 제어하는 Widget Control(Property·Method·Event) 전체는 PageView (페이지뷰) Widget Control 문서에서 확인하세요.