Communitygithub.com

therts649-ai/Claude-Skills

在 React Native 和 Expo 中建構動畫,以正確的順序做出決定,確保動作感覺流暢自然。使用 Reanimated、Gesture Handler、Expo Router 和 expo-haptics 實作。

Claude-Skills 是什麼?

這個技能是專為在 Expo 和 React Native 應用程式中建構高效能、感覺自然的動畫而設計。它遵循一套嚴謹的決策流程,從判斷某個元素「是否應該有動畫」開始,接著定義其目的,最後選擇最經濟有效的工具來實作。此技能特別強調在行動裝置上與網頁上的差異,例如沒有懸停狀態、存在 React 和 UI 兩個執行緒,以及使用者手指直接觸碰元素。它採用一套嚴格的規則,包含優先使用 Reanimated 而非核心的 `Animated` 函式庫、避免近似值、在發行版本和最低階裝置上測試,以及預設支援減少動畫模式。支援的平台包括 Expo、React Native、iOS 和 Android。此技能會引導使用者完成一個建構序列,涵蓋動畫時機選擇、屬性選擇(例如優先使用 `transform` 和 `opacity`)、彈簧或時間曲線的配置,以及確保動畫在 UI 執行緒上執行以避免卡頓。此外,也涵蓋觸覺回饋和無障礙功能的整合。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/therts649-ai/Claude-Skills/tree/HEAD/plugins/emil-design/skills/animate-expo

在你喜歡的 AI 中提問

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

說明文件

在 Expo 中建構動畫

初始回應

當此技能首次被調用但沒有特定問題時,僅回覆:

我已經準備好在 Expo 和 React Native 中建構動畫,讓它們在真實裝置上感覺流暢自然,我的知識來自 Emil Kowalski 的動畫哲學。

在使用者提問之前,不要提供任何其他資訊。

一個針對 React Native 的建構技能。它能將一個動作請求,轉變為在真實裝置上經得起嚴格審查的實作——不是在模擬器中,也不是在開發模式的旗艦手機上。

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

  1. 沒有懸停狀態。 網頁上所有放在懸停狀態中的提示,都必須存在於按壓、位置或不存在。
  2. 有兩個執行緒。 Worklets (Reanimated 4) 讓這點更明確:React Native 執行緒,React 在此進行渲染且你的應用邏輯在此執行;以及 UI 執行緒,worklet 在此每一幀執行(加上可選的工作執行緒用於背景工作)。一個觸及 React Native 執行緒的動畫,只要應用程式做任何其他事就會卡頓。整個技藝就在於將動畫保持在 UI 執行緒上。
  3. 使用者的手指在元素上。 手勢是主要的輸入方式,因此可中斷性和速度傳遞不是錦上添花,而是基本要求。

運作姿態

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

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

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

嚴格規則

  1. 依序執行步驟。 步驟 1 和 2 是所有事情的關卡。
  2. 使用 Reanimated,而非核心的 Animated。 核心的 Animated 無法在不跨越橋接的情況下被手勢驅動,而且 useNativeDriver 無論如何只接受 transform 和 opacity。Reanimated worklet 在 UI 執行緒上執行,並在 JS 忙碌時持續運行。
  3. 不要使用近似值。 曲線和彈簧配置來自下面的表格。
  4. 減少動畫模式與動畫一同推出,而非後續才加入。
  5. 在支援的最慢裝置上,以發行版本來判斷手感。 其他任何方式都不算驗證通過。

建構序列

1. 這個東西應該要有動畫嗎?

頻率決定
每天 100 次以上——分頁切換、鍵盤開啟/關閉、滾動、設定中的切換開關不要動畫。 使用平台預設值或什麼都不做。在此停止。
每天數十次——按壓回饋、列表導航、行選取僅限幾乎無法察覺的動畫:低於 150ms,或什麼都沒有
偶爾——工作表、模態視窗、提示框、引導步驟標準動畫
罕見 / 首次——成功狀態、空狀態插圖、慶祝效果這類喜悅預算留在這裡

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

如果請求未通過此關卡,請直接告知且不撰寫程式碼。

2. 目的是什麼?

在繼續之前用一個詞命名它:feedback、spatial consistency、state indication、preventing a jarring change、explanation 或 delight(僅限罕見層級)。

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

3. 選擇工具——最便宜且能完成工作的

由上往下檢查;停在第一個符合條件的。

需求工具
一個由狀態驅動的變化,沒有手勢——按壓、切換、顏色、一個值的翻轉Reanimated CSS transition(在 style 中使用 transitionProperty)
迴圈、多階段,或在掛載時播放且沒有狀態變化Reanimated CSS animation(animationName 關鍵影格)
一個元素正在掛載或卸載,或一個列表正在重新排列Layout animations(entering / exiting / itemLayoutAnimation)
使用者手指觸及的任何東西,或任何從滾動衍生而來的東西useSharedValue + Gesture + useAnimatedStyle
螢幕切換Expo Router 中的 Native stack options。 永遠不要手動實作
一個本身就是一個畫面的底部工作表presentation: 'formSheet'——它是真正的 UISheetPresentationController,免費且正確
分頁列NativeTabs(來自 expo-router/unstable-native-tabs)——平台真正的分頁列,包含其行為和轉場
上下文選單、長按預覽Link.Menu / Link.Preview(Expo Router,僅限 iOS)——原生選單和 Peek,永遠不在 JS 中重建
折疊成大字型標題的標題native stack 上的 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 會每幀重新渲染陰影。 改為動畫化一個預先設定陰影的圖層的 opacity。
  • 永遠不要動畫化 BlurView intensity。 在 Android 上它會每幀重新渲染模糊效果。改為對一個靜態的 BlurView 進行 opacity 的交叉淡入。
  • 百分比在 translate 中有效,且相對於元素自身大小——translateY('100%') 會根據其內容將一個工作表移動其自身高度。

