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