實作動畫
概述
本技能指導如何將 Figma 的動畫與過渡效果轉譯為可執行的程式碼(motion.dev、CSS 關鍵影格,或特定框架的動畫庫)。
Figma 透過兩個工具來暴露動畫資料:
get_motion_context—— 權威性的動畫工具。回傳完整的動畫節點清單、預先計算好的程式碼片段(CSS@keyframes+ motion.dev)、當片段不可用時的備用關鍵影格綁定,以及遞迴時間軸協調提示。這是動畫資料及哪些節點 ID 會動畫化的唯一真實來源。get_design_context—— 設計的結構:佈局、尺寸、資源、樣式、Code Connect 提示、螢幕截圖上下文,以及有時會出現的動畫位置標記(位於動畫元素上的data-node-id,以及分裂節點上的data-motion-keys/data-motion-wrapper-for/data-motion-transform-template)。它可能將動畫節點渲染為純元素(div、p、span等)或 motion 元素(motion.div);它不會內嵌動畫值。
兩者透過節點 ID 連結,這也是整個工作流程的核心。 get_motion_context 告訴你哪些節點會動畫化,並提供關鍵影格值、緩動函數、時間和程式碼片段。get_design_context 則告訴你這些節點的外觀和位置。對於 get_motion_context.nodes 中的每個節點,在設計上下文中找到對應的 data-node-id,並將動畫合併到該結構中——當結構元素是純元素時,添加或包裹一個 motion.{tag}。當設計上下文重複使用了一個 Figma 組件時,動畫節點可能也包含 fallbackNodeId;僅在嘗試使用確切 nodeId 失敗後,才將其作為備用。
技能邊界
- 當交付成果是使用者儲存庫中的動畫程式碼時,使用此技能。
- 如果使用者要求在 Figma 本身內部創建/編輯動畫,請切換至 figma-use 並遵循該技能。
- 此技能目前涵蓋由
get_motion_context發出的動畫(程式碼片段以及備用關鍵影格軌道,包括由預設值解析而成的動畫)。更廣泛的互動變體流程可能仍需要產品特定的狀態處理程式碼。
先決條件
- Figma MCP 伺服器已連接且可訪問。
- 從使用者提供的 Figma URL 中解析出節點 ID。URL 格式:
https://figma.com/design/:fileKey/:fileName?node-id=1-2—— 提取fileKey(/design/後面的區段)和nodeId(node-id查詢參數的值,例如42-15)。 - 目標程式碼庫。動畫輸出格式會根據技術堆疊進行調整(請參閱框架建議)。
工具選擇
對於動畫實作,請使用兩個工具,各自扮演不同的角色:
| 情況 | 工具 | 原因 |
|---|---|---|
| 理解靜態結構、資源、樣式、Code Connect 或視覺佈局 | get_design_context | 提供正確放置動畫節點所需的組件/頁面程式碼參考和資源 URL。 |
| 獲取任何節點的動畫數據 | get_motion_context | 專為動畫設計,是時間、緩動、程式碼片段和關鍵影格的唯一真實來源。 |
節點帶有動畫標記(data-motion-keys、data-motion-wrapper-for) | 標記用於分裂的放置,get_motion_context 用於值 | 分裂標記告訴你哪個軌道屬於哪個元素;關鍵影格/緩動/時間和動畫節點清單來自 get_motion_context。 |
當你需要一次性獲取所有子孫節點的動畫時,get_motion_context 接受 recursive: true(上限為 500 個節點)。
必要工作流程
步驟 1:確認靜態設計上下文可用
get_design_context(fileKey=":fileKey", nodeId="<node-id>")
如果 get_design_context 已經為此節點調用過,請重複使用該輸出。如果沒有,則正常調用它。
將其用作權威結構——層級、尺寸、樣式、資源、Code Connect 提示、螢幕截圖上下文,以及它可能包含的任何動畫位置標記(步驟 3)。動畫節點清單和動畫值來自 get_motion_context(步驟 2)。
步驟 2:獲取權威動畫數據
get_motion_context(fileKey=":fileKey", nodeId="<node-id>", recursive=true)
回應形狀(每個動畫節點一個條目):
codeSnippets—— 預先生成的 CSS@keyframes和 motion.dev 字串。直接使用這些。 不要從備用軌道數據重新生成它們。keyframeBindings—— 綁定的關鍵影格軌道,包括由預設值解析而成的動畫軌道數據,僅在兩種片段格式都缺失時作為備用數據包含。fallbackNodeId—— 用於匹配元件化設計上下文的可選備用 ID。如果nodeId是實例限定 ID(例如I4005:6111;30:8005),D2R 可能改為使用後台組件 ID(例如4002:3957)來渲染可重複使用的組件主體。在這種情況下,fallbackNodeId是當確切nodeId查找失敗時要查找的data-node-id。
遞迴回應也可能包含 timelineCohorts:共享相同時間軸根節點、持續時間和播放模式(once、loop 或 boomerang)的動畫節點 ID 組。使用這些群組來保持交錯或多節點動畫的同步,而不是根據兄弟順序來推斷共享時間。
對大型語言模型(LLM)很重要的實作細節:
- 當片段存在時,原始的
keyframeBindings、timelineDurationMs、motionSummary和預設的transformOrigin可能會被刪除以保持負載較小。缺少keyframeBindings並不表示沒有動畫。 - 遞迴回應會對完全相同的片段進行去重。一個片段可能被替換為一個註解,指向第一個具有相同動畫的節點;重複使用相同的組件、變體、類別或常數,而不是編寫第二個動畫。
- MCP 伺服器會從
clientFrameworks推斷 CSS 與 motion.dev 片段;如果回應只包含一種片段格式,則將該格式適配到使用者的技術堆疊,而不是假設另一種格式失敗。
步驟 3:合併靜態與動畫上下文
- 從
get_motion_context.nodes開始,而不是從靜態 JSX 中可見的motion.*標籤開始。回傳的每個節點都是動畫化的。 首先,透過精確的nodeId/data-node-id將每個動畫節點匹配回get_design_context。如果且僅當沒有精確匹配時,再嘗試fallbackNodeId/data-node-id。只有在兩個 ID 都失敗後,才根據節點名稱/類型和螢幕截圖位置進行備用。 - 精確 ID 匹配優先於
fallbackNodeId。fallbackNodeId指向 D2R 可能在可重複使用組件內發出的後台組件 ID。該 ID 被該組件的每個實例共享。如果設計上下文中存在精確的nodeId,則將動畫應用於該處並忽略備用 ID。這對於根實例動畫至關重要:一個實例可能與另一個相同組件的實例以不同的方式旋轉或移動,將該動畫應用於共享的組件主體會導致所有實例的動畫都不正確。 - 將每個動畫節點應用於匹配的設計上下文結構,以
data-node-id為鍵。 匹配的data-node-id是結構錨點,不一定是最終接收動畫的 DOM 元素。使用片段形狀和位置標記來決定動畫應該放在哪個確切元素上:一個包裹器、一個內部元素、還是一個內聯的 SVG 路徑。get_design_context可能已經發出了帶有已移除值的motion.{tag},或者它可能發出一個純結構元素(div、p、span、組件根節點等)。如果它是純元素且片段目標是該元素本身,則將其轉換為適當的motion.{tag}或添加一個 motion 包裹器,同時保留節點的文字、子元素、類別/樣式、屬性和data-node-id。載入 references/examples-and-anti-examples.md 以查看此合併步驟的範例。 - 元件化的子節點動畫通常透過備用 ID 匹配。 當設計上下文將 Figma 實例提取到可重複使用的 React 組件中時,該組件主體內的子節點通常具有後台組件 ID(
4002:3957),而動畫上下文報告的是即時實例 ID(I4005:6111;30:8005)。在這種情況下,使用fallbackNodeId來查找組件主體的data-node-id,但將動畫範圍限制在你正在實作的已渲染實例內。如果有多個實例且只有一個具有不同的根動畫,精確 ID 匹配可以將該每個實例的動畫分開。 - 分裂節點帶有
data-motion-keys/data-motion-wrapper-for標記——請參閱下方的 處理交錯變換。 - 保留
display: contents包裹器——除非群組本身會動畫化。 佈局透明的群組包裹器會以contents(Tailwindcontents)的形式出現,通常伴隨著一個無效的absolute/inset-[…](它們在contents盒子上不起作用)。對於一個靜態群組,保留display: contents,讓子元素相對於最近的實際祖先定位——將包裹器的inset轉換為定位盒子會將子元素重新父級化到一個更小的盒子,導致它們渲染得太小/向內偏移。對於一個動畫化的群組(群組節點本身有動畫),display: contents無法攜帶變換——將其替換為一個真正的定位包裹器,並在那裡應用群組動畫。在實作此情況之前,請載入 references/gotchas.md。 get_motion_context是完整的動畫節點清單。 一些動畫節點渲染為純(非motion)元素——組件實例根節點(純定位<div>)、文字(<p>)、遮罩——這些元素仍然帶有data-node-id。遍歷動畫回應中的每個節點,並將其動畫應用於具有匹配data-node-id的元素,根據需要包裹或轉換。如果一個動畫節點在輸出中根本沒有對應的元素(例如,一個被扁平化為靜態mask-image的動畫遮罩),不要無聲地刪除它——請留下一個// TODO: <nodeId> 動畫不受支援的註解,並在你的摘要中提出。- 如果一個節點出現在動畫上下文中但不在靜態 JSX 中,請添加表示它所需的元素——設計上下文程式碼只是一個參考,不是完整的動畫清單。
- 在設計上下文和動畫上下文之間發生衝突時(時間/緩動/動畫值),優先使用
get_motion_context。 - 路徑層級的 SVG 動畫:內聯 SVG 並動畫化實際的
<path>。 當get_motion_context目標是向量路徑(PATH_TRIM、motion.path、stroke-dasharray)但設計上下文將其渲染為<img>時,內聯 SVG 並將片段應用於<path>,同時保留佈局包裹器。載入 references/svg-and-path-motion.md 以取得此情況的完整操作指南(motion.path、pathLength="1"、包裹器+路徑分層、CSS 路徑修剪)。
處理交錯變換
一個同時具有靜態基礎變換和動畫變換的節點會被分割到嵌套元素中,以便兩者正確組合而不是相互衝突:一個無 ID 的 motion.div 攜帶 data-motion-wrapper-for="<nodeId>"(外部包裹器)包裹一個靜態變換 div(例如 rotate-45 + hypot() 尺寸——或者包裹器本身攜帶 data-motion-transform-template="<css>"),而這個靜態變換 div 又包裹內部的節點(data-node-id)。保持 包裹器 > 靜態變換 div > 內部 的嵌套結構——將其折疊會破壞尺寸和基礎變換。
- 根據
data-motion-keys放置軌道。 包裹器的data-motion-keys(變換軌道——x/y/rotate/scaleX/scaleY/skewX)放在外部包裹器上;內部元素的data-motion-keys放在內部元素上。 - 重新應用
data-motion-transform-template。 如果包裹器帶有一個,設置transformTemplate={(_, generated) => "<css> " + generated},以便動畫變換組合在該靜態佈局變換之上。 - 通過靜態基礎偏移動畫變換(避免雙重旋轉)。
get_motion_context給出節點的絕對變換,它已經包含了那些 div 應用的任何靜態基礎。一個rotate片段為[45, 125, 125],疊加在rotate-45基礎上,意味著包裹器動畫化的是偏移量[0, 80, 80](= 絕對值 − 45),而不是絕對值——否則 45° 會被應用兩次,元素在靜止時會處於 90° 位置。沒有靜態基礎的軌道(例如從 0 開始的x/y)則保持不變。請參閱交錯變換範例。 - 保持佈局變換與 Motion 變換分開。 對於每個動畫化
rotate、scale或skew的motion.*元素,請驗證它不依賴於諸如-translate-x-1/2或-translate-y-1/2之類的 Tailwind 佈局變換來進行居中/定位。這些工具類共享 Motion.dev 內聯寫入的 CSStransform屬性,因此 Motion 的變換可能會抹除佈局平移。如果兩者都需要,將元素拆分為一個承載居中/定位變換的靜態佈局包裹器和一個承載動畫旋轉/縮放/透明度的內部motion.*元素,或者將佈局偏移編碼到 Motion 本身(x: "-50%")並為每個關鍵影格保持其存在。
步驟 4:在程式碼中應用動畫
- 片段中存在 motion.dev? 對於 React 目標,逐字使用 motion.dev 程式碼。從
motion/react導入——除非程式碼庫已經使用了另一個動畫庫(Framer Motion、React Spring、GSAP),在這種情況下,請將片段適配到該庫。在適配到其他技術堆疊或選擇庫時,請載入 references/framework-recommendations.md。 - 存在 CSS 關鍵影格? 用於 vanilla/非 React 目標,或者當程式碼庫沒有 React 動畫庫時使用。
- 沒有片段? 使用
keyframeBindings或motionSummary作為備用數據,以構建等效的 motion.dev 調用或 CSS 關鍵影格。通常情況下片段是存在的;僅當兩個片段格式都確實缺失時才這樣做。
步驟 5:驗證
- 在添加新的動畫導入/約定之前,請閱讀組件現有的動畫導入/約定。如果使用者已經在使用 Framer Motion / React Spring / anime.js,請適配而不是強迫使用 motion.dev。
- 在一次遍歷更改許多節點之前,先抽查一個動畫能夠端到端運行(重新加載、觀察、迭代)。
- 載入 references/gotchas.md
[截斷...更多內容]
框架建議
根據您的專案技術堆疊,選擇合適的動畫庫:
- React / Next.js:motion.dev 或 Framer Motion(如果已存在於專案中)。
- Vue:使用 Vue 的過渡系統或
@vueuse/motion。 - Svelte:內置的
transition:指令。 - CSS 動畫:對應成 CSS
@keyframes,適用於任何靜態網站或非 JS 框架。
載入 references/framework-recommendations.md 以取得詳細的適配指南。