Expo에서 애니메이션 구축하기
이 저장소 (Asymmetric-al/core)
이 스킬은 React Native / Expo 모션 전용입니다. Core의 Next.js 앱은 대신 animate, emil-design-engineering, anim을 사용해야 합니다. 업스트림을 리프레시한 후에 bun run skills:sync를 실행하기 전에 이 오버레이를 조정하세요.
트리거
- 명시적인 Expo 또는 React Native 애니메이션, 제스처, 시트, 햅틱 작업.
- Core 웹 앱(
apps/admin,apps/donor,apps/missionary) 또는 공유packages/ui웹 모션에는 로드하지 마세요.
워크플로
- Reanimated 레시피를 적용하기 전에 요청이 네이티브/Expo인지 확인합니다.
- Core Next.js 표면의 경우, 중단하고
animate와anim을 로드합니다.
체크리스트
- 대상 런타임이 Expo/React Native이며, Core의 App Router 앱이 아닙니다.
- 웹 모션은 여전히 Core 토큰과 Base UI를 따릅니다.
React Native를 위한 구축 스킬입니다. 모션에 대한 요청을 실제 기기에서 엄격한 리뷰를 통과할 수 있는 구현으로 변환합니다 — 시뮬레이터가 아니라, 플래그십 폰의 개발 모드에서가 아닌 실제 환경에서 말입니다.
모바일은 애니메이션을 세 가지 측면에서 바꾸며, 이 스킬의 모든 것은 이것에서 비롯됩니다:
- 호버가 없습니다. 웹에서 호버에 있던 모든 어포던스는 프레스, 위치, 또는 없음 중 하나로 처리해야 합니다.
- 두 개의 런타임이 있습니다. Worklet(Reanimated 4)이 이를 명확히 합니다: React가 렌더링되고 앱 로직이 실행되는 React Native 런타임, 그리고 worklet이 매 프레임 실행되는 UI 런타임(추가로 백그라운드 작업을 위한 선택적 워커 런타임 포함). RN 런타임을 건드리는 애니메이션은 앱이 다른 작업을 하는 순간 버벅거립니다. 모든 기술은 모션을 UI 런타임에 유지하는 것입니다.
- 사용자의 손가락이 요소 위에 있습니다. 제스처가 주요 입력이므로, 중단 가능성과 속도 전달은 추가 작업이 아니라 기본입니다.
운영 자세
당신은 애니메이션을 직접 구축하는 시니어 모바일 엔지니어입니다. 결정을 내리고, 이유를 한 줄로 설명하고, 코드를 작성하세요. 모션 옵션을 메뉴 형태로 제시하지 마세요.
두 가지 실패 모드가 있으며, 첫 번째가 더 나쁩니다:
- 애니메이션을 적용해서는 안 되는 것을 애니메이션하는 것. 아래 게이트는 때때로 코드를 전혀 생성하지 않기 위해 존재합니다.
- 올바른 것을 잘못된 스레드에서 애니메이션하는 것 — 프레임당
setState,PanResponder, 애니메이션된height. 개발 모드 폰에서는 잘 보이지만 3년 된 Android에서는 20fps로 떨어집니다.
엄격한 규칙
- 순서대로 실행하세요. 1단계와 2단계가 모든 것을 통제합니다.
- Reanimated, core
Animated가 아닙니다. CoreAnimated는 브리지를 건너지 않고는 제스처로 구동될 수 없으며,useNativeDriver는 어차피 transform과 opacity만 허용합니다. Reanimated worklet은 UI 스레드에서 실행되며 JS가 바쁜 동안에도 계속 실행됩니다. - 근사값을 사용하지 마세요. 곡선과 스프링 설정은 아래 테이블에서 가져옵니다.
- 움직임 감소는 애니메이션과 함께 제공되며, 후속 작업이 아닙니다.
- 느낌은 지원하는 가장 느린 기기에서 릴리스 빌드로 평가됩니다. 그 외에는 검증된 것으로 간주되지 않습니다.
구축 시퀀스
1. 이것이 정말 애니메이션되어야 하나요?
| 빈도 | 결정 |
|---|---|
| 하루 100회 이상 — 탭 전환, 키보드 열기/닫기, 스크롤, 설정 토글 | 애니메이션 없음. 플랫폼 기본값 또는 없음. 여기서 중단하세요. |
| 하루 수십 회 — 프레스 피드백, 목록 탐색, 행 선택 | 거의 인지할 수 없는 수준만: 150ms 미만, 또는 없음 |
| 가끔 — 시트, 모달, 토스트, 온보딩 단계 | 표준 애니메이션 |
| 드물게 / 최초 — 성공 상태, 빈 상태 일러스트레이션, 축하 | 즐거움 예산은 여기에 있습니다 |
탭 전환은 절대 슬라이드하지 않습니다. 탭은 계층 구조가 아닌 동등 관계입니다 — 슬라이드는 존재하지 않는 깊이를 암시하며, 사용자는 세션당 수십 번 그 대가를 치릅니다. animation: 'none'.
요청이 이 게이트를 통과하지 못하면 그렇게 말하고 작성하지 마세요.
2. 목적은 무엇인가요?
계속하기 전에 한 단어로 이름을 붙이세요: 피드백, 공간적 일관성, 상태 표시, 갑작스러운 변화 방지, 설명, 또는 즐거움(드문 계층만).
이름을 붙일 수 없나요? 구축하지 마세요.
3. 도구 선택 — 가장 저렴하고 작동하는 것
아래로 내려가면서 첫 번째로 맞는 것에서 멈추세요.
| 필요 | 도구 |
|---|---|
| 제스처 없이 상태에 의해 구동되는 변화 — 프레스, 토글, 색상, 값 전환 | Reanimated CSS 전환 (스타일의 transitionProperty) |
| 루프, 다단계, 또는 상태 변화 없이 마운트 시 재생 | Reanimated CSS 애니메이션 (animationName 키프레임) |
| 요소 마운트/언마운트 또는 리스트 재배치 | 레이아웃 애니메이션 (entering / exiting / itemLayoutAnimation) |
| 손가락이 닿는 모든 것, 또는 스크롤에서 파생되는 모든 것 | useSharedValue + Gesture + useAnimatedStyle |
| 화면 간 이동 | Expo Router의 네이티브 스택 옵션. 직접 구현하지 마세요 |
| 자체 화면인 바텀 시트 | presentation: 'formSheet' — 실제 UISheetPresentationController로, 무료이고 정확합니다 |
| 탭 바 | NativeTabs (expo-router/unstable-native-tabs에서) — 플랫폼의 실제 탭 바, 동작 및 전환 포함 |
| 컨텍스트 메뉴, 길게 누르고 미리보기 | Link.Menu / Link.Preview (Expo Router, iOS 전용) — 네이티브 메뉴 및 peek, JS에서 다시 구축하지 않음 |
| 큰 제목으로 축소되는 헤더 | headerLargeTitleEnabled (네이티브 스택, iOS 전용; headerLargeTitle은 더 이상 사용되지 않음) — 스크롤 worklet이 아님 |
| 당겨서 새로고침 | RefreshControl — 시그니처 상호작용인 경우에만 직접 구현(임계값 레시피 참조) |
| 키보드를 따라가는 UI | react-native-keyboard-controller — 키보드의 실제 위치, 프레임별로, UI 스레드에서 |
| 벡터 일러스트레이션, 축하, 빈 상태 | Lottie — 일러스트레이션 전용, UI 상태에는 절대 사용하지 마세요 |
| 거대한 애니메이션 장면, 자유형 드로잉 | @shopify/react-native-skia — 뷰 계층 자체가 병목일 때를 위한 캔버스 |
값이 연속적이거나 중단 가능한 경우에만 공유 값에 도달하세요. 프레스 스케일은 CSS 전환이고, 드래그는 공유 값입니다. 두 상태 토글에 worklet을 사용하는 것은 페이드 인/아웃을 위해 모션 라이브러리를 설치하는 것과 같습니다.
의존성. npx expo install <package>로 설치하세요 — 일반 npm install이 하지 못하는 프로젝트의 SDK와 일치하는 버전을 해결합니다:
| 필요 | 패키지 |
|---|---|
| 애니메이션 | react-native-reanimated + react-native-worklets |
| 제스처 | react-native-gesture-handler |
| 내비게이션, 시트, 네이티브 탭, 메뉴 | expo-router |
| 햅틱 | expo-haptics |
| 키보드 따라가는 UI | react-native-keyboard-controller (루트에 KeyboardProvider 필요 — 키보드 레시피 참조) |
| 일러스트레이션, 축하 | lottie-react-native |
| 매우 큰 애니메이션 장면, 커스텀 드로잉 | @shopify/react-native-skia |
4. 속성 선택
transform과opacity는 무료입니다. 그 외의 모든 것은 레이아웃 통과입니다.width,height,margin,padding,flex,top,left,gap은 매 프레임마다 해당 노드와 _그 형제들_에 대해 Yoga를 다시 실행합니다.- 한 가지 예외: 자식이 없는 절대 위치 요소 — 탭 필, 진행률 표시줄 채움. 흐름 밖에 있으므로 다른 요소가 다시 레이아웃되지 않으며,
width를 애니메이션하면scaleX가 흐릴 수 있는 모서리 반경을 유지합니다. - 절대
scale(0)을 사용하지 마세요.scale(0.9–0.97)+opacity: 0에서 시작하세요. 현실 세계에서 무에서 생성되는 것은 없습니다. transform은 배열이며 순서가 중요합니다 —[{ translateY }, { scale }]은 이동 후에 스케일링합니다. 반대로 하면 translate도 스케일링됩니다. 곱셈을 원하지 않는 한 translate를 먼저 유지하세요.- Android 그림자는
elevation이며, elevation을 애니메이션하면 매 프레임 그림자를 다시 렌더링합니다. 대신 사전 그림자 레이어의 opacity를 애니메이션하세요. - 절대
BlurView강도를 애니메이션하지 마세요. Android에서는 매 프레임 블러를 다시 렌더링합니다. 대신 정적BlurView의 opacity를 크로스페이드하세요. - 백분율은
translate에서 작동하며 요소 자체의 크기에 상대적입니다 —translateY('100%')는 내용물에 관계없이 시트를 자체 높이만큼 이동시킵니다.
5. 타이밍 또는 스프링
손가락이 관여했다면 스프링을 사용하세요. 스프링은 중단을 통해 속도를 전달합니다. 타이밍 곡선은 다시 시작됩니다. 그 외 모든 것은 타이밍을 사용합니다.
Reanimated의 스프링은 Apple의 두 디자이너 파라미터를 직접 사용합니다 — 이 형식을 사용하고 mass/stiffness/damping은 사용하지 마세요:
| 상호작용 | 설정 |
|---|---|
| 기본 정착, 오버슈트 없음 | { duration: 400, dampingRatio: 1 } |
| 드래그 후 재배치 / 스냅 백 | { duration: 400, dampingRatio: 0.8, velocity } |
| 시트, 드로어 | { duration: 300, dampingRatio: 0.8, velocity } |
| 단단한 가장자리를 넘지 말아야 함 | overshootClamping: true 추가 |
제스처가 모멘텀을 가지고 있을 때만 바운스하세요. 페이드 인한 메뉴의 오버슈트는 어색하게 느껴집니다. 당신이 튕긴 카드의 오버슈트는 자연스럽게 느껴집니다.
Easing, 손가락이 없는 모든 것:
| 상황 | Easing |
|---|---|
| 진입 또는 퇴장 | ease-out |
| 화면에서 이동 / 변형 | ease-in-out |
| 일정한 모션 (진행, 마키) | linear |
| 기본 | ease-out |
UI에 ease-in을 절대 사용하지 마세요. 느리게 시작하여 사용자가 보고 있는 정확한 순간을 지연시킵니다. Reanimated의 내장 Easing은 CSS만큼 약합니다 — 이것들을 사용하세요:
import { Easing } from "react-native-reanimated";
const EASE_OUT = Easing.bezier(0.23, 1, 0.32, 1); // UI를 위한 강한 ease-out
const EASE_IN_OUT = Easing.bezier(0.77, 0, 0.175, 1); // 화면 내 이동
const EASE_SHEET = Easing.bezier(0.32, 0.72, 0, 1); // iOS 시트 곡선
지속 시간:
| 요소 | 지속 시간 |
|---|---|
| 프레스 피드백 | 100–150ms |
| 토글, 칩, 작은 상태 변화 | 150–200ms |
| 시트, 모달, 드로어 | 스프링, ~300ms 인지 |
| 화면 전환 | 플랫폼 기본값 — 재정의하지 마세요 |
모바일 UI 애니메이션은 웹과 마찬가지로 300ms 미만으로 유지됩니다. 플랫폼 자체 전환은 더 깁니다 (iOS 푸시는 350ms); 네비게이션은 플랫폼을 따르고, 다른 모든 곳에서는 이를 능가하세요.
6. JS 스레드에서 멀리 유지
이것은 모바일 특화 기술이며, 대부분의 React Native 모션이 죽는 곳입니다.
- 제스처 또는 스크롤 핸들러에서 절대
setState를 호출하지 마세요. 프레임당 하나의 React 렌더는 RN 앱에서 버벅거림의 가장 큰 원인입니다. 공유 값 →useAnimatedStyle, React는 전혀 다시 렌더링하지 않습니다. onUpdate또는 스크롤 핸들러 내부에서 RN 런타임으로 다시 스케줄링하지 마세요.react-native-worklets의scheduleOnRN(fn, ...args)— 더 이상 사용되지 않는runOnJS(fn)(...args)를 대체하는 Reanimated 4 — 는 RN 런타임 호출을 큐에 넣으며,onUpdate에서는 초당 60–120번입니다. 이는onEnd또는 값이 임계값을 넘을 때 실행되는useAnimatedReaction에 속합니다.- 렌더링 중에 공유 값을 읽지 마세요 (JSX에서
translateY.get()). 업데이트되지 않는 스냅샷이며, 자동 재렌더링도 없습니다.