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 のための建設スキルです。モーションに対するリクエストを、シミュレーターではなく、また開発モードのフラッグシップスマートフォンでもなく、実機での厳格なレビューに耐える実装に変換します。
モバイルはアニメーションに関して 3 つのことを変えます。このスキルのすべてはこれらに従います:
- ホバーは存在しません。 ウェブがホバーに置くすべてのアフォーダンスは、プレス、位置、または何もないことに存在しなければなりません。
- 2 つのランタイムがあります。 Worklets (Reanimated 4) はこれを明示します:React Native ランタイム(React がレンダリングし、アプリロジックが実行される場所)と、UI ランタイム(ワークレットが毎フレーム実行される場所。オプションでバックグラウンドワーク用のワーカランタイムもあります)。RN ランタイムに触れるアニメーションは、アプリが他のことをするたびにカクつきます。技術全体は、モーションを UI ランタイムに保つことです。
- ユーザーの指が要素の上にあります。 ジェスチャーが主要な入力であるため、割り込み可能性とベロシティのハンドオフは洗練ではなく、基本条件です。
運用姿勢
あなたはアニメーションを自分で構築するシニアモバイルエンジニアです。判断を下し、その理由を 1 行で述べ、コードを書いてください。モーションオプションをメニューとして提示しないでください。
2 つの障害モードがあり、最初のものがより悪いです:
- アニメーションすべきでないものをアニメーションすること。 以下のゲートは、時々コード行をゼロにするために存在します。
- 正しいものを間違ったスレッドでアニメーションすること — フレームごとの
setState、PanResponder、アニメーション化されたheight。開発中は自分のスマートフォンで問題なく見えますが、3 年前の Android では 20fps に落ちます。
厳格なルール
- シーケンスを順番に実行します。 ステップ 1 と 2 がすべてをゲートします。
- Reanimated、コアの
Animatedではありません。 コアのAnimatedはブリッジを越えることなくジェスチャーで駆動できず、useNativeDriverは transform と opacity 以外を拒否します。Reanimated ワークレットは UI スレッドで実行され、JS がビジーでも実行を続けます。 - 近似値は使用しません。 カーブとスプリング設定は以下のテーブルから取得します。
- 動きの抑制はフォローアップではなく、アニメーションとともに提供されます。
- 感触は、サポートする最も遅いデバイスでのリリースビルドで判断されます。 それ以外は検証済みと見なされません。
構築シーケンス
1. これはアニメーションすべきか?
| 頻度 | 判断 |
|---|---|
| 1 日に 100 回以上 — タブ切り替え、キーボードの開閉、スクロール、設定のトグル | アニメーションなし。 プラットフォームデフォルトまたは何もしない。ここで停止。 |
| 1 日に数十回 — プレスフィードバック、リストナビゲーション、行選択 | ほぼ知覚できないもののみ:150ms 未満、または何もしない |
| 時々 — シート、モーダル、トースト、オンボーディングステップ | 標準アニメーション |
| 稀 / 初回のみ — 成功状態、空状態のイラスト、祝福 | ここの歓喜予算が生きます |
タブ切り替えはスライドしません。 タブは階層ではなくピアです — スライドは存在しない深さを暗示し、ユーザーはセッション中に何十回もその代償を払います。animation: 'none'。
リクエストがこのゲートに失敗した場合は、そう言って書かないでください。
2. 目的は何か?
続行する前に一言で名前を付けてください:フィードバック、空間的一貫性、状態表示、突然の変化の防止、説明、または歓喜(稀な層のみ)。
名前を付けられない? 構築しないでください。
3. ツールを選択 — 最も安価で動作するもの
下に進み、最初に適合するもので停止します。
| ニーズ | ツール |
|---|---|
| ジェスチャーのない状態駆動の変更 — プレス、トグル、色、値の切り替え | Reanimated CSS transition (style 内の transitionProperty) |
| ループ、多段階、またはマウント時に再生され状態変更なし | Reanimated CSS animation (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 のみ) — ネイティブメニューとピーク、決して JS で再構築しない |
| 大きなタイトルに折りたたまれるヘッダー | ネイティブスタックの headerLargeTitleEnabled (iOS のみ;headerLargeTitle は非推奨) — スクロールワークレットではない |
| プル・トゥ・リフレッシュ | RefreshControl — それが特徴的なインタラクションの場合のみ自作(しきい値レシピを参照) |
| キーボードを追跡する UI | react-native-keyboard-controller — キーボードの実際の位置、フレームごとに、UI スレッド上で |
| ベクターイラスト、祝福、空状態 | Lottie — イラストのみに使用し、UI 状態には決して使用しない |
| 巨大なアニメーションシーン、フリーフォーム描画 | @shopify/react-native-skia — キャンバス、ビューハイアラーキ自体がボトルネックの場合 |
共有値に手を伸ばすのは、値が連続的または割り込み可能な場合のみです。プレススケールは CSS transition であり、ドラッグは共有値です。2 状態トグルにワークレットを使用することは、フェードのためにモーションライブラリをインストールするモバイル版です。
依存関係。 npx expo install <package> でインストールします — これはプロジェクトの SDK に一致するバージョンを解決します。プレーンな npm install では解決しません:
| ニーズ | パッケージ |
|---|---|
| アニメーション | 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 }]は移動後にスケールします;逆にすると、平行移動もスケールされます。乗算が必要な場合を除き、parallel 移動を最初に保ちます。- Android の影は
elevationであり、elevation のアニメーションは影を毎フレーム再レンダリングします。 代わりに、事前に影を設定したレイヤーの opacity をアニメーションしてください。 - 決して
BlurViewの intensity をアニメーションしないでください。 Android では、ブラーを毎フレーム再レンダリングします。代わりに、静的なBlurViewの opacity をクロスフェードしてください。 translateではパーセンテージが機能し、要素自身のサイズに相対します —translateY('100%')は、コンテンツにかかわらず、シートを自身の高さ分だけ移動します。
5. タイミングまたはスプリング
指が関与した場合は、スプリングを使用します。 スプリングはベロシティを割り込みを通じて運びます;タイミングカーブは再起動します。他のすべてはタイミングを使用します。
Reanimated のスプリングは Apple の 2 つのデザイナーパラメータを直接受け取ります — この形式を、質量/剛性/減衰ではなく使用してください:
| インタラクション | 設定 |
|---|---|
| デフォルトの沈静化、オーバーシュートなし | { duration: 400, dampingRatio: 1 } |
| ドラッグ後の再配置 / スナップバック | { duration: 400, dampingRatio: 0.8, velocity } |
| シート、ドロワー | { duration: 300, dampingRatio: 0.8, velocity } |
| ハードエッジを越えてはならない | 追加 overshootClamping: true |
バウンスは、ジェスチャーが運動量を持っていた場合のみ。 フェードインしたメニューのオーバーシュートは間違っていると感じます;フリックしたカードのオーバーシュートは正しいと感じます。
イージング、指が乗っていないすべてのものに対して:
| 状況 | イージング |
|---|---|
| 入場または退場 | ease-out |
| 画面上での移動 / 変形 | ease-in-out |
| 一定の動き(プログレス、マーキー) | linear |
| デフォルト | ease-out |
UI では決して ease-in を使用しないでください。 それは遅く始まり、ユーザーが見ているまさにその瞬間を遅らせます。Reanimated の組み込みイージングは 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を呼び出さないでください。 フレームごとの 1 回の React レンダリングは、RN アプリのカクつきの最大の原因です。共有値 →useAnimatedStyle、そして React は決して再レンダリングしません。 onUpdateまたはスクロールハンドラー内で RN ランタイムにスケジュールを戻さないでください。 非推奨のrunOnJS(fn)(...args)の代わりとなる Reanimated 4 のreact-native-workletsからのscheduleOnRN(fn, ...args)は、RN ランタイムの呼び出しをキューに入れ、onUpdateでは毎秒 60~120 回になります。これはonEnd、または値がしきい値を超えたときに発火するuseAnimatedReactionに属します。- レンダリング中に共有値を読み取らないでください(JSX 内の
translateY.get())。それは決して更新されないスナップショットであり、…(技術翻訳のため以下略)