본문으로 건너뛰기

버추얼라이저

Virtualizer 클래스는 TanStack Virtual의 핵심입니다. 일반적으로 프레임워크 어댑터가 버추얼라이저 인스턴스를 생성하지만, 버추얼라이저 자체는 직접 전달받습니다.

export class Virtualizer<TScrollElement = unknown, TItemElement = unknown> {
  constructor(options: VirtualizerOptions<TScrollElement, TItemElement>)
}

필수 옵션​

count​

count: number

가상화할 항목의 총개수입니다.

getScrollElement​

getScrollElement: () => TScrollElement

버추얼라이저의 스크롤 가능한 요소를 반환하는 함수입니다. 요소가 아직 준비되지 않았다면 null을 반환할 수 있습니다.

estimateSize​

estimateSize: (index: number) => number

🧠 요소를 동적으로 측정한다면 항목의 가능한 최대 크기(너비/높이, 적절한 범위 내)를 추정하는 것이 좋습니다. 이렇게 하면 버추얼라이저가 초기 위치를 더 정확하게 계산하는 데 도움이 됩니다.

이 함수에는 각 항목의 인덱스가 전달되며, 각 항목의 실제 크기(virtualItem.measureElement로 항목을 동적으로 측정할 예정이라면 추정 크기)를 반환해야 합니다. 이 측정값은 버추얼라이저의 방향에 따라 너비 또는 높이를 반환해야 합니다.

선택적 옵션​

enabled​

enabled?: boolean

false로 설정하면 scrollElement 옵저버를 비활성화하고 버추얼라이저의 상태를 초기화합니다.

debug​

debug?: boolean

true로 설정하면 디버그 로그를 활성화합니다.

initialRect​

initialRect?: Rect

scrollElement의 초기 Rect입니다. 주로 SSR 환경에서 버추얼라이저를 실행해야 할 때 유용하며, 그렇지 않으면 마운트 시 observeElementRect 구현이 initialRect를 계산합니다.

onChange​

onChange?: (instance: Virtualizer<TScrollElement, TItemElement>, sync: boolean) => void

버추얼라이저의 내부 상태가 변경될 때 실행되는 콜백 함수입니다. 버추얼라이저 인스턴스와 sync 매개변수가 전달됩니다.

sync 매개변수는 현재 스크롤이 진행 중인지 나타냅니다. 스크롤 중이면 true이고, 스크롤이 멈췄거나 크기 조정 같은 다른 작업을 수행 중이면 false입니다.

overscan​

overscan?: number

보이는 영역 위아래에 렌더링할 항목 수입니다. 이 값을 늘리면 버추얼라이저를 렌더링하는 데 걸리는 시간이 증가하지만, 스크롤할 때 버추얼라이저의 위아래에서 렌더링이 느린 빈 항목이 보일 가능성은 줄어들 수 있습니다. 기본값은 1입니다.

horizontal​

horizontal?: boolean

버추얼라이저가 가로 방향이면 true로 설정합니다.

paddingStart​

paddingStart?: number

버추얼라이저 시작 부분에 적용할 패딩(픽셀 단위)입니다.

paddingEnd​

paddingEnd?: number

버추얼라이저 끝부분에 적용할 패딩(픽셀 단위)입니다.

scrollPaddingStart​

scrollPaddingStart?: number

요소로 스크롤할 때 버추얼라이저 시작 부분에 적용할 패딩(픽셀 단위)입니다.

scrollPaddingEnd​

scrollPaddingEnd?: number

요소로 스크롤할 때 버추얼라이저 끝부분에 적용할 패딩(픽셀 단위)입니다.

initialOffset​

initialOffset?: number | (() => number)

렌더링할 때 목록이 스크롤될 위치입니다. SSR 환경에서 버추얼라이저를 렌더링하거나 버추얼라이저를 조건부로 렌더링할 때 유용합니다.

getItemKey​

getItemKey?: (index: number) => Key

