figma-use 实战Figma Effect Style API 的创建、应用与检查完整指南【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本文是 figma-use skill 参考文档之一聚焦 Figma Plugin API 中效果样式Effect Style的完整操作模式如何列出本地效果样式、如何以Elevation/200 这类命名创建投影样式、以及如何通过effectStyleId将样式批量应用到节点。你将掌握三类可直接运行的脚本模式并理解EffectStyle的底层模型、只读effects数组、变量绑定与常见陷阱可直接用于设计系统 Token 工作流。效果样式在 Figma 中的定位在继续阅读 API 模式之前先明确概念Figma 中的效果样式Effect Style是一个或多个视觉效果投影、内阴影、模糊的具名、可复用定义是设计系统中阴影/抬升elevationToken最接近的原生等价物。详见 wwds-effect-styles 参考。效果样式与变量Variable是两套不同机制效果样式是一个独立的样式对象EffectStyle通过 ID 应用到节点效果本身没有单一变量类型来表示阴影但效果内部的数值与颜色属性如radius、offsetX、color可以分别绑定变量从而让阴影值参与 Token 体系详见下文变量绑定一节。EffectStyle 数据模型从 typings 文件可以精确看到EffectStyle的接口定义plugin-api-standalone.d.ts属性类型说明typeEFFECT样式类型的字符串字面量读取其他属性前应先检查namestring样式名称用/分隔可实现分组例如Elevation/200effectsReadonlyArrayEffect只读数组必须克隆、修改后整体重新赋值descriptionstring继承自BaseStyleMixin可选描述boundVariables{ [field]: VariableAlias[] }只读该样式上各字段绑定的变量Effect 判别联合Effect是一个判别联合类型d.ts L4250-L4256包含DropShadowEffect | InnerShadowEffect | BlurEffect | NoiseEffect | TextureEffect | GlassEffect。其中最常见的几种type关键属性DROP_SHADOWcolor: RGBA、offset: Vector、radius、spread、visible、blendModeINNER_SHADOW与DROP_SHADOW相同LAYER_BLURradius、visibleBACKGROUND_BLURradius、visible所有颜色一律使用 0–1 范围的 RGBA如{r: 0, g: 0, b: 0, a: 0.15}不是十六进制也不是 0–255。一、列出本地效果样式列出当前文件中的全部本地效果样式返回每个样式的id、name、key和效果数量/** * Lists all local effect styles. * * returns {PromiseArray{id: string, name: string, key: string, effectCount: number}} */ async function listEffectStyles() { const styles await figma.getLocalEffectStylesAsync(); return styles.map(s ({ id: s.id, name: s.name, key: s.key, effectCount: s.effects.length })); }完整可运行脚本独立插件环境(async () { try { const results await listEffectStyles(); figma.closePlugin(JSON.stringify(results)); } catch(e) { figma.closePluginWithFailure(e.toString()); } })()注意两点必须使用getLocalEffectStylesAsync()。同步版本getLocalEffectStyles()已标记为deprecatedd.ts L1484-L1489在插件 manifest 含documentAccess: dynamic-page时会直接抛异常在 use_figma 环境中输出应改为return results不要调用figma.closePlugin()也不要把代码包进 async IIFE——运行时已自动处理见 SKILL.md 关键规则。在 use_figma 环境中的等价写法const styles await figma.getLocalEffectStylesAsync(); return styles.map(s ({ id: s.id, name: s.name, key: s.key, effectCount: s.effects.length }));二、创建投影效果样式创建投影样式时两个关键约束也是出错率最高的点颜色是 RGBA 0–1 范围0.15即 15% 透明度对应约 38/255effects是只读数组——创建时直接整体赋值一个新数组永远不要原地 push/mutate。/** * Creates a drop shadow effect style. * * param {string} name - e.g. Elevation/200 * param {{ r: number, g: number, b: number, a: number }} color - RGBA, 0-1 range * param {{ x: number, y: number }} offset * param {number} radius - blur radius * param {number} [spread0] * returns {EffectStyle} */ function createDropShadowStyle(name, color, offset, radius, spread) { const style figma.createEffectStyle(); style.name name; style.effects [{ type: DROP_SHADOW, color, offset, radius, spread: spread || 0, visible: true, blendMode: NORMAL }]; return style; }完整可运行脚本独立插件环境(async () { try { const style createDropShadowStyle( Elevation/200, { r: 0, g: 0, b: 0, a: 0.15 }, { x: 0, y: 4 }, 12, 0 ); figma.closePlugin(JSON.stringify({ id: style.id, name: style.name })); } catch(e) { figma.closePluginWithFailure(e.toString()); } })()参数取值参考参数含义常见设计系统取值color阴影颜色RGBA 0–1黑色{0,0,0,0.12}{0,0,0,0.3}用于不同层级offset偏移量像素层级越高y偏移越大如 1/2/4/8radius模糊半径像素随层级增大如 2/4/12/24spread扩散量像素默认 0多数投影用 0描边阴影才用正值createEffectStyle()是 Figma Design 专属 APId.ts L1448-L1453在 FigJam 中不可用。用name中的/分隔符即可在 Figma 样式面板中自动形成分组例如Elevation/100、Elevation/200、Elevation/300。多个效果与渲染顺序effects数组中元素顺序影响视觉效果投影按从底部到顶部的顺序渲染。若需要同时有投影 背景模糊可整体赋值多元素数组style.effects [ { type: DROP_SHADOW, color: { r: 0, g: 0, b: 0, a: 0.15 }, offset: { x: 0, y: 4 }, radius: 12, spread: 0, visible: true, blendMode: NORMAL }, { type: BACKGROUND_BLUR, radius: 8, visible: true } ];修改已有样式时同样遵守只读约束// ❌ 错误原地修改 // style.effects.push(newEffect); // ✅ 正确克隆数组后整体重新赋值 style.effects [...style.effects, newEffect];三、将效果样式应用到节点创建样式不会自动生效——必须把样式的id赋给节点的effectStyleId属性节点才会呈现该样式这也是新手最容易忽略的一点。以下函数按节点名子串匹配当前页所有节点将指定样式批量应用并返回成功应用的节点数/** * Applies an effect style to all nodes on the current page that match a given name pattern. * * param {string} styleId - The ID of an EffectStyle. * param {string} nodeNamePattern - Substring match against node names. * returns {number} - Number of nodes the style was applied to. */ function applyEffectStyleToMatchingNodes(styleId, nodeNamePattern) { const nodes figma.currentPage.findAll(n n.name.includes(nodeNamePattern)); let applied 0; for (const node of nodes) { if (effectStyleId in node) { node.effectStyleId styleId; applied; } } return applied; }完整可运行脚本独立插件环境(async () { try { const applied applyEffectStyleToMatchingNodes(STYLE_ID, Card); figma.closePlugin(JSON.stringify({ applied })); } catch(e) { figma.closePluginWithFailure(e.toString()); } })()要点拆解figma.currentPage.findAll()递归遍历当前页全部节点n.name.includes(nodeNamePattern)是子串匹配如传Card会命中Card、Card/Header、PrimaryCard等effectStyleId in node用于过滤——只有支持效果属性的节点类型如矩形、Frame、组件实例才有该属性避免对文本节点等无效类型赋值报错应用后节点的effects属性会自动反映样式中的值。dynamic-page 模式下的写入差异从 typings 可以看到当插件 manifest 使用documentAccess: dynamic-page时effectStyleId变为只读属性必须改用异步写入 APId.ts L6390-L6398await node.setEffectStyleIdAsync(styleId);建议统一用setEffectStyleIdAsync()它兼容两种 documentAccess 模式。四、效果样式中的变量绑定效果样式可以和变量体系协同工作效果中可绑定变量的字段为color、radius、spread、offsetX、offsetY即VariableBindableEffectFieldd.ts L5751。在节点上绑定变量的核心函数是setBoundVariableForEffectd.ts L2136-L2147// 绑定前先获取变量 const [radiusVar] await figma.variables.getLocalVariablesAsync(); // setBoundVariableForEffect 返回一个【新的】effect 对象——必须捕获并整体重新赋值 node.effects node.effects.map(effect { if (effect.type DROP_SHADOW) { return figma.setBoundVariableForEffect(effect, radius, radiusVar); } return effect; });两个关键事实也是常见出错点setBoundVariableForEffect返回新 effect 对象不修改原对象——必须捕获返回值并重新赋值effects数组传入null作为变量参数可解除该字段的绑定传入变量 ID 字符串不受支持必须传Variable对象。更多变量集合、作用域与绑定模式参见 variable-patterns 参考。五、其他相关 API排序moveLocalEffectStyleAfter(targetNode, reference)可在本地效果样式内部调整顺序传null表示移到首位仅 Figma Design 可用d.ts L1530-L1535样式检查每个EffectStyle都有稳定不变的key跨文件/跨库引用样式时应优先用key而非idid在不同文件副本间不保证稳定。六、常见陷阱速查陷阱正确做法effects是只读数组克隆后整体重新赋值style.effects [...style.effects, newEffect]使用已弃用的getLocalEffectStyles()一律用getLocalEffectStylesAsync()颜色写成 0–255 或十六进制用 0–1 范围 RGBA如{r: 0, g: 0, b: 0, a: 0.15}创建样式后以为会自动生效必须把style.id赋给节点的effectStyleId忘记效果数组顺序投影从底部向顶部渲染多效果时注意书写顺序绑定变量后忘记重新赋值setBoundVariableForEffect返回新 effect必须捕获忽略节点类型直接赋effectStyleId先effectStyleId in node过滤支持类型完整的错误示范与正确示范对照见 gotchas 参考效果样式在大型设计系统Token 命名、变量绑定、迁移中的完整方法论见 wwds-effect-styles。七、在 use_figma 工作流中落地以上脚本都基于原生 Plugin API。在 figma-use skill 的use_figmaMCP 环境中运行需遵循其运行时约束详见 SKILL.md用return输出结果不使用figma.closePlugin()不要包 async IIFE顶层await与return即可禁用figma.notify()与console.log()输出创建/修改节点的脚本必须return全部受影响节点 ID。例如完整的列出所有本地效果样式在 use_figma 中只需const styles await figma.getLocalEffectStylesAsync(); return styles.map(s ({ id: s.id, name: s.name, key: s.key, effectCount: s.effects.length }));推荐的分步工作流先用只读脚本return出样式 ID 列表再把 ID 作为字符串字面量传给下一步的创建/应用脚本最后用get_metadata校验effectStyleId与效果数量是否落地避免一次性大脚本带来的定位困难。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
figma-use 实战：Figma Effect Style API 的创建、应用与检查完整指南
figma-use 实战Figma Effect Style API 的创建、应用与检查完整指南【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本文是 figma-use skill 参考文档之一聚焦 Figma Plugin API 中效果样式Effect Style的完整操作模式如何列出本地效果样式、如何以Elevation/200 这类命名创建投影样式、以及如何通过effectStyleId将样式批量应用到节点。你将掌握三类可直接运行的脚本模式并理解EffectStyle的底层模型、只读effects数组、变量绑定与常见陷阱可直接用于设计系统 Token 工作流。效果样式在 Figma 中的定位在继续阅读 API 模式之前先明确概念Figma 中的效果样式Effect Style是一个或多个视觉效果投影、内阴影、模糊的具名、可复用定义是设计系统中阴影/抬升elevationToken最接近的原生等价物。详见 wwds-effect-styles 参考。效果样式与变量Variable是两套不同机制效果样式是一个独立的样式对象EffectStyle通过 ID 应用到节点效果本身没有单一变量类型来表示阴影但效果内部的数值与颜色属性如radius、offsetX、color可以分别绑定变量从而让阴影值参与 Token 体系详见下文变量绑定一节。EffectStyle 数据模型从 typings 文件可以精确看到EffectStyle的接口定义plugin-api-standalone.d.ts属性类型说明typeEFFECT样式类型的字符串字面量读取其他属性前应先检查namestring样式名称用/分隔可实现分组例如Elevation/200effectsReadonlyArrayEffect只读数组必须克隆、修改后整体重新赋值descriptionstring继承自BaseStyleMixin可选描述boundVariables{ [field]: VariableAlias[] }只读该样式上各字段绑定的变量Effect 判别联合Effect是一个判别联合类型d.ts L4250-L4256包含DropShadowEffect | InnerShadowEffect | BlurEffect | NoiseEffect | TextureEffect | GlassEffect。其中最常见的几种type关键属性DROP_SHADOWcolor: RGBA、offset: Vector、radius、spread、visible、blendModeINNER_SHADOW与DROP_SHADOW相同LAYER_BLURradius、visibleBACKGROUND_BLURradius、visible所有颜色一律使用 0–1 范围的 RGBA如{r: 0, g: 0, b: 0, a: 0.15}不是十六进制也不是 0–255。一、列出本地效果样式列出当前文件中的全部本地效果样式返回每个样式的id、name、key和效果数量/** * Lists all local effect styles. * * returns {PromiseArray{id: string, name: string, key: string, effectCount: number}} */ async function listEffectStyles() { const styles await figma.getLocalEffectStylesAsync(); return styles.map(s ({ id: s.id, name: s.name, key: s.key, effectCount: s.effects.length })); }完整可运行脚本独立插件环境(async () { try { const results await listEffectStyles(); figma.closePlugin(JSON.stringify(results)); } catch(e) { figma.closePluginWithFailure(e.toString()); } })()注意两点必须使用getLocalEffectStylesAsync()。同步版本getLocalEffectStyles()已标记为deprecatedd.ts L1484-L1489在插件 manifest 含documentAccess: dynamic-page时会直接抛异常在 use_figma 环境中输出应改为return results不要调用figma.closePlugin()也不要把代码包进 async IIFE——运行时已自动处理见 SKILL.md 关键规则。在 use_figma 环境中的等价写法const styles await figma.getLocalEffectStylesAsync(); return styles.map(s ({ id: s.id, name: s.name, key: s.key, effectCount: s.effects.length }));二、创建投影效果样式创建投影样式时两个关键约束也是出错率最高的点颜色是 RGBA 0–1 范围0.15即 15% 透明度对应约 38/255effects是只读数组——创建时直接整体赋值一个新数组永远不要原地 push/mutate。/** * Creates a drop shadow effect style. * * param {string} name - e.g. Elevation/200 * param {{ r: number, g: number, b: number, a: number }} color - RGBA, 0-1 range * param {{ x: number, y: number }} offset * param {number} radius - blur radius * param {number} [spread0] * returns {EffectStyle} */ function createDropShadowStyle(name, color, offset, radius, spread) { const style figma.createEffectStyle(); style.name name; style.effects [{ type: DROP_SHADOW, color, offset, radius, spread: spread || 0, visible: true, blendMode: NORMAL }]; return style; }完整可运行脚本独立插件环境(async () { try { const style createDropShadowStyle( Elevation/200, { r: 0, g: 0, b: 0, a: 0.15 }, { x: 0, y: 4 }, 12, 0 ); figma.closePlugin(JSON.stringify({ id: style.id, name: style.name })); } catch(e) { figma.closePluginWithFailure(e.toString()); } })()参数取值参考参数含义常见设计系统取值color阴影颜色RGBA 0–1黑色{0,0,0,0.12}{0,0,0,0.3}用于不同层级offset偏移量像素层级越高y偏移越大如 1/2/4/8radius模糊半径像素随层级增大如 2/4/12/24spread扩散量像素默认 0多数投影用 0描边阴影才用正值createEffectStyle()是 Figma Design 专属 APId.ts L1448-L1453在 FigJam 中不可用。用name中的/分隔符即可在 Figma 样式面板中自动形成分组例如Elevation/100、Elevation/200、Elevation/300。多个效果与渲染顺序effects数组中元素顺序影响视觉效果投影按从底部到顶部的顺序渲染。若需要同时有投影 背景模糊可整体赋值多元素数组style.effects [ { type: DROP_SHADOW, color: { r: 0, g: 0, b: 0, a: 0.15 }, offset: { x: 0, y: 4 }, radius: 12, spread: 0, visible: true, blendMode: NORMAL }, { type: BACKGROUND_BLUR, radius: 8, visible: true } ];修改已有样式时同样遵守只读约束// ❌ 错误原地修改 // style.effects.push(newEffect); // ✅ 正确克隆数组后整体重新赋值 style.effects [...style.effects, newEffect];三、将效果样式应用到节点创建样式不会自动生效——必须把样式的id赋给节点的effectStyleId属性节点才会呈现该样式这也是新手最容易忽略的一点。以下函数按节点名子串匹配当前页所有节点将指定样式批量应用并返回成功应用的节点数/** * Applies an effect style to all nodes on the current page that match a given name pattern. * * param {string} styleId - The ID of an EffectStyle. * param {string} nodeNamePattern - Substring match against node names. * returns {number} - Number of nodes the style was applied to. */ function applyEffectStyleToMatchingNodes(styleId, nodeNamePattern) { const nodes figma.currentPage.findAll(n n.name.includes(nodeNamePattern)); let applied 0; for (const node of nodes) { if (effectStyleId in node) { node.effectStyleId styleId; applied; } } return applied; }完整可运行脚本独立插件环境(async () { try { const applied applyEffectStyleToMatchingNodes(STYLE_ID, Card); figma.closePlugin(JSON.stringify({ applied })); } catch(e) { figma.closePluginWithFailure(e.toString()); } })()要点拆解figma.currentPage.findAll()递归遍历当前页全部节点n.name.includes(nodeNamePattern)是子串匹配如传Card会命中Card、Card/Header、PrimaryCard等effectStyleId in node用于过滤——只有支持效果属性的节点类型如矩形、Frame、组件实例才有该属性避免对文本节点等无效类型赋值报错应用后节点的effects属性会自动反映样式中的值。dynamic-page 模式下的写入差异从 typings 可以看到当插件 manifest 使用documentAccess: dynamic-page时effectStyleId变为只读属性必须改用异步写入 APId.ts L6390-L6398await node.setEffectStyleIdAsync(styleId);建议统一用setEffectStyleIdAsync()它兼容两种 documentAccess 模式。四、效果样式中的变量绑定效果样式可以和变量体系协同工作效果中可绑定变量的字段为color、radius、spread、offsetX、offsetY即VariableBindableEffectFieldd.ts L5751。在节点上绑定变量的核心函数是setBoundVariableForEffectd.ts L2136-L2147// 绑定前先获取变量 const [radiusVar] await figma.variables.getLocalVariablesAsync(); // setBoundVariableForEffect 返回一个【新的】effect 对象——必须捕获并整体重新赋值 node.effects node.effects.map(effect { if (effect.type DROP_SHADOW) { return figma.setBoundVariableForEffect(effect, radius, radiusVar); } return effect; });两个关键事实也是常见出错点setBoundVariableForEffect返回新 effect 对象不修改原对象——必须捕获返回值并重新赋值effects数组传入null作为变量参数可解除该字段的绑定传入变量 ID 字符串不受支持必须传Variable对象。更多变量集合、作用域与绑定模式参见 variable-patterns 参考。五、其他相关 API排序moveLocalEffectStyleAfter(targetNode, reference)可在本地效果样式内部调整顺序传null表示移到首位仅 Figma Design 可用d.ts L1530-L1535样式检查每个EffectStyle都有稳定不变的key跨文件/跨库引用样式时应优先用key而非idid在不同文件副本间不保证稳定。六、常见陷阱速查陷阱正确做法effects是只读数组克隆后整体重新赋值style.effects [...style.effects, newEffect]使用已弃用的getLocalEffectStyles()一律用getLocalEffectStylesAsync()颜色写成 0–255 或十六进制用 0–1 范围 RGBA如{r: 0, g: 0, b: 0, a: 0.15}创建样式后以为会自动生效必须把style.id赋给节点的effectStyleId忘记效果数组顺序投影从底部向顶部渲染多效果时注意书写顺序绑定变量后忘记重新赋值setBoundVariableForEffect返回新 effect必须捕获忽略节点类型直接赋effectStyleId先effectStyleId in node过滤支持类型完整的错误示范与正确示范对照见 gotchas 参考效果样式在大型设计系统Token 命名、变量绑定、迁移中的完整方法论见 wwds-effect-styles。七、在 use_figma 工作流中落地以上脚本都基于原生 Plugin API。在 figma-use skill 的use_figmaMCP 环境中运行需遵循其运行时约束详见 SKILL.md用return输出结果不使用figma.closePlugin()不要包 async IIFE顶层await与return即可禁用figma.notify()与console.log()输出创建/修改节点的脚本必须return全部受影响节点 ID。例如完整的列出所有本地效果样式在 use_figma 中只需const styles await figma.getLocalEffectStylesAsync(); return styles.map(s ({ id: s.id, name: s.name, key: s.key, effectCount: s.effects.length }));推荐的分步工作流先用只读脚本return出样式 ID 列表再把 ID 作为字符串字面量传给下一步的创建/应用脚本最后用get_metadata校验effectStyleId与效果数量是否落地避免一次性大脚本带来的定位困难。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考