DragList (드래그리스트) Widget Control

DragList(드래그리스트) 위젯을 스크립트에서 제어할 때 사용하는 Widget Control(Property · Method · Event) 목록입니다. 위젯 소개와 사용법은 DragList 문서를 참고하세요.

정보

아래 예시의 draglistID는 캔버스에서 DragList 위젯에 지정한 이름(ID)입니다. 스크립트에서는 위젯ID.멤버 형태로 접근합니다.

Widget Control 요약

Widget Control	종류	시그니처	설명
add	Method	add() → 정수	끝에 빈 아이템을 추가하고 새 인덱스를 반환
clear	Method	clear()	모든 아이템 제거
count	Property	count (읽기/쓰기, 정수)	반복 렌더링하는 아이템 개수. 값을 쓰면 바인딩 목록 길이를 맞추고 다시 그림
current	Property	current (읽기/쓰기, 정수)	바인딩 스코프로 쓸 현재 아이템 인덱스. 없으면 -1
insert	Method	insert(index)	지정 위치에 빈 아이템 삽입
onMultiReorder	Event	onMultiReorder = (indices, newIndex) => { ... }	선택된 여러 아이템을 함께 이동했을 때
onReorder	Event	onReorder = (oldIndex, newIndex) => { ... }	아이템 하나를 드래그해 이동했을 때
onReorderEnd	Event	onReorderEnd = (index) => { ... }	드래그 재정렬이 끝났을 때
onReorderStart	Event	onReorderStart = (index) => { ... }	드래그 재정렬이 시작될 때 (selectWidgetId 지정 시에만 발화)
onScrollEnd	Event	onScrollEnd = () => { ... }	스크롤이 리스트 끝(하단)에 도달했을 때
onSelected	Event	onSelected = (index) => { ... }	아이템을 탭했을 때
remove	Method	remove(index)	지정 인덱스 아이템 제거
select	Property	select (읽기/쓰기, 정수)	선택된 아이템 인덱스. 없으면 -1
setOnceAnimation	Method	setOnceAnimation()	진입(스태거드) 애니메이션을 다음 빌드에 한 번 재생
setState	Method	setState(index, function)	해당 아이템을 스코프로 콜백 실행 후 그 아이템만 갱신

Widget Control 상세

add

리스트 끝에 빈 아이템을 하나 추가하고 리스트를 다시 그립니다.

• 종류: Method
• Parameters: 없음
• Returns: 정수(int) - 새로 추가된 아이템의 인덱스

Example

const i = draglistID.add();

clear

모든 아이템을 제거하고 리스트를 다시 그립니다.

• 종류: Method
• Parameters: 없음
• Returns: 없음

Example

draglistID.clear();

count

반복 렌더링하는 아이템 개수를 읽고 씁니다. 값을 쓰면 바인딩된 데이터 목록의 길이를 그 값에 맞춰 늘리거나 줄인 뒤 리스트를 다시 그립니다.

• 종류: Property (읽기/쓰기)
• 타입: 정수(int)

Example

draglistID.count = 5;
const n = draglistID.count;

current

바인딩 스코프로 사용할 현재 아이템 인덱스를 읽고 씁니다. 값을 쓰면 이후의 속성 쓰기가 그 아이템(행)을 대상으로 적용됩니다. 지정된 것이 없으면 -1을 반환합니다.

• 종류: Property (읽기/쓰기)
• 타입: 정수(int), 없을 때 -1

Example

draglistID.current = 0;
const cur = draglistID.current;

insert

지정한 위치에 빈 아이템을 삽입하고 리스트를 다시 그립니다.

• 종류: Method
• Parameters: index (정수) - 삽입할 위치
• Returns: 없음

Example

draglistID.insert(0);

onMultiReorder

선택된 여러 아이템을 함께 이동했을 때 실행됩니다.