이 함수에는 각 항목의 인덱스가 전달되며, 해당 항목의 고유 키를 반환해야 합니다. 기본적으로 이 함수는 항목의 인덱스를 반환하지만, 가능하면 전체 집합에서 각 항목을 고유하게 식별하는 값을 반환하도록 재정의해야 합니다.

참고: 측정에 영향을 주는 옵션이 변경되면 버추얼라이저가 측정 캐시를 자동으로 무효화하여 getTotalSize()와 기타 측정값이 최신 값을 반환하도록 합니다. 버추얼라이저는 실제로 측정에 영향을 주는 옵션을 지능적으로 추적하지만, 불필요한 재계산을 피하려면 getItemKey를 메모이제이션하는 것이 좋습니다(예: React에서 useCallback 사용).

rangeExtractor​

rangeExtractor?: (range: Range) => number[]

이 함수는 보이는 범위의 인덱스를 받아 렌더링할 인덱스 배열을 반환해야 합니다. 고정 항목, 헤더, 푸터 등을 렌더링하는 경우처럼 보이는 범위와 관계없이 버추얼라이저에서 항목을 수동으로 추가하거나 제거해야 할 때 유용합니다. 기본 범위 추출기 구현은 보이는 범위의 인덱스를 반환하며 defaultRangeExtractor로 내보냅니다.

scrollToFn​

scrollToFn?: (
  offset: number,
  options: { adjustments?: number; behavior?: 'auto' | 'smooth' },
  instance: Virtualizer<TScrollElement, TItemElement>,
) => void

선택적으로 제공할 수 있는 함수로, 제공하는 경우 scrollElement의 스크롤 동작을 구현해야 합니다. 다음 인수와 함께 호출됩니다.

  • 스크롤할 대상 offset(픽셀 단위)
  • 추정 크기와 실제 크기 사이에 차이가 있었는지(adjustments), 부드러운 애니메이션으로 스크롤을 호출했는지(behaviour)를 나타내는 객체
  • 버추얼라이저 인스턴스 자체

기본 제공 스크롤 구현은 elementScroll과 windowScroll로 내보내며, useVirtualizer 또는 useWindowVirtualizer 같은 프레임워크 어댑터 함수가 자동으로 구성합니다.

observeElementRect​

observeElementRect: (
  instance: Virtualizer<TScrollElement, TItemElement>,
  cb: (rect: Rect) => void,
) => void | (() => void)

