use_figma — 用於 Motion 的 Figma Plugin API 技能
為 use_figma MCP 工具提供的 Motion(動態)上下文。figma-use 涵蓋了基礎的 Plugin API 規則 — 請將兩者一起載入。
當為動態工作呼叫 use_figma 時,始終傳遞 skillNames: "figma-use-motion"(與 figma-use 一起以逗號分隔)。 僅記錄。
執行時期門控
Motion API 受到 metronome 使用者功能旗標的門控。當呼叫的使用者沒有此旗標時,此技能中引用的每個 motion 屬性和輔助方法都會拋出 "<name>" is not a supported API 錯誤。
遇到該錯誤時請快速中止。 不要重試;告知使用者 motion 未為其啟用並停止。否則會浪費呼叫次數,並因重複的相同失敗而讓使用者感到困惑。
何時使用此技能
每當 use_figma 任務涉及以下內容時,請載入此技能:
- 在節點上新增、編輯或移除關鍵影格(
manualKeyframeTracks、applyManualKeyframeTrack、removeManualKeyframeTrack)。 - 隨著時間動畫化填色或筆畫顏色。
- 應用、編輯或移除動畫樣式(
applyAnimationStyle、removeAnimationStyle、animationStyles)。 - 透過
node.timelines/node.setTimelineDuration(id, seconds)讀取或寫入時間軸時長。 - 為上述任何操作選擇緩動效果。
靜態設計工作(建立形狀、元件、變數、佈局)只需透過 figma-use 進行 — 此技能僅用於時間維度。
開放的 Motion API 介面
node.manualKeyframeTracks— 讀取/寫入手動關鍵影格(包括填色、筆畫和效果軌道)。node.applyManualKeyframeTrack(field, track)/node.removeManualKeyframeTrack(field)— 新增、取代或移除一個手動關鍵影格軌道,無需重寫整個物件。node.animationStyles— 讀取/寫入應用於節點的動畫樣式中繼資料。node.applyAnimationStyle(styleId, presetData?)/node.removeAnimationStyle(id)— 應用一個發現的樣式,並透過其回傳/回讀的id移除一個已應用的樣式實例。node.timelines— 包含頂層影格的唯讀時間軸列表,時長以秒為單位。node.setTimelineDuration(id, durationSeconds)— 寫入包含頂層影格的時間軸時長。node.animations— 唯讀的已解析關鍵影格資料(目前僅限手動軌道 — 請參閱 motion-patterns.md)。figma.motion.figmaAnimationStyles()— Figma 第一方動畫樣式的唯讀列表。
編寫自訂的 "figma:motion" 預設模組原始碼超出範圍。如果使用者想要一個全新的動畫樣式,請如此告知並停止;不要憑空捏造一個。
參考文件
根據任務需求載入以下文件:
| 文件 | 何時載入 | 涵蓋內容 |
|---|---|---|
| motion-patterns.md | 新增/編輯動畫 | 手動關鍵影格、動畫化填色/筆畫、應用動畫樣式、時間軸時長 |
| motion-easing.md | 設定動畫緩動 | 關鍵影格緩動物件、自訂 cubic/spring、HOLD、在動畫樣式內應用緩動 |
驗證動畫
get_screenshot 僅顯示時間軸的靜止狀態,絕不顯示動態。要檢查動態,請使用 export_video 並取樣影格 — 但它會在伺服器端渲染且速度慢且昂貴(約 10 秒到數分鐘),因此請確保每次渲染都有用。
在渲染前做好規劃 — 成本與像素 × 影格成正比,因此兩者都不要超過所需範圍:
- 先選定時刻。 每個階段(例如每個錯開步驟,或開始/中間/穩定階段)只需要一個影格,而不是流暢的播放 — 通常 4–6 個。此數量會設定您的 fps。
- 大小以能看清楚為準。 從較小的設定開始 —
constraint: { type: 'WIDTH', value: 320 }、quality: "low"— 但文字和小元素在此設定下會模糊,因此在需要判斷精細細節時提高WIDTH(768+)。省略constraint= 全尺寸(1x;伺服器會限制為 10x / 4096px)。 - 將 fps 設定得剛好足以捕捉這些影格:
fps: 5可涵蓋少量影格;10 是上限。更高只會使渲染變得更龐大。
機制: export_video 僅適用於其子節點包含動畫的頂層影格(請傳遞該影格,而非您設定關鍵影格的子節點)。它會回傳一個帶有 status: "processing" 的 jobId — 使用 { fileKey, jobId } 重新呼叫以進行輪詢。然後使用 ffmpeg -ss <t> -i anim.mp4 -frames:v 1 frame_<t>.png 在本機提取影格 — 提取是免費的,因此一旦您為渲染付費,就請充分挖掘每個能提供資訊的影格,而不是重新導出。如果沒有像 ffmpeg 這樣的影格提取器,請跳過導出並直接推理關鍵影格。
反覆迭代直到正確為止。 導出是一種診斷方法,而非最終確認:如果影格錯誤(順序不對、時機不對、缺少元素、遮罩遮蔽了合成畫面),請修正關鍵影格/樣式並重新導出。讀取所有影格,並將所有修正批次處理到一次傳遞中,然後再重新渲染 — 每次渲染都伴隨著實際開銷,因此請確保每次渲染都有意義,而不是在每次微小變更後都重新導出。
對於微不足道或顯而易見的變更,請完全跳過導出。
預飛檢查清單
除了 figma-use 預飛檢查清單 之外,還請驗證:
- 緩動使用公開的
{ type: 'EASE_OUT', easingFunctionCubicBezier?: …, easingFunctionSpring?: … }形狀 — 而非像OUT_CUBIC這樣的內部場景圖名稱。 - Ease-in-out 使用精確的公開列舉
EASE_IN_AND_OUT(或EASE_IN_AND_OUT_BACK);切勿使用無效的別名EASE_IN_OUT。 - 正在動畫化的節點不是頂層影格(頁面的直接子節點)。請改為對其子節點進行動畫化。
- 時間軸值在公開 Plugin API 中以秒為單位。使用
setTimelineDuration來延長;除非使用者要求,否則切勿縮短。 - 變換關鍵影格欄位使用公開名稱(
TRANSLATION_X、TRANSLATION_Y、ROTATION、SCALE_X、SCALE_Y、SCALE_XY),而非內部MOTION_*場景圖名稱。 - 手動關鍵影格欄位來自 motion-patterns.md 中的公開允許清單;生成的/內部的場景圖欄位故意會拋出錯誤。
- 被修改的節點 ID 已回傳(根據
figma-use規則 15)。 - 當運動正確性並非顯而易見,且影格提取器(
ffmpeg)可用時,請透過export_video+ 影格取樣進行驗證 — 以小尺寸、低fps渲染,反覆迭代直到正確(請參閱上面的驗證動畫章節)。get_screenshot僅顯示靜止狀態。