SectionList

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

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

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

예제

이 컴포넌트는 <VirtualizedList>를 편리하게 감싼 래퍼이며, 여기에 명시적으로 나열되지 않은 <ScrollView>의 프로퍼티도 상속받는다. 다음 주의사항을 참고하라:

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

---

참고 자료

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] 프로퍼티가 제공된다. renderItem은 separators.highlight/unhighlight를 제공하며, 이는 highlighted 프로퍼티를 업데이트한다. 또한 separators.updateProps를 사용해 커스텀 프로퍼티를 추가할 수도 있다. React 컴포넌트(예: SomeComponent) 또는 React 엘리먼트(예: <SomeComponent />)로 사용할 수 있다.

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

keyExtractor

주어진 인덱스에 위치한 항목의 고유 키를 추출하는 데 사용한다. 이 키는 캐싱과 리액트가 항목 재정렬을 추적하는 데 사용된다. 기본 추출기는 item.key, item.id를 차례로 확인한 후, 리액트와 마찬가지로 인덱스를 사용한다. 이 함수는 각 항목의 키를 설정하지만, 각 섹션 전체에는 여전히 고유한 키가 필요하다.

타입
(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 속성을 올바르게 설정해야 한다. RefreshControl을 상단에서 오프셋하려면(예: 100 포인트만큼) progressViewOffset={100}을 사용한다.

타입
function

onViewableItemsChanged

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

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

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

타입	기본값
boolean	false

removeClippedSubviews

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

이 옵션은 대규모 목록의 스크롤 성능을 향상시킬 수 있습니다.

타입	기본값
boolean	false

renderSectionFooter

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

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

renderSectionHeader

각 섹션 상단에 렌더링된다. 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을 재정의한다.