Communitygithub.com

CharbelElBateh/personal-website

在 React Native 和 Expo 中建構動畫,以正確順序做出決定,判斷動畫是否合適、在哪個執行緒執行、使用哪些屬性、彈簧或計時、手勢如何交接、以及如何降級。使用 Reanimated、Gesture Handler、Expo Router 和 expo-haptics 實作。適用於在 Expo 應用程式中製作任何動畫、加入手勢、底部彈出視窗、畫面轉場、按壓回饋或觸覺回饋,或修正在裝置上卡頓的動作。網頁動畫請使用 `animate`。

personal-website 是什麼?

這項 AI 技能專注於在 React Native 和 Expo 中,於真實裝置上建構感覺自然且流暢的動畫。其核心哲學源自 Emil Kowalski 的動畫理念,強調在實體裝置(而非模擬器)上進行嚴格審查。技能內容深入探討行動裝置動畫與網頁設計的關鍵差異,包括「沒有懸停狀態」、「兩個執行緒(React 執行緒與 UI 執行緒)」以及「使用者手指直接觸碰元件」等要點。它提供一套結構化的建構流程,從判斷「是否該加入動畫」(根據頻率分級)開始,接著明確「動畫目的」(如回饋、空間一致性等),並選擇最合適的工具(從 Reanimated CSS 過渡到共享值與手勢處理器)。技能也涵蓋屬性選擇指南(優先使用 transform 和 opacity)、計時與彈簧動畫的配置表、確保動畫在 UI 執行緒上執行以避免卡頓的技術、行動裝置特有「按壓取代懸停」的設計模式、以及觸覺回饋與減少動畫(reduced motion)的無障礙最佳實踐。此技能主要適用於 Cursor 和 Claude Code 等 AI 代理器,協助開發者在 Expo 應用程式中做出關於動畫的專業決策。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/CharbelElBateh/personal-website/tree/HEAD/.claude/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. 手感需在你支援的最慢裝置上,以 release 版本進行評斷。 其他情況都不算驗證通過。

建構序列

1. 這個東西到底該不該動畫化?

頻率決定
每天超過 100 次 — 切換分頁、開啟/關閉鍵盤、滾動、設定中的切換不要動畫。 使用平台預設或什麼都不做。在此停止。
每天數十次 — 按壓回饋、列表導航、行選取僅使用近乎無法察覺的動畫:低於 150ms,或什麼都不做
偶爾 — 底部彈出視窗、模態視窗、提示訊息、入門步驟標準動畫
罕見/首次 — 成功狀態、空狀態插圖、慶祝動畫樂趣預算(delight budget)在此使用

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

如果請求未通過此閘門,請說明原因並且不要撰寫動畫。

2. 目的是什麼?

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

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

3. 選擇工具——用最簡單且有效的那個

依序往下檢查;停在第一個符合條件的工具。

需求工具
由狀態驅動的變化,無手勢——按壓、切換、顏色、值翻轉Reanimated CSS transition (transitionProperty 在 style 中)
循環、多階段、或在掛載時播放且無狀態變化Reanimated CSS animation (animationName 關鍵影格)
元件掛載或卸載,或列表重新排列Layout animations (entering / exiting / itemLayoutAnimation)
任何手指觸碰的東西,或任何源自滾動的東西useSharedValue + Gesture + useAnimatedStyle
畫面到畫面轉場Expo Router 中的 Native stack 選項。 永遠不要手動打造這個
一個本身就是獨立畫面的底部彈出視窗presentation: 'formSheet' —— 這是一個真正的 UISheetPresentationController,免費且正確
分頁列NativeTabs (來自 expo-router/unstable-native-tabs) —— 平台的真正分頁列,包含其行為和轉場
上下文選單、長按預覽Link.Menu / Link.Preview (Expo Router,僅 iOS) —— 原生選單和預覽,永遠不要在 JS 中重建
可摺疊為大標題的頁首headerLargeTitleEnabled 在原生堆疊上 (僅 iOS;headerLargeTitle 已棄用) —— 不是一個滾動 worklet
下拉重新整理RefreshControl —— 只有在這是一個標誌性互動時才手動打造(參閱閾值配方)
跟隨鍵盤的 UIreact-native-keyboard-controller —— 鍵盤的實際位置,逐幀,在 UI 執行緒上
向量插圖、慶祝動畫、空狀態Lottie —— 僅用於插圖,絕不用於 UI 狀態
大型動畫場景、自由繪圖@shopify/react-native-skia —— 一個畫布,用於當檢視層次結構本身就是瓶頸時

