use_figma. Figma Plugin API 技能
使用 use_figma 工具透過 Plugin API 在 Figma 檔案中執行 JavaScript。所有詳細的參考文件都位於 references/ 中。
在呼叫 use_figma 時,務必傳遞 skillNames: "figma-use"。 這是一個用於追蹤技能使用情況的日誌參數,不會影響執行。
如果 Figma MCP 工具顯示為延遲工具,請在單次 ToolSearch 呼叫中批次載入所有工具的架構,使用 select: 語法,例如 ToolSearch query="select:use_figma,get_screenshot,get_metadata,create_new_file"。一次往返比六次好。
如果任務涉及從程式碼在 Figma 中建立或更新完整頁面、畫面或多區塊版面,也請載入 figma-generate-design。它提供了透過 search_design_system 發現設計系統元件、將其匯入並逐步組合畫面的工作流程。兩個技能協同運作:這個技能負責 API 規則,另一個負責畫面建構工作流程。
如果任務涉及在 Figma 中建立或建構元件(即使是單一元件),也請載入 figma-generate-library。它提供了元件建立工作流程、變數基礎、變體組合、設計權杖綁定。這些是 figma-use 單獨無法涵蓋的。
在此之前,請先載入 plugin-api-standalone.index.md 以了解可能的範圍。當您被要求撰寫 Plugin API 程式碼時,請使用此上下文來 grep plugin-api-standalone.d.ts 以取得相關的型別、方法和屬性。這是 API 表面的最終事實來源。這是一個大型的型別定義檔案,因此不要一次全部載入,請根據需要 grep 相關區段。
重要事項:每當您處理設計系統時,請先從 working-with-design-systems/wwds.md 開始,以了解在 Figma 中使用設計系統的關鍵概念、流程和指南。然後再根據需要載入元件、變數、文字樣式和效果樣式的更具體參考資料。
1. 關鍵規則
- 使用
return將資料傳回。 回傳值會自動以 JSON 序列化(物件、陣列、字串、數字)。請勿呼叫figma.closePlugin()或將程式碼包裝在非同步 IIFE 中。這已經為您處理好了。 - 編寫帶有頂層
await和return的純 JavaScript。 程式碼會自動包裝在非同步上下文中。請勿包裝在(async () => { ... })()中。 figma.notify()會擲出「未實作」錯誤:絕對不要使用。 3a.getPluginData()/setPluginData()在use_figma中不受支援:請勿使用。請改用getSharedPluginData()/setSharedPluginData()(這些是受支援的),或者透過傳回節點 ID 並將其傳遞給後續呼叫來追蹤節點 ID。console.log()不會被傳回。請使用return輸出。- 以小步驟增量工作。 將大型操作分解為多個
use_figma呼叫。在每個步驟後進行驗證。這是避免錯誤最重要的實務做法。 - 顏色的範圍是 0-1(而非 0-255):
{r: 1, g: 0, b: 0}代表紅色。 - 填充/描邊是唯讀陣列:請複製、修改、重新指派。
- 每個文字編輯都遵循標準做法:載入字型 →
await→ 變異 → 傳回受影響的節點 ID。 跳過載入會擲出「無法寫入含有未載入字型「 」的節點」錯誤。此規則涵蓋的不僅是characters:它適用於任何對含有未載入字型之節點的操作(appendChild、insertChild、setBoundVariable、setExplicitVariableModeForCollection、setValueForMode、觸及文字的findAll回呼)。在變異現有文字時,請透過getStyledTextSegments(['fontName'])載入節點的目前字型,而非硬編碼的預設值。Inter 在大多數環境中已預先載入,因此其他字型系列更常引發此錯誤。每種字型的做法都相同。如果樣式字串未經驗證,請先使用await figma.listAvailableFontsAsync()。請參閱標準文字編輯做法。 - 頁面增量載入:使用
await figma.setCurrentPageAsync(page)來切換頁面並載入其內容。同步設定器figma.currentPage = page無效且會擲出錯誤(請參閱下方的頁面規則)。 setBoundVariableForPaint會回傳一個新的 paint,必須捕獲並重新指派。createVariable接受 collection 物件或 ID 字串(物件為佳)。layoutSizingHorizontal/Vertical的值受限於結構上下文,FIXED始終有效,HUG和FILL則否。'HUG'僅在自動佈局框架本身上,或是其TEXT 子層上有效。'FILL'僅在自動佈局框架的子層上有效,且不能是絕對定位、不能在不可變框架內、也不能是 canvas-grid 的子層。實務上的結論是:先附加到自動佈局父層,然後再設定HUG/FILL:新建立或未設定父層的節點尚無法滿足規則。該屬性本身存在於每個SceneNode上;錯誤是值被拒絕,而非「無此屬性」。請參閱常見陷阱。 12a. 對容納相關子層的容器使用自動佈局。 當子層具有結構關係時(堆疊、並排、對齊、間距、貼合),請將其包裝在figma.createAutoLayout()中,而非使用帶有絕對x/y的figma.createFrame()。絕對座標控制容器在畫布上的位置;自動佈局控制其子層在容器內的關係。跳過容器會使文字重新排版、內容變更或重疊時失去保護。- 將新的頂層節點放置在遠離 (0,0) 的位置。 直接附加到頁面的節點預設位於 (0,0)。掃描
figma.currentPage.children以找到一個清晰的位置(例如,在最右側節點的右側)。這僅適用於頁面層級的節點,巢狀在其他框架或自動佈局容器內的節點由其父層定位。請參閱常見陷阱。 - 發生
use_figma錯誤時,請立即停止。請勿立即重試。 失敗的腳本是原子性的:如果腳本發生錯誤,它根本不會被執行,也不會對檔案進行任何更改。仔細閱讀錯誤訊息,修正腳本,然後重試。請參閱錯誤復原。 - 必須
return所有已建立/變異的節點 ID。 每當腳本建立新節點或變異畫布上的現有節點時,請收集所有受影響的節點 ID,並以結構化物件傳回(例如return { createdNodeIds: [...], mutatedNodeIds: [...] })。這對於後續呼叫參考、驗證或清理這些節點至關重要。 - 建立變數時,務必明確設定
variable.scopes。 預設值ALL_SCOPES會污染每個屬性選取器,幾乎從不是你想要的。使用特定範圍,例如背景用["FRAME_FILL", "SHAPE_FILL"]、文字顏色用["TEXT_FILL"]、間距用["GAP"]等。請參閱 variable-patterns.md 以取得完整列表。 await每一個 Promise。 絕不要遺留未 await 的 Promise,未 await 的非同步呼叫(例如沒有await的figma.loadFontAsync(...),或沒有await的figma.setCurrentPageAsync(page))會觸發後即忘記,導致靜默失敗或競爭條件。腳本可能非同步操作完成前就回傳,導致資料遺失或變更只套用一半。
關於每個規則的詳細錯誤/正確範例,請參閱常見陷阱與常見錯誤。
2. 頁面規則(關鍵)
頁面上下文在 use_figma 呼叫之間會重設:每次 figma.currentPage 都從第一個頁面開始。
切換頁面
使用 await figma.setCurrentPageAsync(page) 來切換頁面並載入其內容。同步設定器 figma.currentPage = page 無效:它會在 use_figma 中擲出「不支援設定 figma.currentPage」錯誤。請始終使用非同步方法。
// 切換到特定頁面(載入其內容)
const targetPage = figma.root.children.find((p) => p.name === "My Page");
await figma.setCurrentPageAsync(targetPage);
// targetPage.children 現在已填入資料
在單次 use_figma 呼叫中最多呼叫 setCurrentPageAsync 一次,將多頁面工作分散至平行呼叫
一個腳本最多只能切換頁面一次。 絕對不要在迴圈中遍歷 figma.root.children 並在迴圈內部切換頁面。
如果工作跨越多個頁面,請將其拆分為 N 個 use_figma 呼叫(每個目標頁面一個),並平行發出:在單一助理訊息中包含 N 個 use_figma 工具使用區塊。執行環境會並行執行它們;每個腳本精確設定 currentPage 一次。
明確指示: 進行分散操作時,您必須在一個訊息中發出 N 個工具呼叫。請勿跨越多個回合發送。請勿在發出下一個之前等待前一個完成。順序的逐頁呼叫比此規則取代的迴圈模式更慢,並且浪費了拆分所帶來的全部好處。
// 避免,在一個腳本中切換頁面 N 次,每次重新載入檔案
for (const page of figma.root.children) {
await figma.setCurrentPageAsync(page);
// ... 處理此頁面 ...
}
// 偏好,唯讀發現呼叫以取得頁面 ID,然後在下一個訊息中
// 發出 N 個平行的 use_figma 工具呼叫(每個頁面一個),每個設定 currentPage 一次。
對於任何多頁面工作,無論讀取或寫入,預設使用平行分散。請參閱 gotchas.md → 在每次 use_figma 呼叫中設定一次目前頁面 以了解完整理由。
跨腳本執行
figma.currentPage 會在每次 use_figma 呼叫開始時重設為第一個頁面。如果您的工作流程跨越多個呼叫且目標是非預設頁面,請在每次呼叫開始時呼叫 await figma.setCurrentPageAsync(page)。
您可以多次呼叫 use_figma 以增量方式建構檔案狀態,或在編寫另一個腳本之前擷取資訊。例如,編寫一個腳本以取得現有節點的元資料,return 該資料,然後在後續腳本中使用它來修改這些節點。
3. return 是您的輸出通道
代理程式僅能看見您 return 的值。其他所有內容都不可見。
- 傳回 ID(關鍵):每個建立或變異畫布節點的腳本必須傳回所有受影響的節點 ID,例如
return { createdNodeIds: [...], mutatedNodeIds: [...] }。這是硬性要求,非選項。 - 進度回報:
return { createdNodeIds: [...], count: 5, errors: [] }。 - 錯誤資訊:擲出的錯誤會自動被捕獲並傳回,只需讓它們傳播或明確地
throw。 console.log()輸出永遠不會被傳回給代理程式。- 始終傳回可操作的資料(ID、計數、狀態),以便後續呼叫可以參考已建立的物件。
4. 編輯器模式
use_figma 在設計模式(editorType "figma",預設值)下運作。FigJam("figjam")和 Slides("slides")具有不同的可用節點類型集合。大多數設計節點在 FigJam 中被封鎖,而僅 FigJam 的節點在 Slides 中被封鎖。
從 URL 判斷編輯器: Design = figma.com/design/...、FigJam = figma.com/board/...、Slides = figma.com/slides/...。在假設 API 可用之前請先確認。
在設計模式中可用:Rectangle、Frame、Component、Text、Ellipse、Star、Line、Vector、Polygon、BooleanOperation、Slice、Page、Section、TextPath。
在設計模式中被封鎖:Sticky、Connector、ShapeWithText、CodeBlock、Slide、SlideRow、SlideGrid、InteractiveSlideElement、Webpage。
在 Slides 模式中可用:Rectangle、Frame、Component、Text、Ellipse、Star、Line、Vector、Polygon、BooleanOperation、Slice、Section、TextPath、Slide、SlideRow、SlideGrid、InteractiveSlideElement。
在 Slides 模式中被封鎖:Sticky、Connector、ShapeWithText、CodeBlock、Webpage、Page。
僅限設計的 API(不僅是節點類型): figma.createPage() 僅在設計檔案(figma.com/design/...)中可用。在 FigJam(figma.com/board/...)和 Slides(figma.com/slides/...)中,它會擲出 TypeError: figma.createPage no such property 'createPage' on the figma global object。請勿在 FigJam 或 Slides 工作流程中發出 figma.createPage()。
Slides 注意事項: 目前尚無專用的 Slides 檔案讀取工具。請使用
use_figma搭配唯讀腳本進行檢查(請參閱第 6 節「先檢查」模式),並使用get_screenshot/await node.screenshot()獲取視覺上下文。有關 Slides 專用的 API 指南,請載入 figma-use-slides 技能。
5. 高效 API。偏好這些而非冗長替代方案
這些 API 可減少樣板程式碼、消除排序錯誤並壓縮 Token 輸出。始終優先使用它們,而非冗長的替代方案。
node.query(selector):類似 CSS 的節點搜尋
使用類似 CSS 的選擇器在子樹中尋找節點。取代冗長的 findAll + 過濾迴圈。
// 之前,冗長的遍歷
const texts = frame.findAll(n => n.type === 'TEXT' && n.name === 'Title')
// 之後,一行程式碼使用 query
const texts = frame.query('TEXT[name=Title]')
選擇器語法:
- 類型:
FRAME、TEXT、RECTANGLE、ELLIPSE、COMPONENT、INSTANCE、SECTION(不區分大小寫) - 屬性精確:
[name=Card]、[visible=true]、[opacity=0.5] - 屬性子字串:
[name*=art](包含)、[name^=Header](開頭為)、[name$=Nav](結尾為) - 點路徑遍歷:
[fills.0.type=SOLID]、[fills.*.type=SOLID](萬用字元索引) - 實例匹配:
[mainComponent=nodeId]、[mainComponent.name=Button] - 組合器:
FRAME > TEXT(直接子層)、FRAME TEXT(任何後代)、A + B(相鄰同層)、A ~ B(一般同層) - 偽類別:
:first-child、:last-child、:nth-child(2)、:not(TYPE)、:is(FRAME, RECTANGLE)、:where(TEXT, ELLIPSE) - 節點 ID:
#nodeId或純 GUID - 逗號:
TEXT, RECTANGLE(多個選擇器)
最佳實踐與注意事項請參閱 gotchas.md → query() selector rules。
偏好 node.findOneWithName(name) 而非 findAll(n => n.name === name)[0]
// 偏好
const card = frame.findOneWithName('Card');
// 避免
const card = frame.findAll(n => n.name === 'Card')[0];
注意事項:與 findAll 不同,findOneWithName 會尋找確切的子字串,所以如果有多個符合項目,它會傳回找到的第一個。
批次變數操作:importVariableByKeyAsync、bulkCreateVariables、bulkCreateVariableAliases
對於大量變數工作,這些是必用 API。常規的逐個變數建立會遺失模式順序並產生過多 Token。
// 一次呼叫支援最多 100 個變數
const [colorVar, spacingVar] = figma.variables.bulkCreateVariables([
{ name: 'brand/primary', collection: myCollection, scopes: ['FRAME_FILL'] },
{ name: 'spacing/md', collection: myCollection, scopes: ['GAP'] },
]);
// 批次建立別名
const [aliasVar] = figma.variables.bulkCreateVariableAliases([
{ variableId: colorVar.id, name: 'brand/primary-alt' },
]);
重要: bulkCreateVariables 會將變數新增至 collection 的末端。它不會重新排序它們,也不會在兩個變數之間插入。若要控制順序,請將它們個別建立。參閱 variable-patterns.md 以了解完整的工作流程。
持續存在的節點參考(進階)
如果您的腳本需要在後續的 use_figma 呼叫中跨不同腳本執行階段參考節點,請在變數層級儲存節點 ID 字串。然後在後續呼叫中,使用 figma.getNodeById(id) 來擷取它們。
// 在腳本 A 中建立節點
const rect = figma.createRectangle();
figma.currentPage.appendChild(rect);
const nodeId = rect.id; // 儲存此 ID
return { createdNodeIds: [nodeId] };
// 在腳本 B 中(在同個檔案中),參考同個節點
const rect = figma.getNodeById(nodeId);
if (rect) { /* 對其進行操作 */ }
跨腳本關於 ID 的警告: 使用 figma.getNodeById() 時,腳本可能會遇到其他腳本尚未完成的競爭條件。這在儲存和擷取 ID 在另一個腳本建立的節點時尤其常見。請參閱 gotchas.md → Node ID reference race condition,以了解如何透過 setTimeout 或 requestAnimationFrame(在 use_figma 腳本中受支援的兩種瀏覽器模式)來解決此問題。
模組化物件建立
function buildButton(label) {
const btn = figma.createComponent();
btn.layoutMode = 'HORIZONTAL';
btn.primaryAxisAlignItems = 'CENTER';
btn.counterAxisAlignItems = 'CENTER';
btn.fills = [{ type: 'SOLID', color: { r: 0, g: 0.2, b: 1 } }];
const txt = figma.createText();
txt.characters = label;
btn.appendChild(txt);
return btn;
}
const myBtn = buildButton('Click me');
figma.currentPage.appendChild(myBtn);
return { createdNodeIds: [myBtn.id] };
6. 錯誤復原與自我修正
發生 use_figma 錯誤時,受影響的腳本不會在檔案上產生任何效果(原子性)。但由於掛勾的存在,工具的輸出會包含錯誤資訊。
- 永遠不要立即重試。 錯誤腳本未對檔案進行任何變更;重試相同的文字只會引發相同的錯誤。
- 仔細閱讀錯誤訊息。 大部分錯誤會指向特定規則違規(例如,未載入字型、無效的屬性值、嘗試使用已封鎖的 API)。
- 修正腳本,然後重試。 只有變更腳本文字本身才會改變結果。例如:「讓我們修正未載入的字型錯誤」→ 修正腳本 → 重試呼叫。
7. 實作範例
從頭開始建立畫面(逐步)
// 步驟 1:建立主要框架
const frame = figma.createFrame();
frame.resize(375, 812);
frame.name = 'App Screen';
frame.fills = [{ type: 'SOLID', color: { r: 1, g: 1, b: 1 } }];
frame.layoutMode = 'VERTICAL';
frame.primaryAxisSizingMode = 'FIXED';
frame.counterAxisSizingMode = 'FIXED';
frame.itemSpacing = 16;
frame.paddingLeft = frame.paddingRight = frame.paddingTop = frame.paddingBottom = 16;
figma.currentPage.appendChild(frame);
// 將框架遠離 (0,0)
frame.x = 100;
frame.y = 100;
return { createdNodeIds: [frame.id] };
// 步驟 2:加入標題文字
const title = figma.createText();
title.characters = '我的應用程式';
title.fontSize = 24;
title.fontName = { family: 'Inter', style: 'Bold' };
// 僅在顯示載入錯誤時才需要 await 字型載入
await figma.loadFontAsync({ family: 'Inter', style: 'Bold' });
// 也載入現有字型
const segments = title.getStyledTextSegments(['fontName']);
for (const seg of segments) {
await figma.loadFontAsync(seg.fontName);
}
// 附加到自動佈局框架,設定 HUG 寬度
frame.appendChild(title);
title.layoutSizingHorizontal = 'HUG';
return { createdNodeIds: [frame.id, title.id] };
變異現有節點
// 從前一個呼叫取得要變異的節點 ID
const targetNode = figma.getNodeById('123:456');
if (targetNode && targetNode.type === 'TEXT') {
// 載入其目前字型
const segments = targetNode.getStyledTextSegments(['fontName']);
for (const seg of segments) {
await figma.loadFontAsync(seg.fontName);
}
targetNode.characters = '更新的文字';
return { mutatedNodeIds: [targetNode.id] };
} else {
throw new Error('找不到目標節點或節點類型錯誤');
}
工具使用
use_figma
在 Figma 檔案中執行 JavaScript 程式碼。支援 figma.* 和 console.* API。
參數:
fileKey(必要):目標檔案的 Figma 檔案金鑰jsCode(必要):要執行的 JavaScript 程式碼- 使用
return將資料傳回 - 頂層
await受支援 - 程式碼會自動包裝在非同步函數中
- 使用
skillNames(必要,僅限"figma-use"):技能名稱日誌參數callDepth(選用):進階偵錯參數(預設0)pause(選用):在腳本執行後暫停(毫秒),以確保在下一個動作前狀態一致(預設1000)
範例:
{
"fileKey": "abc123",
"jsCode": "return figma.currentPage.children.map(n => ({ id: n.id, name: n.name, type: n.type }));",
"skillNames": "figma-use"
}