Communitygithub.com

Asymmetric-al/core

僅為 Expo 和 React Native 建構動畫,使用 Reanimated、Gesture Handler、Expo Router 和 expo-haptics。當目標執行環境是 Expo 或 React Native 應用程式時使用。請勿用於 Core Next.js 的網頁動畫;網頁動畫請使用 `animate`。僅在明確調用時執行,不會自行觸發。

core 是什麼?

這個技能專為 React Native 和 Expo 應用程式的動畫開發設計,它強制執行一套嚴格的建構流程,確保動畫在真實裝置上(而非模擬器或開發模式)表現流暢。技能的核心圍繞三個移動端動畫的關鍵變化:沒有懸停狀態、存在兩個執行緒(React Runtime 與 UI Runtime),以及使用者的手指直接觸碰元素。因此,它嚴格規定必須使用 Reanimated 而非核心的 Animated API,所有動畫與手勢邏輯必須在 UI 執行緒上執行,以避免因跨執行緒溝通導致的畫面卡頓。 此技能包含一套完整的開發決策樹:從判斷「是否該有動畫」開始,接著明確動畫的「目的」,然後選擇「最便宜且有效的工具」(從 Reanimated CSS 過渡到共用值與手勢),再到選擇正確的屬性(偏好 `transform` 與 `opacity`)與時間曲線(按壓回饋用 100-150ms,手勢操作後用彈簧)。技能也詳細說明了何時應避免自製動畫,而應使用平台原生元件(如 NativeTabs、formSheet、RefreshControl),並嚴格禁止在 Tab 切換中加入滑動動畫。 最後,技能強調「降低動畫 (reduced motion)」必須隨動畫一起提供,而非事後補上,並要求提交的動畫必須在其支援的最慢裝置上以 Release 版本檢驗效能。整體而言,這是一份確保在 React Native / Expo 環境下,動畫既流暢、又符合平台習慣且不過度設計的專業指南。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Asymmetric-al/core/tree/HEAD/.agents/skills/animate-expo

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

在 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 網頁動畫中。

工作流程

  1. 在套用 Reanimated 配方前,確認需求是原生/Expo。
  2. 對於 Core 的 Next.js 頁面,請停止並載入 animate 和 anim。

檢查清單

  • 目標執行環境是 Expo/React Native,而非 Core 的 App Router 應用程式。
  • 網頁動畫仍需遵循 Core 的設計記號與 Base UI。

一個為 React Native 打造的建構技能。它能將一個動畫需求轉化為能夠通過真實裝置上嚴格審查的實作 — 不是在模擬器裡,也不是在開發模式下的旗艦手機上。

行動裝置改變了關於動畫的三件事,此技能中的所有內容都源自於此:

  1. 沒有懸停狀態。 網頁上所有放在懸停中的提示,都必須存在於按壓、位置或空無一物中。
  2. 有兩個執行緒。 Worklets (Reanimated 4) 讓這點變得明確:React Native 執行緒,React 在其中渲染且你的應用邏輯執行;以及 UI 執行緒,worklets 在其中逐幀執行(此外還有用於背景工作的可選 Worker 執行緒)。一個觸及 RN 執行緒的動畫,會在應用程式做任何其他事情時產生卡頓。整個技藝在於讓動畫保持在 UI 執行緒上。
  3. 使用者的手指在元素上。 手勢是主要的輸入方式,因此可中斷性與速度傳遞不是錦上添花 — 它們是基準。

操作姿態

你是一位親自建構動畫的資深行動工程師。做出決定,用一句話說明理由,然後撰寫程式碼。永遠不要將動畫選項當作菜單呈現。

兩種失敗模式,第一種更糟:

  1. 動畫了不該動畫的東西。 下方的關卡有時會為了產出零行程式碼而存在。
  2. 在錯誤的執行緒上動畫了正確的東西 — 每幀一個 setState、一個 PanResponder、一個動畫化的 height。它在你的手機開發模式下看起來沒問題,但在三年前的 Android 裝置上掉到 20fps。

硬性規則

  1. 依序執行步驟。 步驟 1 和 2 是所有後續步驟的前提。
  2. 使用 Reanimated,而不是核心的 Animated。 核心的 Animated 無法在不跨越橋接的情況下由手勢驅動,而且 useNativeDriver 無論如何只接受 transform 和 opacity。Reanimated worklets 在 UI 執行緒上執行,並在 JS 忙碌時保持運作。
  3. 沒有近似值。 曲線和彈簧配置來自下面的表格。
  4. 減少動畫效果應隨動畫一起提供,而不是事後補上。
  5. 感受是在你支援的最慢裝置上,以 Release 版本建置來評判的。 其他任何方式都不算驗證。

建構序列

1. 這東西真的需要動畫嗎?

頻率決定
每天 100+ 次 — 分頁切換、鍵盤開啟/關閉、滾動、設定中的開關不要動畫。 使用平台預設行為或什麼都不做。停在這裡。
每天數十次 — 按壓回饋、列表導航、行選取僅限幾乎難以察覺的:150ms 以下,或什麼都不做
偶爾 — 動作表、模態框、提示條、引導步驟標準動畫
罕見 / 首次 — 成功狀態、空白狀態插圖、慶祝動畫愉悅預算花在這裡

分頁切換永遠不要滑動。 分頁是對等的,不是層級關係 — 滑動暗示了不存在的深度,且使用者每次使用分頁都要為此付出代價。使用 animation: 'none'。

如果請求未通過此關卡,請直接告知,不要撰寫動畫。

2. 目的是什麼?

