VirtualizedList

<FlatList>와 <SectionList> 컴포넌트는 더 편리하고 문서화가 잘 되어 있다. 일반적으로 FlatList가 제공하는 유연성보다 더 많은 제어가 필요할 때, 예를 들어 일반 배열 대신 불변 데이터를 사용해야 할 때 이 컴포넌트를 활용한다.

가상화는 활성 아이템의 유한한 렌더링 윈도우를 유지하고, 윈도우 밖의 아이템을 적절한 크기의 빈 공간으로 대체함으로써 대규모 리스트의 메모리 소비와 성능을 크게 개선한다. 윈도우는 스크롤 동작에 맞춰 조정되며, 아이템은 보이는 영역에서 멀리 떨어져 있을 경우 낮은 우선순위로(실행 중인 상호작용 이후에) 점진적으로 렌더링되고, 그렇지 않으면 높은 우선순위로 렌더링되어 빈 공간이 보이는 가능성을 최소화한다.

TypeScript

JavaScript

---

몇 가지 주의사항:

• 렌더링 윈도우에서 벗어나 스크롤되는 콘텐츠의 내부 상태는 유지되지 않는다. 모든 데이터를 아이템 데이터나 Flux, Redux, Relay와 같은 외부 저장소에 담아야 한다.
• 이 컴포넌트는 PureComponent이므로 props가 얕은 비교에서 동일하면 리렌더링되지 않는다. renderItem 함수가 의존하는 모든 데이터를 업데이트 후에 ===이 아닌 prop(예: extraData)으로 전달해야 한다. 그렇지 않으면 UI가 변경 사항에 반응하지 않을 수 있다. 이는 data prop과 부모 컴포넌트의 상태를 포함한다.
• 메모리를 절약하고 부드러운 스크롤을 위해 콘텐츠는 비동기적으로 화면 밖에서 렌더링된다. 이는 스크롤 속도가 채우기 속도보다 빠를 경우 잠시 빈 콘텐츠가 보일 수 있음을 의미한다. 이는 각 애플리케이션의 요구에 맞게 조정할 수 있는 트레이드오프이며, 우리는 이를 개선하기 위해 내부적으로 작업 중이다.
• 기본적으로 리스트는 각 아이템의 key prop을 찾아 React key로 사용한다. 또는 커스텀 keyExtractor prop을 제공할 수 있다.

---

참조

Props

ScrollView Props

ScrollView Props를 상속받는다.

data

getItem과 getItemCount에 전달되는 불투명한 데이터 타입으로, 아이템을 가져오는 데 사용한다.

타입
any

필수

getItem

tsx

(data: any, index: number) => any;

어떤 종류의 데이터 블롭에서도 아이템을 추출하기 위한 범용 접근자이다.

타입
함수

필수

getItemCount

tsx

(data: any) => number;

데이터 블롭에 포함된 항목의 개수를 반환한다.

타입
함수

필수

renderItem

tsx

(info: any) => ?React.Element<any>

data에서 가져온 항목을 리스트로 렌더링한다.

타입
함수

CellRendererComponent

CellRendererComponent는 renderItem이나 ListItemComponent로 렌더링된 셀들이 기본 ScrollView에 배치될 때 어떻게 감싸질지 커스텀하게 설정할 수 있게 해준다. 이 컴포넌트는 셀 내부의 변화를 VirtualizedList에 알리는 이벤트 핸들러를 반드시 받아들여야 한다.

타입
React.ComponentType<CellRendererProps>

ItemSeparatorComponent

각 항목 사이에 렌더링되지만, 맨 위나 맨 아래에는 렌더링되지 않는다. 기본적으로 highlighted와 leadingItem 프로퍼티가 제공된다. renderItem은 separators.highlight와 separators.unhighlight를 제공하며, 이를 통해 highlighted 프로퍼티를 업데이트할 수 있다. 또한 separators.updateProps를 사용해 커스텀 프로퍼티를 추가할 수도 있다. React 컴포넌트(예: SomeComponent) 또는 React 엘리먼트(예: <SomeComponent />)로 사용할 수 있다.