僅當值需要連續或可中斷時才使用共享值。按壓縮放是 CSS transition;拖曳是共享值。為一個二態切換使用 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 是免費的。 其他一切都會觸發 layout pass。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 的強度。 在 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 push 是 350ms);導航時匹配平台,其他所有地方則超越它。

6. 讓它保持在 JS 執行緒之外

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

  • 永遠不要從手勢或滾動處理器中呼叫 setState。 每幀一次 React 重新渲染是 React Native 應用程式卡頓的最大單一原因。使用共享值 → useAnimatedStyle,React 就根本不會重新渲染。
  • 永遠不要在 onUpdate 或滾動處理器內排程回到 React Native 執行緒。 來自 react-native-worklets 的 scheduleOnRN(fn, ...args)——這是已棄用的 runOnJS(fn)(...args) 在 Reanimated 4 中的替代品——會佇列一個 React Native 執行緒呼叫,而在 onUpdate 中,這會是每秒 60–120 次。它應屬於 onEnd,或屬於一個在值超過閾值時觸發的 useAnimatedReaction。
  • 永遠不要在渲染期間讀取共享值(在 JSX 中使用 translateY.get())。這是一個永遠不會更新的快照,並且會默默地不同步。也永遠不要在渲染期間寫入共享值——它會在 reconciliation 中途觸發,而一個不是你導致的重新渲染會重播該寫入。僅在 worklet、處理器和 effect 中觸碰共享值。
  • 使用 .get() / .set(),而不是 .value。 API 相同,但直接存取 .value 是 React Compiler 無法穿透的形式——Reanimated 文件稱 get/set 為編譯器安全的方式。set 也支援功能性更新:sv.set((v) => v + 1)。
  • 從 worklet 呼叫的函數需要以 'worklet' 作為它們的第一行,否則它們會在裝置上運行時拋出錯誤,儘管在除錯器中可以正常工作。

7. 按壓,而非懸停

來自網頁的每個懸停提示都必須重新設計,而非移植。

  • 按壓時給回饋,鬆開時提交。 等待點擊完成才顯示任何東西會感覺死氣沉沉——這是使用者實際感知到的延遲。
  • 在任何可按壓元件上,使用 scale: 0.97 搭配 100–150ms 時間,使用 Pressable + CSS transition。scale 會同時縮放標籤和圖示,這使得它感覺像是實體的。
  • 最小觸控目標為 44×44pt(Android 為 48dp)。如果視覺元素較小,加上 hitSlop——不要放大視覺元素。
  • 使用 pressRetentionOffset,這樣手指偏移幾像素就不會取消使用者原本想進行的按壓。
  • 僅在 Material 風格應用程式中使用 Android 漣漪效果。 在自訂設計的應用程式中,兩個平台使用相同的縮放效果比一個平台用漣漪效果更連貫。

8. 觸覺回饋

行動裝置擁有網頁所沒有的感覺。節制地使用它,它會成為讓應用程式感覺昂貴的東西;到處使用它,使用者就會關閉它。

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

三個規則,而且是絕對的:

  • 與視覺效果同一幀。 落後於動畫的觸覺回饋讀起來像是故障,而不是回饋。在因果發生的時刻觸發它——也就是定位點卡住的那一刻——而不是在動畫結束時。
  • 每個使用者動作一個。 永遠不要在滾動時、每幀、或在使用者未引起的入場動畫上使用。
  • 永遠不要作為唯一的回饋。 對於許多使用者,觸覺回饋在系統層級是關閉的,並且在大多數 Android 硬體上是靜音的。視覺效果必須能夠獨立存在。

