SectionList

섹션으로 구분된 리스트를 렌더링하기 위한 고성능 인터페이스로, 다음과 같은 유용한 기능을 지원한다:

• 완벽한 크로스 플랫폼 호환성
• 구성 가능한 가시성 콜백
• 리스트 헤더 지원
• 리스트 푸터 지원
• 아이템 구분자 지원
• 섹션 헤더 지원
• 섹션 구분자 지원
• 다양한 데이터와 아이템 렌더링 지원
• 새로고침을 위한 Pull to Refresh
• 스크롤 로딩

섹션 지원이 필요 없고 더 간단한 인터페이스를 원한다면 <FlatList>를 사용한다.

이 예제는 <VirtualizedList>를 편리하게 래핑한 것으로, 여기에 명시적으로 나열되지 않은 <ScrollView>의 속성도 상속받는다. 다음 사항에 주의해야 한다:

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

---

참고 자료

Props

VirtualizedList Props

VirtualizedList Props를 상속한다.

---

필수

renderItem

각 섹션의 모든 아이템에 대한 기본 렌더러. 섹션별로 재정의할 수 있다. React 엘리먼트를 반환해야 한다.

타입
function

렌더 함수는 다음과 같은 키를 가진 객체를 인자로 받는다:

• 'item' (object) - 해당 섹션의 data 키에 지정된 아이템 객체
• 'index' (number) - 섹션 내 아이템의 인덱스
• 'section' (object) - sections에 지정된 전체 섹션 객체
• 'separators' (object) - 다음 키를 가진 객체:
  • 'highlight' (function) - () => void
  • 'unhighlight' (function) - () => void
  • 'updateProps' (function) - (select, newProps) => void
    • 'select' (enum) - 가능한 값은 'leading', 'trailing'
    • 'newProps' (object)

필수

sections

렌더링할 실제 데이터로, FlatList의 data prop과 유사하다.

타입
Section 배열

extraData는 리스트가 리렌더링되도록 지시하는 마커 프로퍼티이다. (리스트가 PureComponent를 구현하기 때문) 만약 renderItem, Header, Footer 등의 함수가 data 프로퍼티 외부의 어떤 것에 의존한다면, 이곳에 추가하고 불변하게 처리한다.

타입
any

initialNumToRender

화면에 처음 렌더링할 아이템의 수를 지정한다. 이 값은 화면을 채우기에 충분하지만 너무 많지 않아야 한다. 주의할 점은 이 아이템들은 스크롤 최상단으로 이동할 때의 사용자 경험을 개선하기 위해 윈도우 렌더링 과정에서 절대 언마운트되지 않는다.

타입	기본값
number	10

inverted

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

타입	기본값
boolean	false

ItemSeparatorComponent

각 항목 사이에 렌더링되지만, 맨 위나 맨 아래에는 렌더링되지 않는다. 기본적으로 highlighted, section, 그리고 [leading/trailing][Item/Section] props가 제공된다. renderItem은 separators.highlight/unhighlight를 제공하며, 이는 highlighted prop을 업데이트한다. 또한 separators.updateProps를 사용해 커스텀 props를 추가할 수 있다. React 컴포넌트(예: SomeComponent)나 React 엘리먼트(예: <SomeComponent />)로 사용할 수 있다.

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

keyExtractor

주어진 인덱스의 아이템에 대해 고유 키를 추출하는 데 사용한다. 이 키는 캐싱과 아이템 재정렬을 추적하기 위한 React 키로 활용된다. 기본 추출기는 item.key, item.id를 차례로 확인하고, 둘 다 없을 경우 React와 마찬가지로 인덱스를 사용한다. 이 함수는 각 아이템에 대한 키를 설정하지만, 전체 섹션은 여전히 고유 키가 필요하다.

타입
(item: object, index: number) => string

ListEmptyComponent

리스트가 비어 있을 때 렌더링되는 컴포넌트이다. React 컴포넌트(예: SomeComponent) 또는 React 엘리먼트(예: <SomeComponent />) 형태로 사용할 수 있다.

타입
컴포넌트, 엘리먼트

ListFooterComponent

리스트의 가장 끝 부분에 렌더링된다. React 컴포넌트(예: SomeComponent)나 React 엘리먼트(예: <SomeComponent />) 형태로 사용할 수 있다.

타입
컴포넌트, 엘리먼트

ListHeaderComponent

리스트의 가장 처음에 렌더링된다. React 컴포넌트(예: SomeComponent)나 React 엘리먼트(예: <SomeComponent />)를 사용할 수 있다.

타입
컴포넌트, 엘리먼트