타입
컴포넌트, 함수, 엘리먼트

ListEmptyComponent

리스트가 비어 있을 때 렌더링된다. 리액트 컴포넌트(예: SomeComponent) 또는 리액트 엘리먼트(예: <SomeComponent />)로 지정할 수 있다.

타입
컴포넌트, 엘리먼트

ListItemComponent

각 데이터 항목은 이 엘리먼트를 사용해 렌더링된다. React 컴포넌트 클래스 또는 렌더링 함수로 구성할 수 있다.

타입
컴포넌트, 함수

ListFooterComponent

모든 항목의 하단에 렌더링된다. React 컴포넌트(예: SomeComponent) 또는 React 엘리먼트(예: <SomeComponent />)로 사용할 수 있다.

타입
컴포넌트, 엘리먼트

ListFooterComponentStyle

ListFooterComponent 내부 뷰를 위한 스타일 설정.

타입	필수 여부
ViewStyleProp	아니오

ListHeaderComponent

모든 아이템 상단에 렌더링되는 컴포넌트다. React 컴포넌트(예: SomeComponent)나 React 엘리먼트(예: <SomeComponent />) 형태로 사용할 수 있다.

타입
컴포넌트, 엘리먼트

ListHeaderComponentStyle

ListHeaderComponent 내부 View에 대한 스타일링.

타입
View 스타일

debug는 사용법과 구현 모두를 디버깅하는 데 도움이 되는 추가 로깅과 시각적 오버레이를 활성화한다. 하지만 이는 성능에 상당한 영향을 미칠 수 있다.

타입
boolean

disableVirtualization

더 이상 사용되지 않음. 가상화는 성능과 메모리 최적화를 크게 향상시킨다. 하지만 렌더링 윈도우 밖에 있는 React 인스턴스를 완전히 언마운트한다. 이 기능을 비활성화하는 경우는 디버깅 목적으로만 한정해야 한다.

타입
boolean

extraData

리스트가 리렌더링되도록 알려주는 마커 속성이다. 리스트가 PureComponent를 구현하기 때문에, renderItem, Header, Footer 등과 같은 함수가 data prop 외부의 어떤 것에 의존한다면, 이 속성에 넣고 불변하게 처리해야 한다.

타입
any

getItemLayout

tsx

(
  data: any,
  index: number,
) => {length: number, offset: number, index: number}

타입
function

horizontal이 true로 설정되면, 아이템을 세로로 쌓는 대신 가로로 나란히 렌더링한다.

타입
boolean

initialNumToRender

화면에 처음으로 렌더링할 항목의 수를 지정한다. 화면을 채우기에 충분한 양이어야 하지만 너무 많지 않도록 조절해야 한다. 이 항목들은 스크롤 상단 이동 시 사용자 경험을 향상시키기 위해 윈도우 렌더링 과정에서 절대 언마운트되지 않는다.

타입	기본값
number	10

initialScrollIndex

첫 번째 항목부터 시작하지 않고, initialScrollIndex에서 시작한다. 이 설정은 첫 번째 initialNumToRender 항목을 항상 렌더링하는 "맨 위로 스크롤" 최적화를 비활성화하고, 대신 이 초기 인덱스부터 항목을 즉시 렌더링한다. 이 기능을 사용하려면 getItemLayout을 구현해야 한다.

타입
number

inverted

스크롤 방향을 반대로 설정한다. -1 스케일 변환을 사용하여 구현한다.

타입
boolean

keyExtractor

tsx

(item: any, index: number) => string;

주어진 아이템과 인덱스에 대해 고유한 키를 추출하는 데 사용된다. 이 키는 캐싱과 아이템 재정렬을 추적하기 위한 리액트 키로 활용된다. 기본 추출기는 item.key, item.id를 차례로 확인하고, 둘 다 없는 경우 리액트와 마찬가지로 인덱스를 사용한다.

