--- url: /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**](https://docs.swmansion.com/react-native-reanimated/)와 [**Gesture Handler**](https://docs.swmansion.com/react-native-gesture-handler/docs/)를 기반으로 한 고성능 **범용 제스처 뷰어** 라이브러리로, 이미지뿐만 아니라 비디오, 커스텀 컴포넌트 등 모든 콘텐츠에 완전한 커스터마이징과 직관적인 제스처 지원을 제공합니다. ## v3 페이징 동작 방식 3.x는 더 이상 사용자가 넘긴 `ScrollView`, `FlatList`, `FlashList`에 의존해서 페이징하지 않습니다. `GestureViewer`가 제스처 기반 render window로 가로 페이징을 내부에서 직접 처리합니다. `windowSize`는 현재 아이템 주변에 유지할 render window의 크기를 결정하며 기본값은 `3`입니다. 기본 설정에서는 이전, 현재, 다음 페이지를 마운트합니다. non-loop의 데이터 경계에서는 범위를 벗어난 페이지를 생략합니다. 애니메이션으로 페이지를 전환하는 동안 Reanimated가 기존 페이지들을 먼저 이동합니다. 전환이 끝나면 새로운 현재 아이템을 기준으로 render window를 갱신합니다. 이때 계속 범위 안에 있는 페이지는 마운트 상태를 유지하고, 범위를 벗어난 페이지는 언마운트하며, 새로 인접한 페이지를 마운트합니다. ![3번 아이템에서 4번 아이템으로 이동할 때 3번과 4번 페이지를 유지하는 세 페이지 render window](/guide/getting-started/v3-paging-render-window-ko.png) `enableLoop`가 켜져 있으면 내부 render window가 마지막 아이템에서 첫 번째 아이템으로, 첫 번째 아이템에서 마지막 아이템으로 이어집니다. 이 동작도 리스트 구현에 의존하지 않습니다. 인접 콘텐츠를 더 많이 마운트해야 할 때만 `windowSize`를 늘리고, 페이지 사이에 보이는 간격이 필요할 때는 `pageSpacing`을 사용하세요. ## 주요 특징 - 🤌 **완전한 제스처 지원** - 핀치 줌, 더블 탭 줌, 스와이프 네비게이션, 줌 상태에서의 팬, 세로 드래그로 닫기 지원 - 🏎️ **고성능 애니메이션** - React Native Reanimated 기반의 60fps 이상의 부드럽고 반응성 높은 애니메이션 - 🪟 **리스트 없는 render window** - `ScrollView`, `FlatList`, `FlashList` 없이 내부 제스처 기반 페이징 처리 - 🎨 **완전한 커스터마이징** - 컴포넌트, 스타일, 제스처 동작까지 완벽하게 제어 가능 - 🎛️ **외부 제어 API** - 버튼 등 다른 UI 컴포넌트에서 프로그래밍 방식으로 제어 가능 - 🧩 **다중 인스턴스 관리** - 고유 ID 기반으로 여러 뷰어를 독립적으로 관리 - 🧬 **유연한 통합** - Modal, [React Native Modal](https://www.npmjs.com/package/react-native-modal), [Expo Image](https://www.npmjs.com/package/expo-image), [FastImage](https://github.com/DylanVann/react-native-fast-image), 커스텀 콘텐츠 사용 - 🧠 **완벽한 TypeScript 지원** - 타입 추론과 안정성을 갖춘 뛰어난 개발 경험 제공 - 🌐 **크로스 플랫폼 지원** - iOS, Android, Web에서 동작하며 Expo Go 및 New Architecture 지원 - 🪄 **간편한 API** - 복잡한 설정 없이도 직관적이고 쉽게 구현 가능 --- url: /3.x-beta/ko/guide/getting-started/installation.md --- # 설치 :::warning React Native Reanimated v3 사용자 **React Native Reanimated v3**를 사용 중이라면, 최상의 경험을 위해 이 라이브러리의 **1.x 버전이 권장됩니다**. 👉 **[1.x 문서로 이동](/1.x/ko/guide/getting-started/installation.md)** 3.x 버전은 React Native Reanimated v4를 지원합니다. ::: :::info 중요 `react-native-gesture-image-viewer`는 [`react-native-reanimated`](https://www.npmjs.com/package/react-native-reanimated)와 [`react-native-gesture-handler`](https://www.npmjs.com/package/react-native-gesture-handler)를 기반으로 한 높은 성능의 뷰어 라이브러리입니다. 따라서 이 라이브러리를 사용하기 전에 React Native Reanimated와 Gesture Handler를 **반드시 설치**해야 합니다. 자세한 설정 가이드는 각 라이브러리의 공식 문서를 참고해주세요. ::: #### 필수 요구사항 | 라이브러리 | 최소 버전 | | :----------------------------- | :--------: | | `react` | `>=18.0.0` | | `react-native` | `>=0.75.0` | | `react-native-gesture-handler` | `>=2.24.0` | | `react-native-reanimated` | `>=4.0.0` | | `react-native-worklets` | `>=0.5.0` | ## [React Native Reanimated 설정](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/getting-started/) ### `react-native-reanimated` 및 `react-native-worklets` 설치: ```sh [npm] npm install react-native-reanimated ``` ```sh [yarn] yarn add react-native-reanimated ``` ```sh [pnpm] pnpm add react-native-reanimated ``` ```sh [bun] bun add react-native-reanimated ``` ```sh [deno] deno add npm:react-native-reanimated ``` - `react-native-worklets`는 더 나은 모듈성을 위해 `react-native-reanimated`에서 분리되었으며 별도로 설치해야 합니다. ```sh [npm] npm install react-native-worklets ``` ```sh [yarn] yarn add react-native-worklets ``` ```sh [pnpm] pnpm add react-native-worklets ``` ```sh [bun] bun add react-native-worklets ``` ```sh [deno] deno add npm:react-native-worklets ``` ### Babel 설정 #### Expo :::warning Expo Go 지원 Expo Go 환경에서 Reanimated 4를 사용하려면 [Expo SDK 54(beta)](https://expo.dev/go)를 사용해야 합니다. ::: Expo를 사용할 경우 `expo prebuild`를 실행하여 ios와 android 디렉토리의 네이티브 코드를 업데이트합니다. ```sh [npm] npm expo prebuild ``` ```sh [yarn] yarn expo prebuild ``` ```sh [pnpm] pnpm expo prebuild ``` ```sh [bun] bun expo prebuild ``` ```sh [deno] deno expo npm:prebuild ``` 끝입니다! 이제 Expo 프로젝트에서 Reanimated 4가 구성되었습니다. Expo SDK 50부터는 Expo 스타터 템플릿에 기본적으로 Reanimated Babel 플러그인이 포함되어 있습니다. #### React Native CLI React Native Community CLI를 사용할 때는 `babel.config.js`에 `react-native-worklets/plugin` 플러그인을 수동으로 추가해야 합니다. ```js title="babel.config.js" module.exports = { presets: [ ... // don't add it here :) ], plugins: [ ... // for web '@babel/plugin-transform-export-namespace-from', // [!code highlight] // react-native-worklets/plugin has to be listed last. 'react-native-worklets/plugin', // [!code highlight] ], }; ``` ## [React Native Gesture Handler 설정](https://docs.swmansion.com/react-native-gesture-handler/docs/fundamentals/installation) ```sh [npm] npm install react-native-gesture-handler ``` ```sh [yarn] yarn add react-native-gesture-handler ``` ```sh [pnpm] pnpm add react-native-gesture-handler ``` ```sh [bun] bun add react-native-gesture-handler ``` ```sh [deno] deno add npm:react-native-gesture-handler ``` - `react-native-gesture-handler`는 기본적으로 추가할 설정은 없지만, 공식 문서를 참고하여 환경에 맞게 설치해주세요. - [안드로이드 환경의 모달에서 제스처를 사용](https://docs.swmansion.com/react-native-gesture-handler/docs/fundamentals/installation#android)하려면 모달의 콘텐츠를 `GestureHandlerRootView`로 래핑해야 정상적으로 동작하지만, **라이브러리 내부에 이미 `GestureHandlerRootView`가 래핑되어 있어 모달 사용 시 추가로 래핑할 필요가 없습니다.** ## React Native Gesture Image Viewer 설치 모든 설정이 끝났습니다! 🎉 이제 `react-native-gesture-image-viewer`의 beta 릴리스를 설치하면 됩니다. ```sh [npm] npm install react-native-gesture-image-viewer@beta ``` ```sh [yarn] yarn add react-native-gesture-image-viewer@beta ``` ```sh [pnpm] pnpm add react-native-gesture-image-viewer@beta ``` ```sh [bun] bun add react-native-gesture-image-viewer@beta ``` ```sh [deno] deno add npm:react-native-gesture-image-viewer@beta ``` --- url: /3.x-beta/ko/guide/getting-started/quick-start.md --- # 빠른 시작 ## 예제 및 데모 - [📁 예제 프로젝트](https://github.com/saseungmin/react-native-gesture-image-viewer/tree/main/example) - 실제 구현 코드와 다양한 사용 사례 - [🤖 Expo Snack](https://snack.expo.dev/@harang/react-native-gesture-image-viewer-v3) - Expo Snack에서 바로 체험 ## 설치 :::warning 중요 `react-native-gesture-image-viewer`는 [`react-native-reanimated`](https://www.npmjs.com/package/react-native-reanimated)와 [`react-native-gesture-handler`](https://www.npmjs.com/package/react-native-gesture-handler)를 기반으로 한 높은 성능의 뷰어 라이브러리입니다. 따라서 이 라이브러리를 사용하기 전에 React Native Reanimated와 Gesture Handler를 설치해야 합니다. **아직 설정을 하지 않았다면 [설치 가이드](/3.x-beta/ko/guide/getting-started/installation.md)를 참고해주세요.** ::: ```sh [npm] npm install react-native-gesture-image-viewer@beta ``` ```sh [yarn] yarn add react-native-gesture-image-viewer@beta ``` ```sh [pnpm] pnpm add react-native-gesture-image-viewer@beta ``` ```sh [bun] bun add react-native-gesture-image-viewer@beta ``` ```sh [deno] deno add npm:react-native-gesture-image-viewer@beta ``` ## 기본 사용법 `react-native-gesture-image-viewer`는 완전한 커스터마이징을 위해 제스처 동작에만 집중한 라이브러리입니다. ```tsx import { useCallback, useState } from 'react'; import { Image, Modal, View, Text, Button, Pressable } from 'react-native'; import { GestureViewer, GestureTrigger, useGestureViewerController, useGestureViewerEvent, useGestureViewerState, } from 'react-native-gesture-image-viewer'; function App() { const images = [...]; const [visible, setVisible] = useState(false); const [selectedIndex, setSelectedIndex] = useState(0); const { goToIndex, goToPrevious, goToNext } = useGestureViewerController(); const { currentIndex, totalCount } = useGestureViewerState(); const openModal = (index: number) => { setSelectedIndex(index); setVisible(true); }; const renderImage = useCallback((imageUrl: string) => { return ; }, []); useGestureViewerEvent('zoomChange', (data) => { console.log(`Zoom changed from ${data.previousScale} to ${data.scale}`); }); return ( {images.map((uri, index) => ( openModal(index)}> ))} setVisible(false)} />