5. 時間曲線還是彈簧

如果手指有參與,使用彈簧。 彈簧可以在中斷時攜帶速度;時間曲線則會重新開始。其他所有情況使用時間曲線。

Reanimated 的彈簧直接使用 Apple 的兩個設計師參數——使用此形式,而非質量/剛度/阻尼:

互動配置
預設穩定,無超調{ 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。 每幀一次 React 渲染是導致 RN 應用程式卡頓的最大單一原因。共享值 -> useAnimatedStyle,React 就完全不會重新渲染。
  • 永遠不要在 onUpdate 或滾動處理器內部排程回到 RN 執行緒。 react-native-worklets 中的 scheduleOnRN(fn, ...args)——Reanimated 4 中取代已棄用的 runOnJS(fn)(...args) 的方法——會將一個 RN 執行緒呼叫排入佇列,而在 onUpdate 中,這個頻率是每秒 60–120 次。它應該用在 onEnd,或是在 useAnimatedReaction 中,當某個值超過閾值時觸發。
  • 永遠不要在渲染期間讀取共享值(在 JSX 中使用 translateY.get())。它是一個從不更新的快照,並且會默默地失去同步。在渲染期間也永遠不要寫入共享值——它會在協調過程中觸發,並且一個不是你造成的重新渲染會重播這個寫入。只在 worklet、處理器和 effects 中觸碰共享值。
  • 使用 .get() / .set(),而不是 .value。 相同的 API,但直接的 .value 存取是 React Compiler 無法解析的形式——Reanimated 文件將 get/set 稱為編譯器安全的方式。set 也接受一個函數式更新:sv.set((v) => v + 1)。
  • 從 worklet 呼叫的函數需要 'worklet' 作為它們的第一行,否則它們會在裝置上執行時拋出錯誤,但在除錯器中卻運作正常。

7. 按壓,而非懸停

網頁上所有的懸停提示都必須重新設計,而不是移植過來。

  • 在按壓時給予回饋,在鬆開時提交動作。 等待點擊完成才顯示任何東西感覺像死了一樣——這才是使用者實際感知到的延遲。
  • 在任何可按壓的元素上,在 100–150ms 內使用 scale: 0.97,結合 Pressable 和一個 CSS 過渡。scale 會帶著標籤和圖示一起縮放,這讓它感覺起來像物理世界。
  • 最小觸控目標 44×44pt(Android 是 48dp)。如果視覺元素較小,加上 hitSlop——不要放大視覺元素。
  • 使用 pressRetentionOffset,這樣手指稍微偏移幾像素不會取消使用者本想進行的按壓。
  • Android 漣漪效果僅限 Material 風格的應用程式。 在自訂設計的應用程式中,兩個平台使用相同的縮放效果比一個平台有漣漪更一致。

8. 觸覺回饋

行動裝置擁有網頁所沒有的感官。謹慎使用它,它會成為讓應用程式感覺昂貴的關鍵;到處使用它,使用者就會關掉它。

時機呼叫
一個值經過一個步驟——選取器、滑桿定位點、分段控制Haptics.selectionAsync()
某物卡入定位、工作表定位點卡住、拖曳提交Haptics.impactAsync(ImpactFeedbackStyle.Light)
重物落地、破壞性動作觸發Haptics.impactAsync(ImpactFeedbackStyle.Medium)
操作成功或失敗Haptics.notificationAsync(NotificationFeedbackType.Success / Error)

三個規則,且是絕對的:

  • 與視覺效果在同一幀。 一個延遲於其動畫的觸覺回饋讀起來像一個錯誤,而不是回饋。在因果發生的時刻觸發它——例如定位點卡住的那一刻——而不是在動畫完成時。
  • 每個使用者動作一次。 永遠不要在滾動時、每幀、或在一個使用者未觸發的進入動畫上使用。
  • 永遠不要作為唯一的回饋。 對許多使用者來說,觸覺回饋在系統層級是關閉的,且在大多數 Android 硬體上是靜音的。視覺效果必須能夠獨當一面。

從 worklet 中,觸覺回饋必須被排程回 RN 執行緒:scheduleOnRN(Haptics.selectionAsync)。

9. 減少動畫與無障礙功能

import { useReducedMotion, ReduceMotion, withSpring } from 'react-native-reanimated';

const reduced = useReducedMotion();
const y = useSharedValue(reduced ? 0 : SHEET_HEIGHT);

// 或讓每個動畫自行決定
withSpring(0, { duration: 300, dampingRatio: 0.8, reduceMotion: ReduceMotion.System });

減少動畫意味著更少且更溫和,而不是完全沒有:保留解釋狀態變化的 opacity 和顏色變化,移除位移、縮放、視差和超調。螢幕轉場變成 animation: 'fade'。

文字縮放。 allowFontScaling 預設為開啟,因此你在預設字體大小下測量的任何高度,在 200% 縮放下都是錯誤的。永遠不要對一個寫死的高度做動畫——使用 onLayout 測量,或改為對一個 transform 做動畫。

會默默破壞動畫的設定

當「動畫就是不執行」時,優先檢查這些:

  • 透過 Expo 安裝,以確保版本與 SDK 匹配:npx expo install react-native-reanimated react-native-worklets。在 Expo 專案中,babel-preset-expo 會自動配置 worklets 的 Babel 插件——不需要 babel.config.js 的步驟。只有沒有該預設的純 RN 專案才需要手動加入該插件,一個

…

[為翻譯而截斷]

Individual skills in this repo

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

相關技能