use_figma. Figma 插件 API 技能
使用 use_figma 工具通过插件 API 在 Figma 文件中执行 JavaScript。所有详细参考文档都放在 references/ 中。
调用 use_figma 时必须始终传递 skillNames: "figma-use"。 这是一个用于跟踪技能使用情况的日志参数,不会影响执行。
如果 Figma MCP 工具显示为延迟工具,请使用 select: 语法在单个 ToolSearch 调用中批量加载所有 schema,例如:ToolSearch query="select:use_figma,get_screenshot,get_metadata,create_new_file"。一次往返优于六次。
如果任务涉及从代码在 Figma 中构建或更新完整的页面、屏幕或多节布局,还应加载 figma-generate-design。它提供了通过 search_design_system 发现设计系统组件、导入它们并逐步组装屏幕的工作流程。两个技能协同工作:一个负责 API 规则,另一个负责屏幕构建工作流程。
如果任务涉及在 Figma 中创建或构建组件(即使是单个组件),还应加载 figma-generate-library。它提供了组件创建工作流程、变量基础、变体集、设计 Token 绑定。这是 figma-use 本身不涵盖的内容。
在开始之前,加载 plugin-api-standalone.index.md 以了解可能实现的功能。当要求编写插件 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()会抛出 "not implemented" 错误:永远不要使用它。 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。 跳过加载会抛出Cannot write to node with unloaded font "<family> <style>"。此规则涵盖的不仅仅是characters:它适用于任何对具有未加载字体的节点的操作(appendChild,insertChild,setBoundVariable,setExplicitVariableModeForCollection,setValueForMode, 影响文本的findAll回调)。在修改现有文本时,通过getStyledTextSegments(['fontName'])加载节点当前的字体,而不是硬编码的默认字体。在大多数环境中 Inter 已预加载,因此其他字体系列更常引发此错误。每种字体的配方都相同。如果样式字符串未经核实,请先使用await figma.listAvailableFontsAsync()。参见标准文本编辑配方。 - 页面是增量加载的:使用
await figma.setCurrentPageAsync(page)切换页面并加载其内容。同步设置器figma.currentPage = page不起作用并且会抛出错误(参见下面的页面规则)。 setBoundVariableForPaint会返回一个新的 paint,必须捕获并重新赋值。createVariable接受集合对象或 ID 字符串(对象优先)。layoutSizingHorizontal/Vertical的值受到结构上下文的限制,FIXED始终有效,HUG和FILL则不然。'HUG'仅在自动布局框架本身或者作为自动布局框架的TEXT子元素上有效。'FILL'仅对自动布局框架的子元素有效,该子元素还不能是绝对定位的、不能位于不可变框架内部、也不能是画布网格的子元素。实际后果是:首先附加到自动布局父级,然后再设置HUG/FILL:一个新创建或未设置父级的节点尚不能满足该规则。该属性存在于每个SceneNode上;错误是值被拒绝,而不是“没有这样的属性”。参见陷阱。 12a. 对存放相关子元素的容器使用自动布局。 当子元素具有结构关系(堆叠、并排、对齐、有间距、自动换行)时,将它们包装在figma.createAutoLayout()中,而不是使用绝对坐标x/y的figma.createFrame()。绝对坐标控制容器在画布上的位置;自动布局控制其子元素在容器内的关系。跳过容器会留下面临文本重排、内容更改或重叠的风险。- 将新的顶层节点放置在远离 (0,0) 的位置。 直接附加到页面的节点默认位于 (0,0)。扫描
figma.currentPage.children以找到空位(例如,在最右侧节点的右侧)。这仅适用于页面级别的节点;嵌套在其他框架或自动布局容器内的节点由其父级定位。参见陷阱。 - 当
use_figma出错时,请 STOP。不要立即重试。 失败的脚本是原子性的:如果脚本出错,则根本不会执行,也不会对文件进行任何更改。仔细阅读错误消息,修复脚本,然后重试。参见错误恢复。 - 必须
return所有创建/修改的节点 ID。 每当脚本在画布上创建新节点或修改现有节点时,收集所有受影响的节点 ID 并以结构化对象的形式返回(例如return { createdNodeIds: [...], mutatedNodeIds: [...] })。这对于后续调用引用、验证或清理这些节点至关重要。 - 创建变量时务必显式设置
variable.scopes。 默认的ALL_SCOPES会污染每个属性选择器,几乎从不符合预期。对背景使用特定的作用域,如["FRAME_FILL", "SHAPE_FILL"],文本颜色使用["TEXT_FILL"],间距使用["GAP"]等。有关完整列表,请参见 variable-patterns.md。 await每个 Promise。 永远不要让 Promise 不被 await。未等待的异步调用(例如没有await的figma.loadFontAsync(...),或者没有await的figma.setCurrentPageAsync(page))会触发即忘,导致静默失败或竞态条件。脚本可能在异步操作完成之前返回,导致数据丢失或更改仅应用一半。
关于每条规则的详细错误/正确示例,请参见陷阱与常见错误。
2. 页面规则(关键)
页面上下文在 use_figma 调用之间重置:每次 figma.currentPage 都从第一页开始。
切换页面
使用 await figma.setCurrentPageAsync(page) 切换页面并加载其内容。同步设置器 figma.currentPage = page 不起作用:它会在 use_figma 中抛出 "Setting figma.currentPage is not supported"。始终使用异步方法。
// 切换到特定页面(加载其内容)
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 判断编辑器: 设计 = 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, RECTANG
[已截断]