선택적으로 제공할 수 있는 함수로, 제공하는 경우 scrollElement가 변경될 때 호출되며 scrollElement의 Rect(width와 height를 가진 객체)에 대한 초기 측정과 지속적인 관찰을 구현해야 합니다. 이 함수는 인스턴스와 함께 호출됩니다(인스턴스의 instance.scrollElement를 통해 scrollElement에도 접근할 수 있습니다. 기본 제공 구현은 observeElementRect와 observeWindowRect로 내보내며, useVirtualizer 또는 useWindowVirtualizer 같은 프레임워크 어댑터의 내보낸 함수가 자동으로 구성합니다.

observeElementOffset​

observeElementOffset: (
    instance: Virtualizer<TScrollElement, TItemElement>,
    cb: (offset: number) => void,
  ) => void | (() => void)

선택적으로 제공할 수 있는 함수로, 제공하는 경우 scrollElement가 변경될 때 호출되며 scrollElement의 스크롤 오프셋(숫자)에 대한 초기 측정과 지속적인 관찰을 구현해야 합니다. 이 함수는 인스턴스와 함께 호출됩니다(인스턴스의 instance.scrollElement를 통해 scrollElement에도 접근할 수 있습니다. 기본 제공 구현은 observeElementOffset과 observeWindowOffset으로 내보내며, useVirtualizer 또는 useWindowVirtualizer 같은 프레임워크 어댑터의 내보낸 함수가 자동으로 구성합니다.

measureElement​

measureElement?: (
  element: TItemElement,
  entry: ResizeObserverEntry | undefined,
  instance: Virtualizer<TScrollElement, TItemElement>,
) => number

이 선택적 함수는 버추얼라이저가 항목의 크기(너비 또는 높이)를 동적으로 측정해야 할 때 호출됩니다.

🧠 instance.options.horizontal을 사용하면 항목의 너비와 높이 중 무엇을 측정해야 하는지 판단할 수 있습니다.

scrollMargin​

scrollMargin?: number

이 옵션으로 스크롤 오프셋의 기준 위치를 지정할 수 있습니다. 일반적으로 이 값은 스크롤 요소의 시작 지점과 목록의 시작 지점 사이의 공간을 나타냅니다. 윈도우 버추얼라이저 앞에 헤더가 있거나 하나의 스크롤 요소 안에서 여러 버추얼라이저를 사용하는 일반적인 상황에서 특히 유용합니다. 요소를 절대 위치로 배치한다면 CSS 변환에서 scrollMargin을 고려해야 합니다.

transform: `translateY(${
   virtualRow.start - rowVirtualizer.options.scrollMargin
}px)`

scrollMargin 값을 동적으로 측정하려면 getBoundingClientRect() 또는 ResizeObserver를 사용할 수 있습니다. 가상 목록 위에 있는 항목의 높이가 달라질 수 있는 상황에서 유용합니다.

gap​

gap?: number

이 옵션으로 가상화된 목록의 항목 사이 간격을 설정할 수 있습니다. 각 항목의 마진이나 패딩을 수동으로 조정하지 않고도 항목 사이에 일관된 시각적 간격을 유지할 때 특히 유용합니다. 값은 픽셀 단위로 지정합니다.

lanes​

lanes: number

목록을 나누는 레인 수입니다(세로 목록에서는 열, 가로 목록에서는 행). 항목은 전체 크기가 가장 작은 레인에 할당됩니다. 기본적으로 항목이 레인 사이에서 이동하지 않도록 estimateSize를 기준으로 레인 할당을 즉시 캐시합니다(이 동작을 변경하려면 아래의 laneAssignmentMode를 참고합니다).

laneAssignmentMode​

laneAssignmentMode?: 'estimate' | 'measured'

기본값: 'estimate'

메이슨리 레이아웃에서 레인 할당을 캐시하는 시점을 제어합니다.

  • 'estimate'(기본값): estimateSize를 기준으로 레인 할당을 즉시 캐시합니다. 항목이 레인 사이에서 이동하는 것을 막지만, 추정값이 부정확하면 할당이 최적이 아닐 수 있습니다.
  • 'measured': measureElement를 통해 항목을 측정할 때까지 레인 캐싱을 연기하므로 할당에 실제 측정 크기가 반영됩니다. 초기 측정 후 레인이 캐시되어 안정적으로 유지됩니다.

anchorTo​

anchorTo?: 'start' | 'end'

기본값: 'start'

목록 데이터가 변경될 때 스크롤 가능한 콘텐츠의 어느 쪽을 안정적인 앵커로 취급할지 제어합니다. 기본값인 'start'는 TanStack Virtual의 기존 위쪽/왼쪽 앵커 동작을 유지합니다.

채팅, 로그, 역순/반전 피드에는 anchorTo: 'end'를 설정합니다. 끝 앵커 모드에서는 이전 항목을 앞에 추가할 때 버추얼라이저가 현재 보이는 항목을 안정적으로 유지하며, 스트리밍 출력 중 마지막 항목이 커질 때 끝에 고정된 뷰포트를 계속 고정합니다. 전체 패턴은 채팅 가이드를 참고합니다.

앞에 추가할 때의 안정성을 위해 각 항목의 영구 id를 기반으로 안정적인 getItemKey를 사용합니다. 항목이 이동한 뒤에는 인덱스 키로 앞에 추가하는 작업과 뒤에 추가하는 작업을 구분할 수 없습니다.

followOnAppend​

followOnAppend?: boolean | 'auto' | 'smooth' | 'instant'

기본값: false

anchorTo: 'end'와 함께 사용할 때 새 항목을 뒤에 추가한 후 버추얼라이저가 끝으로 스크롤할지 제어합니다. 추가하기 전에 뷰포트가 이미 끝에 있었던 경우에만 따라갑니다. 기록을 읽기 위해 위로 스크롤한 사용자는 아래로 끌려가지 않습니다.

true를 전달하는 것은 'auto'를 전달하는 것과 같습니다. 스크롤 동작을 전달하면 따라갈 때 해당 동작을 사용합니다.

이 옵션은 앞에 추가한 항목을 따라가지 않습니다. 뒤에 추가된 출력만 따라가며, 추가하기 전에 뷰포트가 이미 끝에서 scrollEndThreshold 이내에 있었던 경우에만 동작합니다.

scrollEndThreshold​

scrollEndThreshold?: number

기본값: 1

isAtEnd()와 followOnAppend가 뷰포트가 고정된 것으로 간주할 만큼 끝에 가까운지 판단할 때 사용하는 픽셀 임계값입니다.

isScrollingResetDelay​

isScrollingResetDelay: number

이 옵션으로 마지막 스크롤 이벤트 이후 isScrolling 인스턴스 속성을 초기화하기까지 기다릴 시간을 지정할 수 있습니다. 기본값은 150밀리초입니다.

모든 브라우저가 scrollEnd 이벤트를 일관되게 지원할 때까지 브라우저별 스크롤 동작을 처리하는 신뢰할 수 있는 메커니즘이 필요하므로 이 옵션을 구현했습니다.

useScrollendEvent​

useScrollendEvent: boolean

스크롤 중지를 감지할 때 네이티브 scrollend 이벤트를 사용할지 결정합니다. false로 설정하면 디바운스한 대체 방식을 사용하여 isScrollingResetDelay 밀리초 후 isScrolling 인스턴스 속성을 초기화합니다. 기본값은 false입니다.

모든 브라우저가 scrollEnd 이벤트를 일관되게 지원할 때까지 브라우저별 스크롤 동작을 처리하는 신뢰할 수 있는 메커니즘이 필요하므로 이 옵션을 구현했습니다.

isRtl​

isRtl: boolean

오른쪽에서 왼쪽으로 쓰는 언어 로케일을 지원하기 위해 가로 스크롤을 반전할지 여부입니다.

initialMeasurementsCache​

initialMeasurementsCache: Array<VirtualItem>

기본값: []

마운트 시 버추얼라이저를 초기화하는 데 사용할, 이전에 캡처한 측정된 항목 크기의 스냅샷(takeSnapshot()에서 가져옴)입니다. 탐색 후 스크롤 위치를 복원할 때 유용합니다. takeSnapshot()의 결과와 현재 scrollOffset을 라우트 상태에 유지한 다음, 이를 initialMeasurementsCache와 initialOffset으로 다시 전달하면 모든 항목을 처음부터 다시 측정하지 않고 사용자를 같은 위치로 이동시킬 수 있습니다.

캐시에 없는 항목은 estimateSize로 대체하며, 캐시에 있는 항목은 측정된 size를 복원합니다. 캐시는 마운트 후 처음 getMeasurements()를 호출할 때 한 번만 사용됩니다.

useAnimationFrameWithResizeObserver​

useAnimationFrameWithResizeObserver: boolean

기본값: false

활성화하면 requestAnimationFrame을 사용하여 ResizeObserver 측정 처리를 다음 애니메이션 프레임으로 연기합니다.

중요: 대부분의 경우 일반적으로 이 옵션을 활성화하면 안 됩니다. ResizeObserver 콜백은 이미 브라우저 렌더링 파이프라인의 최적 시점(레이아웃 이후, 페인트 이전)에 실행되며, 콜백에 제공되는 측정값은 추가 리플로를 일으키지 않고 브라우저에서 미리 계산됩니다.

잠재적 사용 사례:

  • 크기 변경에 대응하여 많은 DOM 변경을 수행하고 이를 다음 렌더링 주기와 함께 배칭하려는 경우
  • "전달되지 않은 알림이 있는 상태에서 ResizeObserver 루프가 완료됨" 오류의 해결 방법으로 사용하는 경우(다만 일반적으로는 수정해야 할 더 근본적인 문제가 있음을 나타냅니다)

트레이드오프:

  • 약 16ms의 지연 추가: 측정이 다음 프레임으로 연기되어 시각적 결함, 오래된 측정값 또는 상호작용 가능 시점 지연이 발생할 수 있습니다.
  • 배칭 이점 없음: ResizeObserver는 이미 여러 요소의 크기 조정을 하나의 콜백으로 배칭합니다.
  • 최적화 무효화: 브라우저가 이미 측정값을 동기적으로 계산했으므로, 측정을 연기해도 값을 읽을 때 성능상 이점이 없습니다.

명확한 이유가 있고 사용 사례가 개선된다는 사실을 측정으로 확인한 경우에만 이 옵션을 활성화합니다.

useCachedMeasurements​

useCachedMeasurements?: boolean

기본값: false

활성화하면 기본 measureElement 구현이 DOM 측정을 건너뛰고 각 항목에 대해 이전에 캐시한 크기를 반환합니다(캐시된 크기가 없으면 estimateSize로 대체합니다).

가상화된 목록이 일시적으로 숨겨질 때(예: 부모 요소에 display: none을 적용할 때) 유용합니다. 이 옵션이 없으면 목록이 숨겨질 때 ResizeObserver가 모든 항목에 크기 0을 전달하여 모든 측정값을 초기화합니다. 목록이 다시 표시되면 항목을 재측정해야 할 수 있으며, 이로 인해 레이아웃 이동이 발생할 수 있습니다.

사용법: 목록을 숨기기 전에 이 옵션을 true로 전환하고, 표시할 때 다시 false로 전환합니다. ResizeObserver는 계속 연결되어 있으므로 플래그를 끄고 요소가 다시 표시되면 실제 측정이 자동으로 재개됩니다.

⚠️ 이 옵션은 기본 measureElement에만 영향을 줍니다. 사용자 정의 measureElement를 제공한다면 이 경우를 직접 처리해야 합니다.

버추얼라이저 인스턴스​

버추얼라이저 인스턴스에서 다음 속성과 메서드를 사용할 수 있습니다.

options​

options: readonly Required<VirtualizerOptions<TScrollElement, TItemElement>>

버추얼라이저의 현재 옵션입니다. 이 속성은 프레임워크 어댑터를 통해 업데이트되며 읽기 전용입니다.

scrollElement​

scrollElement: readonly TScrollElement | null

버추얼라이저의 현재 scrollElement입니다. 이 속성은 프레임워크 어댑터를 통해 업데이트되며 읽기 전용입니다.

getVirtualItems​

type getVirtualItems = () => VirtualItem[]

버추얼라이저의 현재 상태에 해당하는 가상 항목을 반환합니다.

getVirtualIndexes​

type getVirtualIndexes = () => number[]

버추얼라이저의 현재 상태에 해당하는 가상 행 인덱스를 반환합니다.

scrollToOffset​

scrollToOffset: (
  toOffset: number,
  options?: {
    align?: 'start' | 'center' | 'end' | 'auto',
    behavior?: 'auto' | 'smooth'
  }
) => void

버추얼라이저를 지정한 픽셀 오프셋으로 스크롤합니다. 선택적으로 정렬 모드를 전달하여 스크롤을 scrollElement의 특정 부분에 맞출 수 있습니다.

scrollToIndex​

scrollToIndex: (
  index: number,
  options?: {
    align?: 'start' | 'center' | 'end' | 'auto',
    behavior?: 'auto' | 'smooth'
  }
) => void

버추얼라이저를 지정한 인덱스의 항목으로 스크롤합니다. 선택적으로 정렬 모드를 전달하여 스크롤을 scrollElement의 특정 부분에 맞출 수 있습니다.

🧠 부드럽게 스크롤하는 동안 버추얼라이저는 스크롤 대상 주변의 버퍼 범위 안에 있는 항목만 측정합니다. 대상에서 멀리 떨어진 항목은 크기 변경으로 인해 대상 위치가 이동하여 부드러운 애니메이션이 깨지지 않도록 건너뜁니다.

따라서 부드러운 스크롤에 권장되는 레이아웃 전략은 블록 변환입니다. 각 항목을 절대 위치로 독립적으로 배치하는 대신 첫 번째 항목의 start 오프셋을 사용해 렌더링된 전체 블록을 변환합니다. 이렇게 하면 일부 측정을 건너뛰더라도 항목이 서로 올바른 상대 위치를 유지합니다.

scrollBy​

scrollBy: (
  delta: number,
  options?: {
    behavior?: 'auto' | 'smooth'
  }
) => void

현재 스크롤 위치를 기준으로 지정한 픽셀 수만큼 버추얼라이저를 스크롤합니다.

scrollToEnd​

scrollToEnd: (
  options?: {
    behavior?: 'auto' | 'smooth' | 'instant'
  }
) => void

버추얼라이저를 콘텐츠의 끝으로 스크롤합니다. 세로 목록에서는 아래쪽이고 가로 목록에서는 오른쪽 가장자리입니다.

채팅 및 로그 뷰의 "최신 항목으로 이동" 컨트롤에 유용합니다.

getDistanceFromEnd​

getDistanceFromEnd: () => number

가상화된 콘텐츠의 끝에서 현재 위치까지의 픽셀 거리를 반환합니다.

세로 목록에서는 아래쪽 끝으로부터의 거리입니다.

isAtEnd​

isAtEnd: (threshold?: number) => boolean

뷰포트가 끝에서 threshold 픽셀 이내에 있는지 반환합니다. 임계값을 제공하지 않으면 scrollEndThreshold를 사용합니다.

이를 사용하여 "최신 항목으로 이동" UI를 표시할지 또는 들어오는 출력을 고정된 것으로 처리할지 결정합니다.

getTotalSize​

getTotalSize: () => number

가상화된 항목의 전체 크기를 픽셀 단위로 반환합니다. 요소가 렌더링될 때 동적으로 측정하도록 선택하면 이 측정값이 점진적으로 변경됩니다.

measure​

measure: () => void

이전 항목의 모든 측정값을 초기화합니다.

takeSnapshot​

takeSnapshot: () => Array<VirtualItem>

현재 측정된 항목의 스냅샷을 일반 VirtualItem 객체로 반환하며, 상태 저장소를 통해 왕복 처리하고 다시 마운트할 때 initialMeasurementsCache로 다시 전달하기에 적합합니다. 현재 scrollOffset과 함께 사용하면 탐색 후 정확한 스크롤 위치를 복원할 수 있습니다.

소비자가 실제로 렌더링하여 측정한 항목만 스냅샷에 포함되며, 측정하지 않은 항목은 복원할 때 estimateSize로 대체됩니다. 측정한 항목이 없으면 빈 배열을 반환합니다.

// Capture state on unmount
const snapshot = virtualizer.takeSnapshot()
const offset = virtualizer.scrollOffset
sessionStorage.setItem('myList', JSON.stringify({ snapshot, offset }))

// Restore on remount
const saved = JSON.parse(sessionStorage.getItem('myList') ?? 'null')
useVirtualizer({
  count: items.length,
  estimateSize: () => 50,
  getScrollElement: () => parentRef.current,
  initialMeasurementsCache: saved?.snapshot,
  initialOffset: saved?.offset,
})

measureElement​

measureElement: (el: TItemElement | null) => void

구성한 measureElement 버추얼라이저 옵션을 사용하여 요소를 측정합니다. 컴포넌트가 렌더링될 때 버추얼라이저 마크업에서 이를 호출하고(예: React의 ref 콜백 prop과 비슷한 방식 사용) data-index도 추가해야 합니다.

 <div
  key={virtualRow.key}
  data-index={virtualRow.index}
  ref={virtualizer.measureElement}
  style={...}
>...</div>

기본적으로 measureElement 버추얼라이저 옵션은 getBoundingClientRect()로 요소를 측정하도록 구성됩니다.

resizeItem​

resizeItem: (index: number, size: number) => void

가상화된 항목의 크기를 수동으로 변경합니다. 이 함수를 사용하여 해당 인덱스에 대해 계산된 크기를 수동으로 설정합니다. 사용자 정의 모핑 전환을 사용하면서 모핑된 항목의 크기를 미리 알고 있는 경우에 유용합니다.

재렌더링을 줄이기 위해 Virtualizer.measureElement 대신 스로틀된 ResizeObserver와 함께 이 메서드를 사용할 수도 있습니다.

⚠️ Virtualizer.measureElement로 항목을 관찰하는 동안 해당 항목의 크기를 수동으로 변경하면 Virtualizer.measureElement도 크기를 변경하므로 예측할 수 없는 동작이 발생합니다. 다만 같은 버추얼라이저 인스턴스에서 서로 다른 항목 인덱스에 resizeItem과 measureElement 중 하나씩 사용할 수 있습니다.

scrollRect​

scrollRect: Rect

스크롤 요소의 현재 Rect입니다.

shouldAdjustScrollPositionOnItemSizeChange​

shouldAdjustScrollPositionOnItemSizeChange: undefined | ((item: VirtualItem, delta: number, instance: Virtualizer<TScrollElement, TItemElement>) => boolean)

뷰포트 위에 있는 항목의 측정 크기가 추정 크기와 다를 때 실행되는 스크롤 위치 조정을 세밀하게 제어합니다. 기본적으로 버추얼라이저는 사용자가 뒤로 스크롤하고 있지 않을 때만 이 보정을 적용하여 잘 알려진 "위로 스크롤할 때 항목이 튀는" 끊김 현상을 방지합니다. 뒤로 스크롤하는 동안 보정을 적용하거나 다른 상황에서도 보정을 건너뛰는 경우처럼 기본 동작을 재정의하려는 경우에만 이 콜백을 제공합니다.

이는 VirtualizerOptions 옵션이 아니라 버추얼라이저 인스턴스 속성입니다. 버추얼라이저를 생성한 후 버추얼라이저 인스턴스에 직접 할당합니다.

virtualizer.shouldAdjustScrollPositionOnItemSizeChange = (
  item,
  delta,
  instance,
) => {
  return item.start < instance.getScrollOffset() + instance.scrollAdjustments
}

콜백은 크기가 조정된 item, 크기 delta, instance를 받습니다. 스크롤 조정을 적용하려면 true를, 건너뛰려면 false를 반환합니다.

iOS WebKit에서는 이 콜백과 관계없이 화면에 손가락이 닿아 있는 동안, 모멘텀 스크롤 중, 탄성 오버스크롤 바운스 중에 스크롤 위치 쓰기를 연기합니다. 스크롤이 안정되면 누적 델타를 단일 쓰기로 반영하여 iOS의 네이티브 모멘텀 물리 동작을 유지합니다.

isScrolling​

isScrolling: boolean

목록이 현재 스크롤 중인지 나타내는 불리언 플래그입니다.

scrollDirection​

scrollDirection: 'forward' | 'backward' | null

이 옵션은 스크롤 방향을 나타냅니다. 가능한 값은 아래로 스크롤할 때의 'forward'와 위로 스크롤할 때의 'backward'입니다. 활성 스크롤이 없으면 값은 null로 설정됩니다.

scrollOffset​

scrollOffset: number

이 옵션은 스크롤 축을 따른 현재 스크롤 위치를 나타냅니다. 스크롤 가능 영역의 시작 지점부터 픽셀 단위로 측정합니다.