DragList
DragList(드래그리스트) 위젯은 아이템을 드래그해 순서를 바꿀 수 있는 스크롤 리스트입니다.
목록의 항목을 사용자가 직접 끌어다 재정렬해야 하는 화면에 사용합니다.
이 위젯은 Free 플랜에서 잠겨 있으며, Pro·Enterprise 플랜에서 사용할 수 있습니다.
정의 / 역할
DragList 위젯은 세로(기본) 또는 가로로 스크롤되는 리스트를 그리고, 각 아이템을 드래그해 순서를 재배치할 수 있게 합니다. 드래그 핸들 아이콘 표시, 아이템 전체 드래그, 다중 선택 이동, 스크롤 끝 감지, 진입 애니메이션을 지원합니다.
- 카테고리: Layouts (레이아웃)
- 기본 스크롤 방향: 세로(
vertical) - 기본 아이템 개수(itemCount):
0
기능
| 기능 | 설명 |
|---|---|
| 드래그 재정렬 | 아이템을 끌어다 놓아 순서를 바꿉니다. 이동이 끝나면 바인딩된 데이터 목록의 순서도 함께 갱신됩니다. |
| 드래그 핸들 | 각 아이템에 드래그 핸들 아이콘을 표시하고, 색·크기·정렬·여백을 설정합니다. |
| 아이템 전체 드래그 | 핸들 없이 아이템 전체를 잡아 드래그하도록 설정합니다. |
| 다중 선택 이동 | 체크박스 위젯과 연동해 여러 아이템을 한 번에 이동합니다. |
| 스크롤 제어 | 방향·역방향·물리 효과·여백 등 스크롤 동작을 조정합니다. |
| 진입 애니메이션 | 리스트가 나타날 때 스태거드(순차) 애니메이션을 재생합니다. |
사용 방법
- 왼쪽 위젯 팔레트에서 Layouts 카테고리를 엽니다.
- DragList 항목을 캔버스로 끌어다 놓습니다.
- 데이터 바인딩으로 리스트에 표시할 항목과 개수(
itemCount)를 연결합니다. - 필요하면 드래그 핸들 표시(
useDragHandler)·아이콘·색을 조정합니다. - 순서 변경을 처리하려면 스크립트에서 재정렬 이벤트(
onReorder등)를 연결합니다.
속성 (Property)
아래는 속성 패널을 펼쳤을 때 바로 보이는 최상위 속성입니다. animation·scrollController처럼 묶음(그룹) 속성은 펼치면 하위 옵션이 더 있으며, 해당 문서 버전에서는 최상위 항목만 다룹니다. 표 순서는 속성 패널에 나타나는 순서와 같습니다.
| 속성 | 설명 | 기본값 | 값 / 타입 |
|---|---|---|---|
useDragHandler | 각 아이템에 기본 드래그 핸들 아이콘 표시 여부 | true (켜김) | 참/거짓 |
selectWidgetId | 다중 선택에 사용할 체크박스 위젯의 ID | 미지정 | 문자열(위젯 ID) |
selectPropertyName | 선택 상태를 읽을 속성 이름 (미지정 시 value) | 미지정 | 문자열 |
handlerColor | 드래그 핸들 아이콘 색 | 미지정 | 색상 |
dragHandleIcon | 드래그 핸들에 쓸 아이콘 | 미지정(기본 핸들 아이콘) | 아이콘 설정 |
iconSize | 핸들 아이콘 크기 | 24 | 숫자(px) |
iconAlignment | 아이템 안 핸들 위치 | 오른쪽 가운데 | 정렬 값 |
dragHandlePadding | 핸들 주위 여백 | 미지정 | 여백 값 |
fullItemDraggable | 핸들 없이 아이템 전체를 잡아 드래그 | false | 참/거짓 |
padding | 리스트 바깥 여백 | 미지정 | 여백 값 |
itemPadding | 각 아이템 안쪽 여백 | 미지정 | 여백 값 |
scrollDirection | 스크롤(배치) 방향 | 세로 vertical | horizontal, vertical |
reverse | 스크롤 방향 역전 | false | 참/거짓 |
scrollController | 외부 스크롤 컨트롤러 | 미지정 | 스크롤 컨트롤러 |
primary | 기본 스크롤 뷰 여부 | 미지정 | 참/거짓 |
physics | 스크롤 물리 효과 | 미지정 | bouncing, clamping, alwaysScrollable, rangeMaintaining, neverScrollable, page |
shrinkWrap | 내용 크기에 맞춰 리스트 축소 | false | 참/거짓 |
anchor | 스크롤 앵커 위치 | 0.0 | 숫자(0~1) |
cacheExtent | 화면 밖 미리 렌더링 영역 | 미지정 | 숫자(px) |
dragStartBehavior | 드래그 시작 판정 방식 | start | down, start |
keyboardDismissBehavior | 스크롤 시 키보드 닫힘 처리 | 미지정 | manual, onDrag |
restorationId | 스크롤 위치 복원 ID | 미지정 | 문자열 |
clipBehavior | 자르기(clip) 방식 | hardEdge | none, hardEdge, antiAlias, antiAliasWithSaveLayer |
itemExtent | 아이템 고정 크기 | 미지정 | 숫자(px) |
autoScrollerVelocityScalar | 가장자리 자동 스크롤 속도 배율 | 800 | 숫자 |
itemCount | 리스트에 표시할 아이템 개수 (데이터 바인딩) | 0 | 숫자(정수) |
animation | 진입(스태거드) 애니메이션 설정 | 미지정 | 애니메이션 설정 |
순서 변경·스크롤 관련 이벤트(onReorder, onScrollEnd 등)와 개수·선택 제어는 스크립트 Widget Control로 제공되며, 아래 더 알아보기의 문서에서 확인합니다.
주의 / 팁
다중 선택 이동은 selectWidgetId에 선택 상태(체크박스) 위젯의 ID를 지정해야 동작합니다. 지정하지 않으면 한 번에 하나씩만 이동됩니다.
dragHandleIcon을 지정하지 않아도 useDragHandler가 켜져 있으면 기본 드래그 핸들 아이콘이 표시됩니다. fullItemDraggable을 켜면 핸들 대신 아이템 전체를 잡아 드래그합니다.
더 알아보기
이 위젯을 스크립트로 제어하는 Widget Control(Property·Method·Event) 전체는 DragList (드래그리스트) Widget Control 문서에서 확인하세요.