GestureViewer Props

`renderItem`

renderItem은 data의 각 아이템을 렌더링하며, renderItem(item, index, { isActive, setItemDimensions }) 형태로 세 번째 인자에서 isActive와 setItemDimensions를 제공합니다.

비디오 재생처럼 활성 아이템에서만 필요한 작업은 isActive로 제어할 수 있습니다. 동작 방식과 예시는 renderItem 활성 상태 (isActive)를 참고하세요.

setItemDimensions({ width, height })는 렌더링된 콘텐츠의 원본 크기를 알 수 있게 된 뒤 호출하세요. 예시와 호출 시점은 콘텐츠 크기 가이드를 참고하세요.

`enableLoop` (기본값: `false`)

루프 모드를 활성화합니다. true일 때 마지막 아이템에서 다음으로 가면 첫 번째로, 첫 번째에서 이전으로 가면 마지막으로 돌아갑니다.

import { GestureViewer } from 'react-native-gesture-image-viewer';

function App() {
  return (
    <GestureViewer
      enableLoop={true} 
    />
  );
}

`enableSnapMode` (기본값: `false`)

스냅 스크롤 모드를 활성화합니다.

false (기본값): 페이징 모드 (pagingEnabled: true)
- 전체 화면 크기 단위로 스크롤됩니다
true: 스냅 모드 (snapToInterval 자동 계산)
- snapToInterval이 width와 itemSpacing 값을 기반으로 자동 계산됩니다
- 아이템 간격이 필요할 때 이 옵션을 사용하세요

import { GestureViewer } from 'react-native-gesture-image-viewer';

function App() {
  return (
    <GestureViewer
      data={data}
      renderItem={renderItem}
      enableSnapMode={true} 
    />
  );
}

`itemSpacing` (기본값: `0`)

아이템 간의 간격을 픽셀 단위로 설정합니다. enableSnapMode가 true일 때만 적용됩니다.

import { GestureViewer } from 'react-native-gesture-image-viewer';

function App() {
  return (
    <GestureViewer
      data={data}
      renderItem={renderItem}
      enableSnapMode={true}
      itemSpacing={16} // 16px spacing between items
    />
  );
}

`autoPlay` (기본값: `false`)

자동 재생 모드를 활성화합니다. true일 때 지정된 간격 후 다음 아이템으로 자동으로 재생됩니다.

enableLoop이 활성화되면 마지막 아이템에서 다음으로 가면 첫 번째로, 첫 번째에서 이전으로 가면 마지막으로 돌아갑니다.
enableLoop이 비활성화되면 마지막 아이템에서 정지됩니다.
아이템이 하나만 있을 때 자동 재생이 비활성화됩니다.
줌 또는 회전 제스처가 감지되면 자동 재생이 일시 중지됩니다.

import { GestureViewer } from 'react-native-gesture-image-viewer';

function App() {
  return (
    <GestureViewer
      autoPlay={true}
    />
  );
}

`autoPlayInterval` (기본값: `3000`)

자동 재생 간격을 밀리초 단위로 설정합니다.
양수 정수여야 합니다. 값이 250ms 미만이면 런타임에서 250ms로 제한됩니다.

import { GestureViewer } from 'react-native-gesture-image-viewer';

function App() {
  return (
    <GestureViewer
      autoPlay={true}
      autoPlayInterval={3000}
    />
  );
}

`onSingleTap`

뷰어에서 싱글 탭이 확정되면 실행됩니다. 헤더, 푸터, 캡션, 액션 버튼처럼 뷰어 컨트롤 UI를 토글할 때 유용하며, 뷰어 위에 별도의 pressable을 덮지 않아도 됩니다.

더블 탭 줌이 활성화되어 있으면 더블 탭이 아닌지 확인한 뒤 실행되므로 약간 늦게 호출될 수 있습니다
스와이프, 핀치, dismiss, 더블 탭 줌 제스처에서는 호출되지 않습니다

import { GestureViewer } from 'react-native-gesture-image-viewer';

function App() {
  const [showControls, setShowControls] = useState(true);

  return (
    <GestureViewer
      data={images}
      renderItem={renderImage}
      onSingleTap={() => setShowControls((prev) => !prev)} 
    />
  );
}

`getItemDimensions`

콘텐츠의 원본 크기를 이미 알고 있을 때 반환합니다. renderItem에서 setItemDimensions로 런타임에 등록한 크기가 우선합니다. 예시는 콘텐츠 크기 가이드를 참고하세요.

`getItemKey`

같은 내용이 같은 슬롯에서 다른 객체로 다시 만들어질 수 있을 때 사용할 안정적인 논리 키를 반환합니다. setItemDimensions로 런타임에 등록한 크기와 함께 사용하세요. 자세한 내용은 콘텐츠 크기 가이드를 참고하세요.

`initialIndex` (기본값: `0`)

뷰어가 표시할 아이템 인덱스를 설정할 수 있습니다. 이 값은 현재 data 길이에 맞게 정규화됩니다. 유한하지 않은 값과 음수는 0이 되고, 범위를 초과한 값은 마지막 인덱스가 되며, 빈 데이터는 0으로 처리됩니다.

뷰어가 이미 마운트된 뒤 initialIndex가 바뀌면 정규화된 인덱스로 다시 이동합니다.

`maxZoomScale` (기본값: `2`)

최대 줌 배율을 제어할 수 있습니다.