#개요

이 문서는 v3 beta 문서입니다. v3가 stable로 릴리스되기 전까지 기본 stable 문서는 2.x로 유지됩니다.

React Native에서 이미지 갤러리나 콘텐츠 뷰어를 구현할 때, 복잡한 제스처 처리와 애니메이션 구현으로 어려움을 겪으신 적이 있으신가요?

기존 라이브러리들은 커스터마이징이 어렵거나 성능 문제가 있었습니다. react-native-gesture-image-viewer는 React Native Reanimated와 Gesture Handler를 기반으로 한 고성능 범용 제스처 뷰어 라이브러리로, 이미지뿐만 아니라 비디오, 커스텀 컴포넌트 등 모든 콘텐츠에 완전한 커스터마이징과 직관적인 제스처 지원을 제공합니다.

#v3 페이징 동작 방식

3.x는 더 이상 사용자가 넘긴 ScrollView, FlatList, FlashList에 의존해서 페이징하지 않습니다. GestureViewer가 제스처 기반 render window로 가로 페이징을 내부에서 직접 처리합니다.

windowSize는 현재 아이템 주변에 유지할 render window의 크기를 결정하며 기본값은 3입니다. 기본 설정에서는 이전, 현재, 다음 페이지를 마운트합니다. non-loop의 데이터 경계에서는 범위를 벗어난 페이지를 생략합니다.

애니메이션으로 페이지를 전환하는 동안 Reanimated가 기존 페이지들을 먼저 이동합니다. 전환이 끝나면 새로운 현재 아이템을 기준으로 render window를 갱신합니다. 이때 계속 범위 안에 있는 페이지는 마운트 상태를 유지하고, 범위를 벗어난 페이지는 언마운트하며, 새로 인접한 페이지를 마운트합니다.

enableLoop가 켜져 있으면 내부 render window가 마지막 아이템에서 첫 번째 아이템으로, 첫 번째 아이템에서 마지막 아이템으로 이어집니다. 이 동작도 리스트 구현에 의존하지 않습니다.

인접 콘텐츠를 더 많이 마운트해야 할 때만 windowSize를 늘리고, 페이지 사이에 보이는 간격이 필요할 때는 pageSpacing을 사용하세요.

#주요 특징

• 🤌 완전한 제스처 지원 - 핀치 줌, 더블 탭 줌, 스와이프 네비게이션, 줌 상태에서의 팬, 세로 드래그로 닫기 지원
• 🏎️ 고성능 애니메이션 - React Native Reanimated 기반의 60fps 이상의 부드럽고 반응성 높은 애니메이션
• 🪟 리스트 없는 render window - ScrollView, FlatList, FlashList 없이 내부 제스처 기반 페이징 처리
• 🎨 완전한 커스터마이징 - 컴포넌트, 스타일, 제스처 동작까지 완벽하게 제어 가능
• 🎛️ 외부 제어 API - 버튼 등 다른 UI 컴포넌트에서 프로그래밍 방식으로 제어 가능
• 🧩 다중 인스턴스 관리 - 고유 ID 기반으로 여러 뷰어를 독립적으로 관리
• 🧬 유연한 통합 - Modal, React Native Modal, Expo Image, FastImage, 커스텀 콘텐츠 사용
• 🧠 완벽한 TypeScript 지원 - 타입 추론과 안정성을 갖춘 뛰어난 개발 경험 제공
• 🌐 크로스 플랫폼 지원 - iOS, Android, Web에서 동작하며 Expo Go 및 New Architecture 지원
• 🪄 간편한 API - 복잡한 설정 없이도 직관적이고 쉽게 구현 가능