use_figma — Figma 插件 API 动效技能
动效上下文,用于 use_figma MCP 工具。figma-use 涵盖了基础的插件 API 规则——请同时加载两者。
在进行动效相关工作时,务必以逗号分隔的形式将 skillNames: "figma-use-motion" 与 figma-use 一同传递给 use_figma。 仅用于日志记录。
运行时门控
动效 API 受 metronome_plugin_api 用户特性标志门控。当调用用户未启用该标志时,本技能中涉及的所有动效属性和辅助方法都会抛出 "<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 已经是上限。更高的 fps 只会无谓地增加渲染负担。
机制: 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仅显示静止状态。