用途:figma-use 是调用 use_figma 工具前必须加载的前置技能,用于在 Figma 文件中通过 Plugin API 执行 JavaScript。调用 use_figma 时需传入 skillNames: "figma-use"(仅用于记录技能使用情况,不影响执行)。如任务涉及从代码构建或更新整页、屏幕或多区块布局,还需同时加载 figma-generate-design。
主要能力与规则:代码用顶层 await 编写,返回值为输出通道(自动 JSON 序列化),不要用 figma.closePlugin() 或 async IIFE。console.log() 不返回结果。figma.notify() 会报未实现,勿用;getPluginData()/setPluginData() 不支持,改用 getSharedPluginData()/setSharedPluginData()。颜色范围为 0–1(非 0–255)。填充/描边为只读数组,需克隆后重新赋值。文本操作前必须 await figma.loadFontAsync({family, style})。切换页面须用 await figma.setCurrentPageAsync(page),同步写法会抛错。layoutSizingHorizontal/Vertical = 'FILL' 必须在 appendChild 之后设置。创建变量时显式设置 variable.scopes。所有 Promise 都要 await。新建顶层节点应避开 (0,0),并返回全部创建/修改的节点 ID。
使用方式:先加载 plugin-api-standalone.index.md 了解 API 全貌,写代码时用 plugin-api-standalone.d.ts grep 相关类型。涉及设计系统时从 working-with-design-systems/wwds.md 入手。建议增量作业:每次调用只做一件事,逐步用 get_metadata 和 get_screenshot 验证。use_figma 具有原子性,脚本报错则不执行、不改动文件。
适用场景与限制:仅适用于设计模式(editorType "figma");FigJam("figjam")多数设计节点不可用。设计模式中可用的节点包括 Rectangle、Frame、Component、Text、Ellipse、Star、Line、Vector、Polygon、BooleanOperation、Slice、Page、Section、TextPath;被禁用的包括 Sticky、Connector、ShapeWithText、CodeBlock、Slide、SlideRow、Webpage。更多参考文档:gotchas.md、common-patterns.md、plugin-api-patterns.md、api-reference.md、validation-and-recovery.md、component-patterns.md、variable-patterns.md、text-style-patterns.md、effect-style-patterns.md。官方文档与具体收费信息暂未提供。