ListView (리스트뷰) Widget Control

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

정보

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

Widget Control 요약

Widget Control	종류	시그니처	설명
count	Property	count (읽기/쓰기)	반복 항목 개수를 읽거나 설정
current	Property	current (읽기/쓰기)	바인딩 스코프로 쓸 현재 항목 인덱스
select	Property	select (읽기/쓰기)	선택된 항목 인덱스
overflowCount	Property	overflowCount (읽기 전용)	clip 모드에서 잘려 숨겨진 항목 수
add	Method	add(): int	끝에 빈 항목을 추가하고 새 인덱스 반환
insert	Method	insert(index)	지정 위치에 빈 항목 삽입
remove	Method	remove(index)	지정 인덱스의 항목 제거
clear	Method	clear()	모든 항목 제거
setState	Method	setState(index, function)	항목 하나의 바인딩 속성만 갱신
setOnceAnimation	Method	setOnceAnimation()	등장(staggered) 애니메이션을 1회 다시 재생
scrollToIndex	Method	scrollToIndex(index, duration)	해당 항목이 맨 위에 오도록 스크롤
getFirstVisibleIndex	Method	getFirstVisibleIndex(): int	첫 번째로 보이는 항목의 인덱스 반환
onSelected	Event	onSelected = (index) => { ... }	사용자가 항목을 탭했을 때 실행
onScrollEnd	Event	onScrollEnd = () => { ... }	스크롤이 리스트 끝에 닿았을 때 실행
onOverflowChanged	Event	onOverflowChanged = (count) => { ... }	잘린 항목 수가 바뀌었을 때 실행

Property

count

반복 렌더링할 항목 개수입니다. 설정하면 바인딩된 데이터 리스트를 그 개수에 맞춰 늘리거나 줄인 뒤 다시 그립니다. 읽으면 현재 항목 개수를 돌려줍니다.

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

Example

listviewID.count = 10;
const n = listviewID.count;

current

바인딩 스코프로 사용할 현재 항목 인덱스입니다. 설정하면 이후의 속성 쓰기가 그 항목 행을 대상으로 합니다. 읽으면 현재 인덱스를, 설정된 것이 없으면 -1을 돌려줍니다.

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

Example

listviewID.current = 2;
const cur = listviewID.current;

select

선택된 항목 인덱스입니다. 설정하면 해당 인덱스를 선택 상태로 두고, 읽으면 선택된 인덱스를, 선택된 것이 없으면 -1을 돌려줍니다.

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

Example

listviewID.select = 0;
const sel = listviewID.select;

overflowCount

overflowMode가 clip일 때 영역에 맞춰 잘려서 숨겨진 항목의 수입니다. 읽기 전용입니다.

• 종류: Property (읽기 전용)
• 타입: 정수(int)

Example

const hidden = listviewID.overflowCount;

Method

add

리스트 끝에 빈 항목을 추가하고 다시 그립니다.

• Parameters: 없음
• Returns: 정수(int) - 새로 추가된 항목의 인덱스

Example

const i = listviewID.add();

insert

지정한 위치에 빈 항목을 삽입하고 다시 그립니다.

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

Example

listviewID.insert(0);

remove

지정한 인덱스의 항목을 제거하고 다시 그립니다. 인덱스가 범위를 벗어나면 아무 일도 하지 않습니다.

• Parameters: index 정수(int) - 제거할 항목의 인덱스
• Returns: 없음

Example

listviewID.remove(0);

clear

리스트의 모든 항목을 제거하고 다시 그립니다.

• Parameters: 없음
• Returns: 없음

Example

listviewID.clear();

setState

바인딩 스코프를 지정한 인덱스의 항목으로 맞춘 상태에서 콜백을 실행한 뒤, 그 항목만 다시 그립니다. 항목 하나의 바인딩 속성을 갱신할 때 사용합니다.

• Parameters: index 정수(int) - 갱신할 항목의 인덱스 · function 콜백 함수 - index가 활성 항목인 동안 실행됨
• Returns: 없음

Example

listviewID.setState(0, () => {
  // 0번 항목의 바인딩 속성 갱신
});

setOnceAnimation

다음 빌드에서 항목 등장(staggered) 애니메이션을 한 번 다시 재생합니다. 데이터 새로고침 후 등장 효과를 다시 보여줄 때 유용합니다.

• Parameters: 없음
• Returns: 없음

Example

listviewID.setOnceAnimation();

scrollToIndex

지정한 인덱스의 항목이 맨 위에 오도록 스크롤합니다. itemExtent(항목 고정 크기)가 설정돼 있어야 동작하며(설정이 없으면 아무 일도 하지 않음), 이동 위치는 최대 스크롤 범위로 제한됩니다.

• Parameters: index 정수(int) - 스크롤해 보여줄 항목의 인덱스 · duration 정수(int) 또는 null - 애니메이션 시간(밀리초); null이거나 0 이하이면 애니메이션 없이 즉시 이동
• Returns: 없음

Example

listviewID.scrollToIndex(10, 300);

getFirstVisibleIndex

현재 첫 번째로 보이는 항목의 인덱스를 돌려줍니다. itemExtent가 설정돼 있어야 계산하며, 설정이 없으면 0을 돌려줍니다.

• Parameters: 없음
• Returns: 정수(int) - 첫 번째로 보이는 항목의 인덱스

Example

const index = listviewID.getFirstVisibleIndex();

Event

onSelected

사용자가 리스트의 항목을 탭했을 때 실행됩니다.

• 종류: Event
• 핸들러: index 정수(int) - 탭한 항목의 인덱스를 받는 콜백 함수
• Returns: 없음

Example

listviewID.onSelected = (index) => {
  // 선택한 항목 처리
};

onScrollEnd

스크롤이 리스트의 끝(바닥)에 닿았을 때 한 번 실행됩니다. 끝에서 벗어나면 다시 발화할 수 있게 준비됩니다.

• 종류: Event
• 핸들러: 인자 없는 콜백 함수
• Returns: 없음

Example

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

onOverflowChanged

clip 오버플로우 모드에서 잘린 항목 수가 바뀔 때만 실행됩니다.

• 종류: Event
• 핸들러: count 정수(int) - 새로 잘린 항목 수를 받는 콜백 함수
• Returns: 없음

Example

listviewID.onOverflowChanged = (count) => {
  // 잘린 항목 수 변화 처리
};

공통 Widget Control (모든 위젯)

노트

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