# React Native Gesture Image Viewer ## 가이드 - [개요](/2.x/ko/guide/getting-started/overview.md): React Native에서 이미지 갤러리나 콘텐츠 뷰어를 구현할 때, 복잡한 제스처 처리와 애니메이션 구현으로 어려움을 겪으신 적이 있으신가요? 기존 라이브러리들은 커스터마이징이 어렵거나 성능 문제가 있었습니다. react-native-gesture-image-viewer는 React Native Reanimated와 Gesture Handler를 기반으로 한 고성능 범용 제스처 뷰어 라이브러리로, 이미지뿐만 아니라 비디오, 커스텀 컴포넌트 등 모든 콘텐츠에 완전한 커스터마이징과 직관적인 제스처 지원을 제공합니다. - [설치](/2.x/ko/guide/getting-started/installation.md): 필수 요구사항 - [빠른 시작](/2.x/ko/guide/getting-started/quick-start.md) - [AI](/2.x/ko/guide/getting-started/ai.md): AI가 이 라이브러리의 기능, 버전별 문서, 프로젝트 규칙을 더 잘 이해해서 개발이나 트러블슈팅 과정에서 더 정확한 도움을 줄 수 있도록, 이 프로젝트는 다음 기능들을 제공합니다. ## Others - [1.x에서 2.x로 마이그레이션](/2.x/ko/guide/migration-from-1.x.md) - [성능 최적화 팁](/2.x/ko/guide/performance-optimization-tips.md): renderItem 함수는 useCallback으로 감싸서 불필요한 리렌더링을 방지하세요. 변경되지 않은 data를 다시 만들지 마세요. 목록 내용이 바뀔 때 새 배열을 전달하는 것은 올바른 사용법이며 정상적으로 지원됩니다. 다만 부모 컴포넌트가 자주 rerender될 때 동일한 배열을 매번 다시 만들면 viewer와 치수 조정 작업이 반복될 수 있습니다. 변환이 필요하지 않다면 기존 배열을 그대로 전달하고, 실제 파생 데이터만 메모이제이션하세요. data를 제자리에서 변경하지 말고, 내용이 바뀔 때 배열을 교체하세요. 대용량 이미지의 경우 expo-image나 FastImage 사용을 권장합니다. 많은 수의 이미지를 다룰 때는 FlashList 사용을 권장합니다. FlashList Performance 가이드 디바이스에서 테스트하세요. (시뮬레이터에서는 성능이 제한될 수 있습니다.) - [기본 사용법](/2.x/ko/guide/usage/basic-usage.md) - [커스텀 컴포넌트](/2.x/ko/guide/usage/custom-components.md): react-native-gesture-image-viewer는 강력한 기능으로 완벽한 컴포넌트 커스터마이징이 가능합니다. 이미지뿐만 아니라 원하는 컴포넌트로 제스처를 지원하는 아이템을 만들 수 있습니다. - [제스처 기능](/2.x/ko/guide/usage/gesture-features.md): react-native-gesture-image-viewer는 뷰어에 필요한 다양한 제스처를 지원합니다. 제스처 동작의 기본값은 아래 예제를 참고해주세요. - [GestureViewer Props](/2.x/ko/guide/usage/gesture-viewer-props.md): renderItem renderItem은 data의 각 아이템을 렌더링하며, renderItem(item, index, { isActive, setItemDimensions }) 형태로 세 번째 인자에서 isActive와 setItemDimensions를 제공합니다. 비디오 재생처럼 활성 아이템에서만 필요한 작업은 isActive로 제어할 수 있습니다. 동작 방식과 예시는 renderItem 활성 상태 (isActive)를 참고하세요. setItemDimensions({ width, height })는 렌더링된 콘텐츠의 원본 크기를 알 수 있게 된 뒤 호출하세요. 예시와 호출 시점은 콘텐츠 크기 가이드를 참고하세요. enableLoop (기본값: false) 루프 모드를 활성화합니다. true일 때 마지막 아이템에서 다음으로 가면 첫 번째로, 첫 번째에서 이전으로 가면 마지막으로 돌아갑니다. enableSnapMode (기본값: false) 스냅 스크롤 모드를 활성화합니다. false (기본값): 페이징 모드 (pagingEnabled: true)전체 화면 크기 단위로 스크롤됩니다true: 스냅 모드 (snapToInterval 자동 계산)snapToInterval이 width와 itemSpacing 값을 기반으로 자동 계산됩니다아이템 간격이 필요할 때 이 옵션을 사용하세요 itemSpacing (기본값: 0) 아이템 간의 간격을 픽셀 단위로 설정합니다. enableSnapMode가 true일 때만 적용됩니다. autoPlay (기본값: false) 자동 재생 모드를 활성화합니다. true일 때 지정된 간격 후 다음 아이템으로 자동으로 재생됩니다. enableLoop이 활성화되면 마지막 아이템에서 다음으로 가면 첫 번째로, 첫 번째에서 이전으로 가면 마지막으로 돌아갑니다.enableLoop이 비활성화되면 마지막 아이템에서 정지됩니다.아이템이 하나만 있을 때 자동 재생이 비활성화됩니다.줌 또는 회전 제스처가 감지되면 자동 재생이 일시 중지됩니다. autoPlayInterval (기본값: 3000) 자동 재생 간격을 밀리초 단위로 설정합니다.양수 정수여야 합니다. 값이 250ms 미만이면 런타임에서 250ms로 제한됩니다. onSingleTap 뷰어에서 싱글 탭이 확정되면 실행됩니다. 헤더, 푸터, 캡션, 액션 버튼처럼 뷰어 컨트롤 UI를 토글할 때 유용하며, 뷰어 위에 별도의 pressable을 덮지 않아도 됩니다. 더블 탭 줌이 활성화되어 있으면 더블 탭이 아닌지 확인한 뒤 실행되므로 약간 늦게 호출될 수 있습니다스와이프, 핀치, dismiss, 더블 탭 줌 제스처에서는 호출되지 않습니다 getItemDimensions 콘텐츠의 원본 크기를 이미 알고 있을 때 반환합니다. renderItem에서 setItemDimensions로 런타임에 등록한 크기가 우선합니다. 예시는 콘텐츠 크기 가이드를 참고하세요. getItemKey 같은 내용이 같은 슬롯에서 다른 객체로 다시 만들어질 수 있을 때 사용할 안정적인 논리 키를 반환합니다. setItemDimensions로 런타임에 등록한 크기와 함께 사용하세요. 자세한 내용은 콘텐츠 크기 가이드를 참고하세요. initialIndex (기본값: 0) 뷰어가 표시할 아이템 인덱스를 설정할 수 있습니다. 이 값은 현재 data 길이에 맞게 정규화됩니다. 유한하지 않은 값과 음수는 0이 되고, 범위를 초과한 값은 마지막 인덱스가 되며, 빈 데이터는 0으로 처리됩니다. 뷰어가 이미 마운트된 뒤 initialIndex가 바뀌면 정규화된 인덱스로 다시 이동합니다. maxZoomScale (기본값: 2) 최대 줌 배율을 제어할 수 있습니다. - [GestureViewer 상태 추적](/2.x/ko/guide/usage/gesture-viewer-state.md): GestureViewer는 뷰어의 현재 상태를 추적하는 상태 관리 시스템을 제공합니다. useGestureViewerState 훅을 사용하여 뷰어의 상태를 접근할 수 있습니다. - [뷰어 이벤트 처리하기](/2.x/ko/guide/usage/handling-viewer-events.md): useGestureViewerEvent 훅을 사용하여 GestureViewer의 특정 이벤트를 구독할 수 있습니다. 줌, 회전, 탭과 같은 뷰어 상호작용에 반응할 수 있습니다. - [콘텐츠 크기](/2.x/ko/guide/usage/item-dimensions.md): GestureViewer는 렌더된 콘텐츠의 원본 크기를 알 때 더 정확한 줌과 팬 범위를 계산할 수 있습니다. 이 값은 특히 contain 이미지에서 중요합니다. 콘텐츠 크기를 제공하지 않으면 기존 동작처럼 전체 뷰어 셀을 콘텐츠 크기로 사용합니다. 원본 크기를 화면에 맞춘 뒤, 콘텐츠가 화면보다 작은 축에서는 중앙에 유지하고 큰 축에서는 콘텐츠 가장자리까지만 이동할 수 있습니다. width와 height는 모두 0보다 큰 유한한 숫자여야 합니다. - [다중 인스턴스 관리](/2.x/ko/guide/usage/multi-instance-management.md): 여러 개의 GestureViewer 인스턴스를 효율적으로 관리하고 싶은 경우 id 값을 적용하면 여러 개의 GestureViewer를 사용할 수 있습니다. GestureViewer는 컴포넌트가 언마운트되면 메모리에서 자동으로 인스턴스가 제거되어 메모리 관리를 수동으로 할 필요가 없습니다. - [프로그래밍 방식 제어](/2.x/ko/guide/usage/programmatic-control.md): useGestureViewerController 훅을 사용하여 GestureViewer를 프로그래밍 방식으로 제어할 수 있습니다. - [스타일 커스터마이징](/2.x/ko/guide/usage/style-customization.md): GestureViewer의 스타일을 커스터마이징할 수 있습니다. - [트리거 기반 모달 애니메이션](/2.x/ko/guide/usage/trigger-based-animations.md): GestureTrigger는 썸네일과 같은 트리거 요소에서 전체 모달 뷰로의 원활한 전환을 생성하는 부드러운 트리거 기반 애니메이션을 지원합니다. 이 기능은 트리거와 모달 콘텐츠 간의 시각적 연속성을 유지하여 사용자 경험을 향상시킵니다.