從 worklet 中,觸覺回饋必須排程回到 React Native 執行緒: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 步驟。只有一個沒有該 preset 的裸 React Native 專案才需要手動添加該插件,這

…

[為翻譯而截斷]

Individual skills in this repo

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

CharbelElBateh/personal-website

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.

CharbelElBateh/personal-website

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.

CharbelElBateh/personal-website

Apple's approach to interface design and fluid, physical motion, translated for the web. Use when building or reviewing gesture-driven UI, spring animations, drag/swipe/sheet interactions, momentum and interruptible transitions, translucent materials and depth, typography (optical sizing, tracking, leading), reduced-motion, or the design foundations (feedback, spatial consistency, restraint) behind Apple-style interfaces.

CharbelElBateh/personal-website

Guide to Sonner, the React toast library — install and wire up the Toaster, pick the right toast() call, promise and loading toasts, updating, dismissing and persisting toasts, styling, theming and icons, positioning and multiple toasters. Use when working with Sonner or troubleshooting it — toasts that don't appear, appear twice, lose their styles, ignore Tailwind classes, sit behind a modal, or don't follow dark mode.

CharbelElBateh/personal-website

Try to break a piece of UI by feeding it worst-case data — long names, unbreakable emails, one-letter names, missing fields, huge counts, zero items, long labels, non-Latin text, emoji, extreme numbers — then render it behind a "Demo data / Worst case" toggle and report everything that broke, with the fix for each. Use when the user asks to stress-test, break, or find edge cases in a component or screen, or to "try the worst case". For visual design critique use emil-design-eng; for motion use review-animations.

CharbelElBateh/personal-website

This skill encodes Emil Kowalski's philosophy on UI polish, component design, animation decisions, and the invisible details that make software feel great.

CharbelElBateh/personal-website

Search a codebase or UI for places that don't animate but should, and reject everything that shouldn't. Read-only; it proposes motion with exact values, it does not implement it. Use when the user asks "what could be animated here?" or wants to "make this feel more alive". For fixing existing animations, use improve-animations or review-animations instead.

CharbelElBateh/personal-website

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.

CharbelElBateh/personal-website

Make a web app feel native on a phone — the small CSS and meta-tag fixes that separate "a website in a browser" from something that feels installed. Covers sticky hover states, tap highlight flashes, the 100vh bug, inputs that zoom the page, laggy taps, pull-to-refresh hijacking scroll, content under the notch, long-press selecting button text, carousels that scroll the wrong way, mismatched status bars, and the rule that you test on real hardware. Use when a web app is being built for or reviewed on mobile, when something "works in Chrome but feels wrong on my phone", when building a PWA, a bottom sheet, a carousel, a full-screen layout, or any touch interaction. For motion itself use animate; for React Native use animate-expo.

CharbelElBateh/personal-website

Pick the right library for a given frontend task from a curated, opinionated list — numbers, OTP inputs, charts, command menus, virtualization, drag and drop, toasts, state, styling, and more. Only runs when explicitly invoked; it does not trigger on its own.

CharbelElBateh/personal-website

Build multiple genuinely different versions of a UI piece you describe, rendered behind a visual picker so you can flip through them live and promote the one that feels right. Only runs when explicitly invoked; it does not trigger on its own.

CharbelElBateh/personal-website

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

CharbelElBateh/personal-website

How to write modern Swift well — modeling with value types, Swift 6 data-race safety and approachable concurrency (@concurrent, main-actor-by-default, actors, task groups), protocols and generics (some vs any), API design, performance and ARC, Swift Testing, macros, and the modern language features agents don't know about yet. Use when writing, reviewing, or migrating Swift, or when a concurrency error, a hang, a data race, a retain cycle, or a performance problem needs fixing.

相關技能