Animationen in Expo bauen
Dieses Repository (Asymmetric-al/core)
Diese Fähigkeit ist ausschließlich für React Native / Expo Motion gedacht. Core Next.js-Apps sollten stattdessen animate, emil-design-engineering und anim verwenden. Stimmen Sie dieses Overlay nach Upstream-Aktualisierungen ab, bevor Sie bun run skills:sync ausführen.
Auslöser
- Explizite Expo- oder React Native-Animationen, Gesten, Sheets oder Haptik.
- Nicht laden für Core Web-Apps (
apps/admin,apps/donor,apps/missionary) oder geteiltepackages/uiWeb-Motion.
Arbeitsablauf
- Bestätigen Sie, dass die Anfrage nativ/Expo ist, bevor Sie Reanimated-Rezepte anwenden.
- Hören Sie bei Core Next.js-Oberflächen auf und laden Sie
animateplusanim.
Checkliste
- Die Zielplattform ist Expo/React Native, nicht Cores App Router-Apps.
- Web-Motion folgt weiterhin Core-Tokens und Base UI.
Eine Konstruktionsfähigkeit für React Native. Sie verwandelt eine Anfrage nach Bewegung in eine Implementierung, die einer strengen Überprüfung auf einem echten Gerät standhält – nicht im Simulator, nicht auf einem Flaggschiff-Telefon im Entwicklermodus.
Mobile Plattformen ändern drei Dinge an Animationen, und alles in dieser Fähigkeit folgt daraus:
- Es gibt keinen Hover. Jede Interaktionsmöglichkeit, die das Web in Hover legt, muss in Druck, Position oder nichts existieren.
- Es gibt zwei Laufzeiten. Worklets (Reanimated 4) machen dies explizit: die React Native-Laufzeit, in der React rendert und Ihre App-Logik läuft, und die UI-Laufzeit, in der Worklets jeden Frame ausführen (plus optionale Worker-Laufzeiten für Hintergrundarbeit). Eine Animation, die die RN-Laufzeit berührt, ruckelt, sobald die App etwas anderes tut. Die ganze Kunst besteht darin, die Bewegung auf der UI-Laufzeit zu halten.
- Der Finger des Benutzers liegt auf dem Element. Gesten sind die primäre Eingabe, daher sind Unterbrechbarkeit und Geschwindigkeitsübergabe keine Verfeinerung – sie sind die Basis.
Arbeitsweise
Sie sind ein leitender Mobile-Ingenieur, der die Animation selbst baut. Treffen Sie die Entscheidung, geben Sie die Begründung in einem Satz an, schreiben Sie den Code. Präsentieren Sie niemals Bewegungsoptionen als Menü.
Zwei Fehlermodi, und der erste ist schlimmer:
- Etwas animieren, das nicht animiert werden sollte. Die folgende Hürde existiert, um manchmal null Zeilen Code zu produzieren.
- Das Richtige auf dem falschen Thread animieren – ein
setStatepro Frame, einPanResponder, eine animierteheight. Es sieht im Entwicklungsmodus auf Ihrem Telefon gut aus und fällt auf einem drei Jahre alten Android auf 20 fps.
Harte Regeln
- Führen Sie die Sequenz in der Reihenfolge aus. Die Schritte 1 und 2 sind das Tor zu allem.
- Reanimated, nicht das Kern-
Animated. Kern-Animatedkann nicht von einer Geste gesteuert werden, ohne die Brücke zu überqueren, unduseNativeDriverweigert sich ohnehin alles außer Transform und Opacity. Reanimated-Worklets laufen auf dem UI-Thread und laufen weiter, während JS beschäftigt ist. - Keine angenäherten Werte. Kurven und Federkonfigurationen stammen aus den folgenden Tabellen.
- Reduzierte Bewegung wird mit der Animation ausgeliefert, nicht als nachträgliche Änderung.
- Das Gefühl wird auf einem Release-Build auf dem langsamsten unterstützten Gerät bewertet. Nichts anderes zählt als verifiziert.
Die Bau-Sequenz
1. Sollte dies überhaupt animieren?
| Häufigkeit | Entscheidung |
|---|---|
| 100+ mal/Tag – Tab-Wechsel, Tastatur öffnen/schließen, Scrollen, Umschalter in Einstellungen | Keine Animation. Plattform-Standard oder nichts. Hier anhalten. |
| Dutzende mal/Tag – Druck-Feedback, Listennavigation, Zeilenauswahl | Nur kaum wahrnehmbar: unter 150ms, oder nichts |
| Gelegentlich – Sheets, Modals, Toasts, Onboarding-Schritte | Standard-Animation |
| Selten / zum ersten Mal – Erfolgszustände, Leerzustands-Illustrationen, Feierlichkeiten | Das Freudenbudget lebt hier |
Tab-Wechsel gleiten nie. Tabs sind gleichrangig, keine Hierarchie – Gleiten impliziert Tiefe, die nicht da ist, und der Benutzer bezahlt dutzende Male pro Sitzung dafür. animation: 'none'.
Wenn die Anfrage diese Hürde nicht besteht, sagen Sie das und schreiben Sie nichts.
2. Was ist der Zweck?
Benennen Sie es in einem Wort, bevor Sie fortfahren: Feedback, räumliche Konsistenz, Zustandsanzeige, Verhindern einer ruckartigen Änderung, Erklärung oder Freude (nur seltene Kategorie).
Können Sie es nicht benennen? Bauen Sie es nicht.
3. Wählen Sie das Werkzeug – das günstigste, das funktioniert
Gehen Sie die Liste durch; halten Sie beim ersten an, das passt.
| Bedarf | Werkzeug |
|---|---|
| Eine zustandsgesteuerte Änderung ohne Geste – Druck, Umschalter, Farbe, ein Wert, der umkippt | Reanimated CSS-Übergang (transitionProperty im Style) |
| Schleife, mehrstufig oder startet beim Mounten ohne Zustandsänderung | Reanimated CSS-Animation (animationName Keyframes) |
| Ein Element, das ein- oder ausgeblendet wird, oder eine Liste, die sich umordnet | Layout-Animationen (entering / exiting / itemLayoutAnimation) |
| Alles, was ein Finger berührt, oder alles, was vom Scrollen abgeleitet wird | useSharedValue + Gesture + useAnimatedStyle |
| Bildschirm zu Bildschirm | Native Stack-Optionen in Expo Router. Niemals selbst bauen |
| Ein Bottom Sheet, das ein eigener Bildschirm ist | presentation: 'formSheet' – es ist ein echter UISheetPresentationController, kostenlos und korrekt |
| Tab-Leiste | NativeTabs (von expo-router/unstable-native-tabs) – die echte Tab-Leiste der Plattform, inklusive ihrer Verhalten und Übergänge |
| Kontextmenü, Drücken-und-Halten-Vorschau | Link.Menu / Link.Preview (Expo Router, nur iOS) – native Menüs und Peek, nie in JS neu gebaut |
| Kopfzeile, die in einen großen Titel zusammenfällt | headerLargeTitleEnabled auf dem nativen Stack (nur iOS; headerLargeTitle ist veraltet) – kein Scroll-Worklet |
| Pull-to-Refresh | RefreshControl – nur selbst bauen, wenn es eine signifikante Interaktion ist (siehe das Schwellenwert-Rezept) |
| UI, die der Tastatur folgt | react-native-keyboard-controller – die echte Position der Tastatur, Frame für Frame, auf dem UI-Thread |
| Vektorgrafik-Illustration, Feierlichkeit, Leerzustand | Lottie – nur für Illustration, niemals für UI-Zustand |
| Eine riesige animierte Szene, Freihandzeichnen | @shopify/react-native-skia – eine Leinwand, wenn die Ansichtshierarchie selbst der Engpass ist |
Greifen Sie nur zu einem geteilten Wert, wenn der Wert kontinuierlich oder unterbrechbar ist. Ein Drücken-Skalieren ist ein CSS-Übergang; ein Ziehen ist ein geteilter Wert. Die Verwendung eines Worklets für einen Zwei-Zustands-Umschalter ist das mobile Äquivalent zur Installation einer Bewegungsbibliothek für eine Einblendung.
Abhängigkeiten. Installieren Sie mit npx expo install <package> – es löst die Version auf, die zum SDK des Projekts passt, was einfaches npm install nicht tut:
| Bedarf | Paket |
|---|---|
| Animation | react-native-reanimated + react-native-worklets |
| Gesten | react-native-gesture-handler |
| Navigation, Sheets, native Tabs, Menüs | expo-router |
| Haptik | expo-haptics |
| Tastatur-folgende UI | react-native-keyboard-controller (benötigt KeyboardProvider an der Wurzel – siehe das Tastatur-Rezept) |
| Illustration, Feierlichkeit | lottie-react-native |
| Sehr große animierte Szenen, benutzerdefinierte Zeichnung | @shopify/react-native-skia |
4. Wählen Sie die Eigenschaften
transformundopacitysind kostenlos. Alles andere ist ein Layout-Durchlauf.width,height,margin,padding,flex,top,left,gapführen Yoga für diesen Knoten und seine Geschwister bei jedem Frame neu aus.- Die eine Ausnahme: ein absolut positioniertes Element ohne Kinder – eine Tab-Pille, ein Fortschrittsbalken. Es ist aus dem Fluss genommen, also wird nichts anderes neu angeordnet, und das Animieren von
widthbehält den Eckradius, denscaleXverschmieren würde. - Niemals
scale(0). Beginnen Sie mitscale(0.9–0.97)+opacity: 0. Nichts in der realen Welt erscheint aus dem Nichts. transformist ein Array, und die Reihenfolge ist wichtig –[{ translateY }, { scale }]skaliert nach dem Verschieben; umgekehrt wird auch das Verschieben skaliert. Halten Sie translate zuerst, es sei denn, Sie wollen die Multiplikation.- Android-Schatten sind
elevation, und das Animieren von Elevation rendert den Schatten bei jedem Frame neu. Animieren Sie stattdessen die Opazität einer bereits mit Schatten versehenen Ebene. - Animieren Sie niemals die Intensität von
BlurView. Auf Android rendert es die Unschärfe bei jedem Frame neu. Blenden Sie stattdessen die Opazität eines statischenBlurViewüber. - Prozentangaben funktionieren in
translateund sind relativ zur eigenen Größe des Elements –translateY('100%')bewegt ein Sheet um seine eigene Höhe, unabhängig vom Inhalt.
5. Timing oder Feder
Wenn ein Finger beteiligt war, verwenden Sie eine Feder. Federn tragen Geschwindigkeit durch eine Unterbrechung; Timing-Kurven starten neu. Alles andere verwendet Timing.
Reanimateds Feder verwendet Apples zwei Designer-Parameter direkt – verwenden Sie diese Form, nicht Masse/Steifigkeit/Dämpfung:
| Interaktion | Konfiguration |
|---|---|
| Standard-Setzen, kein Überschwingen | { duration: 400, dampingRatio: 1 } |
| Neupositionieren / Zurückschnappen nach einem Zug | { duration: 400, dampingRatio: 0.8, velocity } |
| Sheet, Drawer | { duration: 300, dampingRatio: 0.8, velocity } |
| Darf eine harte Kante nicht überschreiten | overshootClamping: true hinzufügen |
Federn nur, wenn die Geste Schwung hatte. Überschwingen bei einem Menü, das eingeblendet wurde, fühlt sich falsch an; Überschwingen bei einer Karte, die Sie geworfen haben, fühlt sich richtig an.
Easing, für alles ohne Finger darauf:
| Situation | Easing |
|---|---|
| Eintreten oder Verlassen | ease-out |
| Bewegen / Umformen auf dem Bildschirm | ease-in-out |
| Konstante Bewegung (Fortschritt, Laufschrift) | linear |
| Standard | ease-out |
Niemals ease-in auf der UI. Es beginnt langsam und verzögert den genauen Moment, den der Benutzer beobachtet. Die integrierten Easing-Funktionen von Reanimated sind so schwach wie die von CSS – verwenden Sie diese:
import { Easing } from "react-native-reanimated";
const EASE_OUT = Easing.bezier(0.23, 1, 0.32, 1); // starkes ease-out für UI
const EASE_IN_OUT = Easing.bezier(0.77, 0, 0.175, 1); // Bewegung auf dem Bildschirm
const EASE_SHEET = Easing.bezier(0.32, 0.72, 0, 1); // iOS-Sheet-Kurve
Dauer:
| Element | Dauer |
|---|---|
| Druck-Feedback | 100–150ms |
| Umschalter, Chip, kleine Zustandsänderung | 150–200ms |
| Sheet, Modal, Drawer | Feder, ~300ms wahrgenommen |
| Bildschirmübergang | der Plattform-Standard – nicht überschreiben |
Mobile UI-Animationen bleiben unter 300ms, genau wie im Web. Die eigenen Übergänge der Plattform sind länger (iOS Push ist 350ms); passen Sie sich der Plattform für die Navigation an, schlagen Sie sie überall sonst.
6. Halten Sie es vom JS-Thread fern
Dies ist die mobile-spezifische Kunst und der Punkt, an dem die meiste React Native-Bewegung stirbt.
- Niemals
setStatevon einem Gesten- oder Scroll-Handler aus aufrufen. Ein React-Render pro Frame ist die häufigste Ursache für Ruckeln in RN-Apps. Shared Value →useAnimatedStyle, und React rendert nie neu. - Niemals innerhalb von
onUpdateoder einem Scroll-Handler zur RN-Laufzeit zurückplanen.scheduleOnRN(fn, ...args)vonreact-native-worklets– der Reanimated 4-Ersatz für das veralteterunOnJS(fn)(...args)– reiht einen RN-Laufzeit-Aufruf ein, und inonUpdatesind das 60–120 mal pro Sekunde. Es gehört inonEndoder in eineuseAnimatedReaction, die ausgelöst wird, wenn ein Wert einen Schwellenwert überschreitet. - Niemals einen geteilten Wert während des Renderings lesen (
translateY.get()in JSX). Es ist ein Schnappschuss, der nie aktualisiert wird, und er wird heimlich …