Construire des animations dans Expo
Ce dépôt (Asymmetric-al/core)
Ce skill est destiné uniquement au motion React Native / Expo. Les applications Next.js de Core doivent utiliser animate, emil-design-engineering et anim à la place. Conciliez cette superposition après les mises à jour en amont avant d'exécuter bun run skills:sync.
Déclencheurs
- Travail explicite d'animation, de geste, de feuille ou de haptique pour Expo ou React Native.
- Ne le chargez pas pour les applications web Core (
apps/admin,apps/donor,apps/missionary) ou le motion web partagépackages/ui.
Flux de travail
- Confirmez que la demande est native/Expo avant d'appliquer les recettes Reanimated.
- Pour les surfaces Core Next.js, arrêtez-vous et chargez
animateplusanim.
Liste de vérification
- L'environnement d'exécution cible est Expo/React Native, pas les applications Core App Router.
- Le motion web suit toujours les tokens Core et Base UI.
Un skill de construction pour React Native. Il transforme une demande de mouvement en une implémentation qui résiste à une revue stricte sur un appareil réel — pas dans le simulateur, pas sur un téléphone phare en mode dev.
Le mobile change trois choses à propos de l'animation, et tout dans ce skill en découle :
- Il n'y a pas de survol. Chaque affordance que le web place dans le survol doit vivre dans la pression, la position, ou rien.
- Il y a deux runtimes. Les worklets (Reanimated 4) rendent cela explicite : le runtime React Native, où React fait le rendu et où votre logique applicative s'exécute, et le runtime UI, où les worklets s'exécutent à chaque image (plus des runtimes workers optionnels pour le travail en arrière-plan). Une animation qui touche le runtime RN saccade dès que l'application fait autre chose. Tout l'art est de maintenir le motion sur le runtime UI.
- Le doigt de l'utilisateur est sur l'élément. Les gestes sont l'entrée principale, donc l'interruptibilité et le transfert de vélocité ne sont pas du polissage — ils sont la base.
Posture opérationnelle
Vous êtes un ingénieur mobile senior qui construit l'animation vous-même. Prenez la décision, énoncez le raisonnement en une ligne, écrivez le code. Ne présentez jamais les options de motion comme un menu.
Deux modes d'échec, et le premier est le pire :
- Animer quelque chose qui ne devrait pas être animé. La porte ci-dessous existe pour produire zéro ligne de code parfois.
- Animer la bonne chose sur le mauvais thread — un
setStatepar image, unPanResponder, uneheightanimée. Cela semble bien en dev sur votre téléphone et tombe à 20fps sur un Android de trois ans.
Règles strictes
- Exécutez la séquence dans l'ordre. Les étapes 1 et 2 conditionnent tout.
- Reanimated, pas le
Animatedde base. LeAnimatedde base ne peut pas être piloté par un geste sans traverser le pont, etuseNativeDriverrefuse tout sauf transform et opacity de toute façon. Les worklets Reanimated s'exécutent sur le thread UI et continuent de s'exécuter pendant que JS est occupé. - Pas de valeurs approximatives. Les courbes et les configurations de ressort proviennent des tableaux ci-dessous.
- Le motion réduit est livré avec l'animation, pas en tant que suivi.
- La sensation est jugée sur une version release sur l'appareil le plus lent que vous supportez. Rien d'autre n'est considéré comme vérifié.
La séquence de construction
1. Cela devrait-il être animé du tout ?
| Fréquence | Décision |
|---|---|
| 100+ fois/jour — changements d'onglets, ouverture/fermeture du clavier, défilement, bascules dans les paramètres | Pas d'animation. Valeur par défaut de la plateforme ou rien. Arrêtez-vous ici. |
| Des dizaines de fois/jour — retour de pression, navigation dans une liste, sélection de ligne | Presque imperceptible seulement : moins de 150ms, ou rien |
| Occasionnel — feuilles, modales, toasts, étapes d'intégration | Animation standard |
| Rare / première fois — états de succès, illustrations d'état vide, célébration | Le budget de plaisir vit ici |
Les onglets ne glissent jamais. Les onglets sont des pairs, pas une hiérarchie — glisser implique une profondeur qui n'existe pas, et l'utilisateur paie pour cela des dizaines de fois par session. animation: 'none'.
Si la demande échoue à cette porte, dites-le et ne l'écrivez pas.
2. Quel est le but ?
Nommez-le en un mot avant de continuer : feedback, cohérence spatiale, indication d'état, prévention d'un changement brusque, explication, ou plaisir (niveau rare uniquement).
Vous ne pouvez pas le nommer ? Ne le construisez pas.
3. Choisissez l'outil — le moins cher qui fonctionne
Descendez ; arrêtez-vous au premier qui convient.
| Besoin | Outil |
|---|---|
| Un changement piloté par l'état sans geste — pression, bascule, couleur, une valeur qui change | Transition CSS Reanimated (transitionProperty dans le style) |
| Boucle, plusieurs étapes, ou se joue au montage sans changement d'état | Animation CSS Reanimated (animationName keyframes) |
| Un élément qui se monte ou se démonte, ou une liste qui se réorganise | Animations de layout (entering / exiting / itemLayoutAnimation) |
| Tout ce qu'un doigt touche, ou tout ce qui dérive d'un défilement | useSharedValue + Gesture + useAnimatedStyle |
| Écran à écran | Options de stack native dans Expo Router. Ne faites jamais cela à la main |
| Une feuille inférieure qui est son propre écran | presentation: 'formSheet' — c'est un vrai UISheetPresentationController, gratuit et correct |
| Barre d'onglets | NativeTabs (depuis expo-router/unstable-native-tabs) — la vraie barre d'onglets de la plateforme, ses comportements et transitions inclus |
| Menu contextuel, aperçu par appui prolongé | Link.Menu / Link.Preview (Expo Router, iOS uniquement) — menus natifs et aperçus, jamais reconstruits en JS |
| En-tête qui se réduit en un grand titre | headerLargeTitleEnabled sur la stack native (iOS uniquement ; headerLargeTitle est déprécié) — pas un worklet de défilement |
| Pull to refresh | RefreshControl — faites-le à la main seulement quand c'est une interaction signature (voir la recette de seuil) |
| UI qui suit le clavier | react-native-keyboard-controller — la position réelle du clavier, image par image, sur le thread UI |
| Illustration vectorielle, célébration, état vide | Lottie — pour l'illustration seulement, jamais pour l'état UI |
| Une scène animée immense, dessin libre | @shopify/react-native-skia — un canevas, pour quand la hiérarchie des vues elle-même est le goulot d'étranglement |
N'utilisez une valeur partagée que lorsque la valeur est continue ou interruptible. Une échelle de pression est une transition CSS ; un glissement est une valeur partagée. Utiliser un worklet pour une bascule à deux états est l'équivalent mobile d'installer une bibliothèque de motion pour un fondu.
Dépendances. Installez avec npx expo install <package> — cela résout la version qui correspond au SDK du projet, ce que npm install ne fera pas :
| Besoin | Package |
|---|---|
| Animation | react-native-reanimated + react-native-worklets |
| Gestes | react-native-gesture-handler |
| Navigation, feuilles, onglets natifs, menus | expo-router |
| Haptiques | expo-haptics |
| UI suivant le clavier | react-native-keyboard-controller (nécessite KeyboardProvider à la racine — voir la recette du clavier) |
| Illustration, célébration | lottie-react-native |
| Scènes animées très grandes, dessin personnalisé | @shopify/react-native-skia |
4. Choisissez les propriétés
transformetopacitysont gratuits. Tout le reste est un passage de layout.width,height,margin,padding,flex,top,left,gapréexécutent Yoga à chaque image pour ce nœud et ses frères.- La seule exception : un élément positionné en absolu sans enfants — une pilule d'onglet, un remplissage de barre de progression. Il est hors du flux, donc rien d'autre ne se réorganise, et animer
widthconserve le rayon de bordure quescaleXétalerait. - Jamais
scale(0). Commencez àscale(0.9–0.97)+opacity: 0. Rien dans le monde réel n'apparaît de rien. transformest un tableau et l'ordre compte —[{ translateY }, { scale }]met à l'échelle après avoir déplacé ; inversé, la translation est également mise à l'échelle. Gardez la translation en premier sauf si vous voulez la multiplication.- Les ombres Android sont
elevation, et animer l'élévation refait le rendu de l'ombre à chaque image. Animez plutôt l'opacité d'une couche pré-ombragée. - N'animez jamais l'intensité de
BlurView. Sur Android, cela refait le rendu du flou à chaque image. Croisez plutôt l'opacité d'unBlurViewstatique. - Les pourcentages fonctionnent dans
translateet sont relatifs à la taille propre de l'élément —translateY('100%')déplace une feuille de sa propre hauteur quel que soit son contenu.
5. Timing ou ressort
Si un doigt a été impliqué, utilisez un ressort. Les ressorts transportent la vélocité à travers une interruption ; les courbes de timing redémarrent. Tout le reste utilise le timing.
Le ressort de Reanimated prend directement les deux paramètres de conception d'Apple — utilisez cette forme, pas mass/stiffness/damping :
| Interaction | Configuration |
|---|---|
| Stabilisation par défaut, sans dépassement | { duration: 400, dampingRatio: 1 } |
| Repositionnement / retour après un glissement | { duration: 400, dampingRatio: 0.8, velocity } |
| Feuille, tiroir | { duration: 300, dampingRatio: 0.8, velocity } |
| Ne doit pas dépasser un bord dur | ajoutez overshootClamping: true |
Rebond seulement quand le geste a porté de l'élan. Un dépassement sur un menu qui est apparu en fondu semble faux ; un dépassement sur une carte que vous avez lancée semble juste.
Easing, pour tout ce qui n'a pas de doigt dessus :
| Situation | Easing |
|---|---|
| Entrée ou sortie | ease-out |
| Déplacement / morphing à l'écran | ease-in-out |
| Mouvement constant (progression, marquee) | linear |
| Par défaut | ease-out |
Jamais ease-in sur l'UI. Cela commence lentement, retardant le moment exact que l'utilisateur regarde. Les fonctions intégrées de Reanimated sont aussi faibles que celles de CSS — utilisez celles-ci :
import { Easing } from "react-native-reanimated";
const EASE_OUT = Easing.bezier(0.23, 1, 0.32, 1); // strong ease-out pour l'UI
const EASE_IN_OUT = Easing.bezier(0.77, 0, 0.175, 1); // mouvement à l'écran
const EASE_SHEET = Easing.bezier(0.32, 0.72, 0, 1); // courbe de feuille iOS
Durée :
| Élément | Durée |
|---|---|
| Retour de pression | 100–150ms |
| Bascule, chip, petit changement d'état | 150–200ms |
| Feuille, modale, tiroir | ressort, ~300ms perçus |
| Transition d'écran | la valeur par défaut de la plateforme — ne la remplacez pas |
Les animations UI mobiles restent sous 300ms, comme sur le web. Les propres transitions de la plateforme sont plus longues (la poussée iOS est à 350ms) ; correspond à la plateforme pour la navigation, battez-la partout ailleurs.
6. Gardez-le hors du thread JS
C'est le savoir-faire spécifique au mobile, et c'est là que la plupart des motions React Native meurent.
- Jamais
setStatedepuis un gestionnaire de geste ou de défilement. Un rendu React par image est la cause numéro un de saccades dans les applications RN. Valeur partagée →useAnimatedStyle, et React ne refait jamais le rendu du tout. - Ne planifiez jamais un retour vers le runtime RN à l'intérieur de
onUpdateou d'un gestionnaire de défilement.scheduleOnRN(fn, ...args)depuisreact-native-worklets— le remplacement Reanimated 4 du dépréciérunOnJS(fn)(...args)— met en file d'attente un appel du runtime RN, et dansonUpdate, c'est 60–120× par seconde. Il appartient àonEnd, ou dans unuseAnimatedReactionqui se déclenche quand une valeur franchit un seuil. - Ne lisez jamais une valeur partagée pendant le rendu (
translateY.get()dans du JSX). C'est un instantané qui ne se met jamais à jour et il le fait silencieusement...