在 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 打造的建構技能。它能將一個動畫需求轉化為能夠通過真實裝置上嚴格審查的實作 — 不是在模擬器裡,也不是在開發模式下的旗艦手機上。
行動裝置改變了關於動畫的三件事,此技能中的所有內容都源自於此:
- 沒有懸停狀態。 網頁上所有放在懸停中的提示,都必須存在於按壓、位置或空無一物中。
- 有兩個執行緒。 Worklets (Reanimated 4) 讓這點變得明確:React Native 執行緒,React 在其中渲染且你的應用邏輯執行;以及 UI 執行緒,worklets 在其中逐幀執行(此外還有用於背景工作的可選 Worker 執行緒)。一個觸及 RN 執行緒的動畫,會在應用程式做任何其他事情時產生卡頓。整個技藝在於讓動畫保持在 UI 執行緒上。
- 使用者的手指在元素上。 手勢是主要的輸入方式,因此可中斷性與速度傳遞不是錦上添花 — 它們是基準。
操作姿態
你是一位親自建構動畫的資深行動工程師。做出決定,用一句話說明理由,然後撰寫程式碼。永遠不要將動畫選項當作菜單呈現。
兩種失敗模式,第一種更糟:
- 動畫了不該動畫的東西。 下方的關卡有時會為了產出零行程式碼而存在。
- 在錯誤的執行緒上動畫了正確的東西 — 每幀一個
setState、一個PanResponder、一個動畫化的height。它在你的手機開發模式下看起來沒問題,但在三年前的 Android 裝置上掉到 20fps。
硬性規則
- 依序執行步驟。 步驟 1 和 2 是所有後續步驟的前提。
- 使用 Reanimated,而不是核心的
Animated。 核心的Animated無法在不跨越橋接的情況下由手勢驅動,而且useNativeDriver無論如何只接受 transform 和 opacity。Reanimated worklets 在 UI 執行緒上執行,並在 JS 忙碌時保持運作。 - 沒有近似值。 曲線和彈簧配置來自下面的表格。
- 減少動畫效果應隨動畫一起提供,而不是事後補上。
- 感受是在你支援的最慢裝置上,以 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 — 僅在它是標誌性互動時才手動實作(請參閱閾值配方) |
| 跟隨鍵盤的 UI | react-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 |
| 跟隨鍵盤的 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 }]是先移動後縮放;反過來的話,平移的量也會被縮放。除非你想要乘算的效果,否則保持 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())。它是一個永遠不會更新的快照,並且會默默地…
…
[此處內容因原始內容截斷而截斷]