use_figma — 用于动效的 Figma 插件 API 技能
use_figma MCP 工具的动效上下文。figma-use 包含了基础的插件 API 规则——两者应同时加载。
进行动效工作时,调用 use_figma 时必须始终传入 skillNames: "figma-use-motion"(与 figma-use 以逗号分隔一并传入)。 仅作日志记录。
运行时门控
动效 API 受 metronome 用户特性标志控制。当调用用户不具备该标志时,此技能中引用的所有动效属性和辅助方法都会抛出 "<name>" is not a supported API 错误。
遇到该错误请快速退出。 不要重试;告知用户动效功能未对其启用并停止。否则会浪费调用次数,并因重复的相同失败混淆用户。
何时使用此技能
当 use_figma 任务涉及以下内容时,请加载此技能:
- 添加、编辑或移除节点上的关键帧(
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 是上限。更高的值只会徒增渲染开销。
操作机制:export_video 仅对顶级框架有效,且该框架的子元素承载着动画(请传递该框架,而不是您添加关键帧的后代节点)。它返回一个 jobId,状态为 "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。 - 被动画的节点不是顶级框架(页面的直接子节点)。请改为动画后代元素。
- 时间轴值是公开插件 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仅显示静止状态。