타입
함수

maxToRenderPerBatch

한 번에 렌더링할 항목의 최대 개수를 설정한다. 한 번에 많은 항목을 렌더링하면 채우기 속도가 빨라지지만, 렌더링 작업이 버튼 터치나 다른 상호작용에 대한 응답을 방해할 수 있어 반응성이 떨어질 수 있다.

타입
number

onEndReached

리스트의 논리적 끝에서 onEndReachedThreshold 범위 내로 스크롤 위치가 들어오면 한 번 호출된다.

타입
(info: {distanceFromEnd: number}) => void

onEndReachedThreshold

리스트의 끝에서 얼마나 떨어져 있을 때 onEndReached 콜백을 트리거할지 결정하는 값이다. 이 값은 리스트의 보이는 길이 단위로 측정된다. 예를 들어, 값이 0.5라면 리스트의 끝이 보이는 길이의 절반 이내에 도달했을 때 onEndReached가 트리거된다.

타입	기본값
number	2

onRefresh

tsx

() => void;

이 속성을 제공하면 "당겨서 새로고침" 기능을 위해 표준 RefreshControl이 추가된다. 이때 refreshing 속성도 올바르게 설정해야 한다.

타입
function

onScrollToIndexFailed

tsx

(info: {
  index: number,
  highestMeasuredFrameIndex: number,
  averageItemLength: number,
}) => void;

아직 측정되지 않은 인덱스로 스크롤하려고 할 때 실패를 처리하기 위해 사용한다. 일반적으로 권장하는 방법은 직접 오프셋을 계산하여 scrollTo를 호출하거나, 가능한 한 끝까지 스크롤한 후 더 많은 아이템이 렌더링된 후에 다시 시도하는 것이다.

타입
function

onStartReached

리스트의 논리적 시작점에서 onStartReachedThreshold 범위 내로 스크롤 위치가 들어오면 한 번 호출된다.

타입
(info: {distanceFromStart: number}) => void

onStartReachedThreshold

리스트의 시작 부분에서 콘텐츠의 선두가 얼마나 떨어져 있어야 onStartReached 콜백이 트리거되는지를 나타낸다. 이 값은 리스트의 가시 길이 단위로 측정된다. 예를 들어, 값이 0.5라면 콘텐츠의 시작 부분이 리스트의 가시 길이 절반 이내에 있을 때 onStartReached가 트리거된다.

타입	기본값
number	2

onViewableItemsChanged

행의 가시성이 변경될 때 호출된다. viewabilityConfig prop에 정의된 기준에 따라 동작한다.

타입
(callback: {changed: ViewToken[], viewableItems: ViewToken[]}) => void

persistentScrollbar

타입
bool

progressViewOffset

로딩 인디케이터가 올바르게 표시되도록 오프셋이 필요할 때 이 값을 설정한다.

타입
number

refreshControl

커스텀 리프레시 컨트롤 엘리먼트. 이 값을 설정하면 내장된 기본 <RefreshControl> 컴포넌트를 대체한다. 이 경우 onRefresh와 refreshing props는 무시된다. 이 기능은 세로 방향의 VirtualizedList에서만 동작한다.

타입
element

refreshing

새로운 데이터를 가져오기 위해 새로고침을 기다리는 동안 이 값을 true로 설정한다.

타입
boolean

removeClippedSubviews

이 기능은 긴 목록의 스크롤 성능을 향상시킬 수 있다.

참고: 특정 상황에서 버그(콘텐츠 누락)가 발생할 수 있으므로 사용에 주의가 필요하다.

타입
boolean

renderScrollComponent

tsx

(props: object) => element;

커스텀 스크롤 컴포넌트를 렌더링한다. 예를 들어, 다른 스타일의 RefreshControl을 사용할 수 있다.

