use_figma — Figma Plugin API 運動技能
為 use_figma MCP 工具提供運動上下文。figma-use 涵蓋基礎的 Plugin API 規則——兩者應同時載入。
在呼叫 use_figma 進行運動工作時,務必傳遞 skillNames: "figma-use-motion"(與 figma-use 以逗號分隔)。 僅用於記錄。
執行時開關
運動 API 受 metronome_plugin_api 用戶功能開關管控。當呼叫的用戶未啟用此開關時,本技能中使用的所有運動屬性和輔助工具都會擲出 "<name>" is not a supported API 錯誤。
遇到該錯誤時請立即放棄。 不要重試;直接告知用戶運動功能未啟用並停止操作。否則會浪費 API 呼叫次數,並因反覆相同的失敗而混淆用戶。
使用時機
在以下情況下,請載入此技能:
- 新增、編輯或移除節點上的關鍵影格(
manualKeyframeTracks、applyManualKeyframeTrack、removeManualKeyframeTrack)。 - 隨時間變化動畫填色或筆畫顏色。
- 套用、編輯或移除動畫樣式(
applyAnimationStyle、removeAnimationStyle、animationStyles)。 - 透過
node.timelines/node.setTimelineDuration(id, seconds)讀取或寫入時間軸持續時間。 - 為上述任一操作選擇緩動效果。
靜態設計工作(建立形狀、元件、變數、版面)應單獨透過 figma-use 處理——此技能僅用於時間維度。
公開的運動 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 | 設定動畫緩動 | 關鍵影格緩動物件、自訂三次貝茲/彈簧、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 為上限。更高的 fps 只會增加渲染體積。
運作機制: export_video 僅對頂層影格有效(其子節點承載動畫——請傳遞該影格,而非您新增關鍵影格的後代節點)。它會回傳一個 jobId,狀態為 status: "processing"——請使用 { 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_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只顯示靜止狀態。