在繼續之前,用一個詞來命名它:回饋、空間一致性、狀態指示、防止突兀的變化、解釋或愉悅(僅限罕見層級)。

無法命名?就不要建構它。

3. 選擇工具 — 最便宜且有效的那個

依序向下檢查;停在第一個符合需求的工具。

需求工具
狀態驅動的變化,無手勢 — 按壓、切換、顏色、數值變化Reanimated CSS 過渡 (transitionProperty 在 style 中)
循環、多階段、或在掛載時播放且無狀態變化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 — 僅在它是標誌性互動時才手動實作(請參閱閾值配方)
跟隨鍵盤的 UIreact-native-keyboard-controller — 鍵盤的真實位置,逐幀,在 UI 執行緒上
向量插圖、慶祝動畫、空白狀態Lottie — 僅用於插圖,永遠不用於 UI 狀態
大型動畫場景、自由繪圖@shopify/react-native-skia — 一個畫布,當視圖層級本身成為瓶頸時使用

僅當數值是連續的或可中斷時,才使用共用值。按壓縮放是 CSS 過渡;拖曳是共用值。為了一個兩狀態的切換使用 worklet,就像為了淡入淡出安裝一個動畫庫一樣小題大作。

依賴套件。 使用 npx expo install <package> 安裝 — 它會解析與專案 SDK 相符的版本,這是單純的 npm install 做不到的:

需求套件
動畫react-native-reanimated + react-native-worklets
手勢react-native-gesture-handler
導航、動作表、原生分頁、選單expo-router
觸覺回饋expo-haptics
跟隨鍵盤的 UIreact-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 在前。
  • Android 陰影是 elevation,對 elevation 做動畫會每幀重新渲染陰影。 改為對一個預先有陰影的圖層的透明度做動畫。
  • 永遠不要對 BlurView 的 intensity 做動畫。 在 Android 上它每幀都會重新計算模糊效果。改為對一個靜態 BlurView 的透明度進行交叉淡入淡出。
  • 百分比在 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

僅在手勢帶有動量時才使用彈跳。 一個淡入的選單過衝感覺很奇怪;一個你撥動的卡片過衝則感覺正確。

緩動函數,用於所有沒有手指接觸的情況:

情況緩動函數
進入或離開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
動作表、模態框、抽屜spring, ~300ms 感知時間
頁面轉場平台預設 — 不要覆蓋它

行動 UI 動畫保持在 300ms 以下,與網頁相同。平台的內建轉場更長 (iOS push 是 350ms);導航時跟隨平台,其他所有地方則要做得比它快。

6. 讓它遠離 JS 執行緒

這是行動裝置特有的技藝,也是大多數 React Native 動畫失敗的地方。

  • 永遠不要從手勢或滾動處理函式中呼叫 setState。 每幀一次 React 渲染是 RN 應用程式中畫面卡頓的最大原因。使用共用值 → useAnimatedStyle,React 就完全不會重新渲染。
  • 永遠不要在 onUpdate 或滾動處理函式內部安排回到 RN 執行緒。 scheduleOnRN(fn, ...args) (來自 react-native-worklets) — 這是已棄用的 runOnJS(fn)(...args) 在 Reanimated 4 中的替代方案 — 會將一個 RN 執行緒呼叫排入佇列,而在 onUpdate 中,這是每秒 60–120 次。它屬於 onEnd,或屬於一個在數值超過閾值時觸發的 useAnimatedReaction。
  • 永遠不要在渲染期間讀取共用值 (在 JSX 中使用 translateY.get())。它是一個永遠不會更新的快照,並且會默默地…

…

[此處內容因原始內容截斷而截斷]

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

Asymmetric-al/core

Build an animation from scratch, making the decisions in the order that determines whether it feels right — should it animate at all, what purpose, which tool, which properties, which curve and duration, how it interrupts, how it exits. Writes the implementation. Use when asked to animate something, add motion, make a component feel alive, or build a transition. For critiquing existing motion use review-animations; for auditing a whole codebase use improve-animations. Only runs when explicitly invoked; it does not trigger on its own.

Asymmetric-al/core

Reverse-lookup glossary that turns a vague description of a web animation or motion effect into its exact term ("the bouncy thing when a popover opens" → Pop in; "the iOS rubber-band scroll" → Rubber-banding). Use when the user asks "what's it called when…", or describes a motion effect without knowing its name and wants the right word to prompt an AI or designer with. For naming an effect, not designing or building one.

Asymmetric-al/core

Inspect a Core UI or code surface for a small number of justified motion opportunities and explicitly identify what should remain static. Use when asked what should animate, where motion would improve feedback or comprehension, how to make an interface feel more alive without over-animating it, or whether a proposed animation is worth adding. Read-only; do not use to review or fix existing motion code or to implement animations.

Asymmetric-al/core

Survey a codebase's animation and motion code as a senior motion advisor, then produce a prioritized audit and self-contained implementation plans for other agents (or cheaper models) to execute. Read-only on source code — it plans improvements, it does not apply them. Use when the user asks to "improve the animations", "audit the motion", "make this app feel better", or wants a roadmap of animation fixes rather than a review of a single diff.

Asymmetric-al/core

Implement smooth, accessible animations with motion/react (Framer Motion) in React. Use when adding animations, gestures, or layout transitions with motion, AnimatePresence, useScroll, and related APIs. Requires a 'use client' boundary; not for strictly server-rendered components or when no animation is needed.

Asymmetric-al/core

Best practices for Remotion - Video creation in React

Asymmetric-al/core

Reviews animation and motion code against a high craft bar derived from Emil Kowalski's design engineering philosophy. Default to flagging; approval is earned.

相關技能