타입
함수

viewabilityConfig

ViewabilityHelper.js 파일에서 플로우 타입과 추가 문서를 확인할 수 있다.

타입
ViewabilityConfig

viewabilityConfigCallbackPairs

ViewabilityConfig와 onViewableItemsChanged의 쌍으로 이루어진 리스트다. 특정 ViewabilityConfig의 조건이 충족되면, 해당하는 onViewableItemsChanged가 호출된다. 자세한 플로우 타입과 추가 문서는 ViewabilityHelper.js를 참고한다.

타입
ViewabilityConfigCallbackPair 배열

updateCellsBatchingPeriod

화면에서 멀리 떨어진 아이템을 렌더링할 때, 저우선순위 아이템 렌더링 배치 간의 시간 간격을 설정한다. maxToRenderPerBatch와 마찬가지로 렌더링 속도와 응답성 사이의 균형을 조절한다.

타입
number

windowSize

화면 밖에 렌더링할 최대 아이템 수를 결정한다. 단위는 화면 길이이다. 예를 들어, 리스트가 화면을 꽉 채우고 있다면 windowSize={21}(기본값)은 현재 보이는 화면 영역과 뷰포트 위아래로 각각 10개 화면 분량을 추가로 렌더링한다. 이 값을 줄이면 메모리 사용량이 감소하고 성능이 개선될 수 있지만, 빠르게 스크롤할 때 잠시 렌더링되지 않은 빈 영역이 나타날 가능성이 커진다.

타입
number

메서드

flashScrollIndicators()

tsx

flashScrollIndicators();

getScrollableNode()

tsx

getScrollableNode(): any;

getScrollRef()

tsx

getScrollRef():
  | React.ElementRef<typeof ScrollView>
  | React.ElementRef<typeof View>
  | null;

getScrollResponder()

tsx

getScrollResponder () => ScrollResponderMixin | null;

기본 스크롤 응답자에 대한 핸들을 제공한다. this._scrollRef가 ScrollView가 아닐 수도 있으므로, getScrollResponder를 호출하기 전에 해당 메서드가 존재하는지 확인해야 한다.

scrollToEnd()

tsx

scrollToEnd(params?: {animated?: boolean});

컨텐츠의 끝까지 스크롤한다. getItemLayout 속성이 없으면 부드럽지 않을 수 있다.

인자:

이름	타입
params	object

유효한 params 키는 다음과 같다:

• 'animated' (boolean) - 스크롤 시 애니메이션을 적용할지 여부. 기본값은 true이다.

scrollToIndex()

tsx

scrollToIndex(params: {
  index: number;
  animated?: boolean;
  viewOffset?: number;
  viewPosition?: number;
});

params에 유효한 값은 다음과 같다:

• 'index' (number). 필수.
• 'animated' (boolean). 선택 사항.
• 'viewOffset' (number). 선택 사항.
• 'viewPosition' (number). 선택 사항.

---

scrollToItem()

tsx

scrollToItem(params: {
  item: ItemT;
  animated?: boolean;
  viewOffset?: number;
  viewPosition?: number;
);

유효한 params는 다음과 같이 구성된다:

• 'item' (Item). 필수 항목.
• 'animated' (boolean). 선택 항목.
• 'viewOffset' (number). 선택 항목.
• 'viewPosition' (number). 선택 항목.

scrollToOffset()

tsx

scrollToOffset(params: {
  offset: number;
  animated?: boolean;
});

리스트에서 특정 콘텐츠 픽셀 오프셋으로 스크롤한다.

offset 파라미터는 스크롤할 오프셋 값을 지정한다. horizontal이 true인 경우, 오프셋은 x값을 의미한다. 그 외의 경우에는 오프셋이 y값을 나타낸다.

animated 파라미터는 기본값이 true이며, 스크롤 시 애니메이션을 사용할지 여부를 결정한다.