• 종류: Event
• 핸들러 인자: indices (정수 배열) - 이동한 아이템들의 원래 인덱스(정렬됨) / newIndex (정수) - 드롭 대상 인덱스
• Returns: 없음

Example

draglistID.onMultiReorder = (indices, newIndex) => {
  // 다중 이동 처리
};

onReorder

아이템 하나를 드래그해 새 위치로 옮겼을 때 실행됩니다.

• 종류: Event
• 핸들러 인자: oldIndex (정수) - 이동 전 인덱스 / newIndex (정수) - 이동 후 인덱스
• Returns: 없음

Example

draglistID.onReorder = (oldIndex, newIndex) => {
  // 순서 변경 처리
};

onReorderEnd

드래그 재정렬 제스처가 끝났을 때(이동이 적용된 뒤) 실행됩니다.

• 종류: Event
• 핸들러 인자: index (정수) - 드래그한 아이템의 최종 인덱스
• Returns: 없음

Example

draglistID.onReorderEnd = (index) => {
  // 드래그 종료 처리
};

onReorderStart

드래그 재정렬 제스처가 시작될 때 실행됩니다. 단, 다중 선택 연동용 selectWidgetId가 지정되어 유효한 위젯에 매핑될 때만 발화합니다. selectWidgetId를 지정하지 않으면 이 이벤트는 호출되지 않습니다(반면 onReorderEnd는 항상 발화).

• 종류: Event
• 핸들러 인자: index (정수) - 드래그 중인 아이템 인덱스
• Returns: 없음

Example

draglistID.onReorderStart = (index) => {
  // 드래그 시작 처리
};

onScrollEnd

스크롤이 리스트 끝(하단)에 도달했을 때 한 번 실행됩니다. 하단에서 벗어나 다시 스크롤하면 재발화됩니다.

• 종류: Event
• 핸들러 인자: 없음
• Returns: 없음

Example

draglistID.onScrollEnd = () => {
  // 다음 페이지 로드 등
};

onSelected

사용자가 아이템을 탭했을 때 실행됩니다.

• 종류: Event
• 핸들러 인자: index (정수) - 탭한 아이템 인덱스
• Returns: 없음

Example

draglistID.onSelected = (index) => {
  // 아이템 선택 처리
};

remove

지정한 인덱스의 아이템을 제거하고 리스트를 다시 그립니다. 인덱스가 범위를 벗어나면 아무 동작도 하지 않습니다.

• 종류: Method
• Parameters: index (정수) - 제거할 아이템 인덱스
• Returns: 없음

Example

draglistID.remove(0);

select

선택된 아이템 인덱스를 읽고 씁니다. 선택된 것이 없으면 -1을 반환합니다.

• 종류: Property (읽기/쓰기)
• 타입: 정수(int), 없을 때 -1

Example

draglistID.select = 2;
const sel = draglistID.select;

setOnceAnimation

진입(스태거드) 애니메이션을 다음 빌드 때 한 번 다시 재생합니다. 애니메이션 설정이 되어 있어야 효과가 나타납니다.

• 종류: Method
• Parameters: 없음
• Returns: 없음

Example

draglistID.setOnceAnimation();

setState

지정한 아이템을 바인딩 스코프로 삼아 콜백을 실행한 뒤, 그 아이템만 다시 그립니다. 특정 아이템의 바인딩 속성을 갱신할 때 사용합니다.

• 종류: Method
• Parameters: index (정수) - 갱신할 아이템 인덱스 / function (함수) - 해당 아이템이 활성 스코프인 동안 실행할 콜백
• Returns: 없음

Example

draglistID.setState(0, () => {
  // 인덱스 0 아이템의 바인딩 속성 갱신
});

공통 Widget Control (모든 위젯)

노트

모든 위젯은 setProperty / getProperty / setStyleProperty 같은 이름 기반 공통 Widget Control(Method)도 사용할 수 있습니다. 자세한 규칙은 공통 Widget Control 레퍼런스 문서(작성 예정)를 참고하세요.