onRefresh를 제공하면 "당겨서 새로고침(Pull to Refresh)" 기능을 위한 표준 RefreshControl이 추가된다. 이때 refreshing prop도 올바르게 설정해야 한다. RefreshControl을 상단에서 오프셋하려면(예: 100 포인트만큼) progressViewOffset={100}을 사용한다.

타입
function

onViewableItemsChanged

행의 가시성이 변경될 때 호출된다. 이 동작은 viewabilityConfig 속성으로 정의된다.

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

refreshing

새로 고침 작업에서 새로운 데이터를 기다리는 동안 이 값을 true로 설정한다.

타입	기본값
boolean	false

removeClippedSubviews

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

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

타입	기본값
boolean	false

renderSectionFooter

각 섹션 하단에 렌더링된다.

타입
(info: {section: Section}) => element ｜ null

각 섹션 상단에 렌더링되는 부분이다. iOS에서는 기본적으로 ScrollView의 상단에 스틱키 고정된다. stickySectionHeadersEnabled를 참고하라.

타입
(info: {section: Section}) => element ｜ null

SectionSeparatorComponent

섹션의 상단과 하단에 렌더링되는 컴포넌트이다. (아이템 사이에만 렌더링되는 ItemSeparatorComponent와는 다르다.) 이 컴포넌트는 섹션을 위아래 헤더와 구분하는 역할을 하며, 일반적으로 ItemSeparatorComponent와 동일한 하이라이트 응답을 가진다. 또한 highlighted, [leading/trailing][Item/Section], 그리고 separators.updateProps로부터 전달된 커스텀 프로퍼티를 받는다.

타입
컴포넌트, 엘리먼트

stickySectionHeadersEnabled

섹션 헤더를 화면 상단에 스틱키 고정 상태로 유지한다. 다음 섹션 헤더가 이를 밀어낼 때까지 고정된다. iOS에서만 기본적으로 활성화되어 있으며, 해당 플랫폼의 표준 동작이다.

타입	기본값
boolean	false Android true iOS

메서드

flashScrollIndicators()

iOS

tsx

flashScrollIndicators();

스크롤 인디케이터를 잠깐 동안 표시한다.

recordInteraction()

tsx

recordInteraction();

리스트에 사용자 상호작용이 발생했음을 알려, 뷰어빌리티 계산을 트리거한다. 예를 들어, waitForInteractions가 true이고 사용자가 스크롤하지 않은 경우에 해당한다. 일반적으로 아이템 탭이나 네비게이션 액션에 의해 호출된다.

scrollToLocation()

tsx

scrollToLocation(params: SectionListScrollParams);

지정된 sectionIndex와 itemIndex(섹션 내)에 위치한 아이템을 스크롤하여 뷰어블 영역에 위치시킨다. viewPosition 값이 0이면 아이템을 상단에 위치시키고(스틱키 헤더에 가려질 수 있음), 1이면 하단에, 0.5면 중앙에 위치시킨다.

참고: getItemLayout 또는 onScrollToIndexFailed 속성을 지정하지 않으면 렌더링 윈도우 밖의 위치로 스크롤할 수 없다.

매개변수:

이름	타입
params 필수	object

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

• 'animated' (boolean) - 스크롤 시 애니메이션을 사용할지 여부. 기본값은 true이다.
• 'itemIndex' (number) - 스크롤할 아이템의 섹션 내 인덱스. 필수.
• 'sectionIndex' (number) - 스크롤할 아이템이 포함된 섹션의 인덱스. 필수.
• 'viewOffset' (number) - 최종 목표 위치에서 고정된 픽셀 수만큼 오프셋을 조정한다. 예를 들어 스틱키 헤더를 보상하기 위해 사용할 수 있다.
• 'viewPosition' (number) - 0은 지정된 인덱스의 아이템을 상단에, 1은 하단에, 0.5는 중앙에 위치시킨다.

타입 정의

섹션

특정 섹션에 렌더링할 데이터를 식별하는 객체

타입
any

속성:

이름	타입	설명
data 필수	array	이 섹션의 아이템을 렌더링하기 위한 데이터. 객체의 배열로, FlatList의 data prop과 유사하다.
key	string	섹션 재정렬을 추적하기 위한 선택적 키. 섹션을 재정렬할 계획이 없다면 기본적으로 배열 인덱스를 사용한다.
renderItem	function	이 섹션에 대해 임의의 아이템 렌더러를 정의할 수 있으며, 리스트의 기본 renderItem을 재정의한다.
ItemSeparatorComponent	component, element	이 섹션에 대해 임의의 아이템 구분자를 정의할 수 있으며, 리스트의 기본 ItemSeparatorComponent을 재정의한다.
keyExtractor	function	이 섹션에 대해 임의의 키 추출기를 정의할 수 있으며, 리스트의 기본 keyExtractor을 재정의한다.