figma-use-slides

use_figma — Slides 的 Figma Plugin API 技能

此技能包含适用于 use_figma MCP 工具的 Slides 专属上下文。figma-use 技能提供通过 MCP 执行插件 API 的基础上下文，以及完整的 Figma 插件 API，供处理本文未说明的高级用例。

调用 use_figma 执行 Slides 操作时，务必在逗号分隔的 skillNames 参数中包含 figma-use-slides。如果此技能是通过 MCP 资源加载的，则必须在名称前加上 resource: 前缀（例如 resource:figma-use-slides）。 这是用于跟踪技能使用情况的日志参数，不会影响执行。

选择如何制作 Slides 演示文稿

如果你的环境还提供 generate_deck 工具，则每个演示文稿请求只能选择一种方式，不要针对同一份演示文稿同时调用两种工具。

何时使用哪种方式

use_figma + 此技能（默认）： 可处理任何 Slides 任务，包括制作新演示文稿、编辑现有演示文稿、符合品牌风格的设计、参考文件样式、迭代优化、演讲者备注，以及对布局、颜色和字体的全面创意控制。大多数请求都应使用此方式。

generate_deck： 通过一次调用，使用预先制作并精选的模板生成完整演示文稿。适用于快速制作简单的演示文稿，且用户不需要定制设计、品牌风格匹配或参考文件样式的情况。它无法使用自定义模板，无法参考其他 Figma 文件来确定设计方向，也不支持通过对话进行迭代编辑或后续修改。

如有疑问，默认使用 use_figma + 此技能——它涵盖了 generate_deck 的全部功能，且更多。

二选一并坚持到底

为某份演示文稿选择一种方式后，就用该方式完成整个请求。不要先用 generate_deck 生成演示文稿，然后又用 use_figma 创建或填充文件——这样会产生重复且相互冲突的内容，令用户感到困惑。

关键规则（Slides 专用）

1. 新建的 Slides 文件默认使用浅色主题。 通过 create_new_file 创建 Slides 文件时，系统会自动初始化默认浅色主题。此主题只是结构脚手架——你应该根据要制作的演示文稿设计方向，覆盖主题的颜色变量和文本样式。不要依赖默认浅色主题标记，也不要受其影响。
2. 必须先执行 appendChild，再设置 x/y——适用于每个节点和每一层嵌套。 新建节点会被静默地自动挂接到幻灯片上下文中的绝对坐标 (240, 240)（幻灯片网格的 GRID_PADDING）。在执行 appendChild 前写入 x/y，会导致该值相对于这个隐藏原点存储；随后挂接到实际父节点时，节点就会落在 (预期位置 − 240, 预期位置 − 240)。这个 Bug 偶尔发生——同一脚本中的某些帧可能不会出现问题，因此测试成功并不能证明你是安全的。**识别特征：**如果任何节点相对于你设置的位置偏移了 (−240, −240)，说明代码在最终的 appendChild 前设置了 x/y。不要尝试再加上 240 来补偿——重试时结果会更糟。应该修正操作顺序。请参阅 slide-gotchas.md，了解如何通过辅助模式确保顺序不会出错。
3. SLIDE_GRID 和 SLIDE_ROW 是不透明节点——不要访问它们的 .fills、.effects 或布局属性。只有 SLIDE 节点（类型为 'SLIDE'）才扩展 BaseFrameMixin。**例外：**可以设置 SLIDE_ROW.name——插件正是通过这种方式重命名幻灯片区段（例如 slideRow.name = "Intro"）。请参阅 slide-lifecycle.md。
4. get_metadata 不适用于 Slides 文件。 请使用只读 use_figma 脚本进行验证。在 closePlugin() 输出中返回已创建节点的位置，并确认边界框没有重叠。
5. 在 Slides 中不要调用 figma.createPage()。 这会抛出 TypeError: figma.createPage no such property 'createPage' on the figma global object——createPage() 仅适用于 Design 文件（figma.com/design/...）；Slides 的 URL 是 figma.com/slides/...。请改用幻灯片网格（SLIDE_GRID / SLIDE_ROW / SLIDE）来组织演示文稿结构——请参阅 slide-lifecycle.md 和 slide-grid.md。
6. 绝不要删除现有幻灯片并重新制作。 当用户要求改进、重新设计或更改演示文稿样式时，应直接修改现有幻灯片。只有用户明确要求“重新开始”或“从头重做”时，才删除幻灯片。

设计思考

并非所有任务都需要同等程度的设计思考。开始操作前，先判断你属于哪种模式：

• 内容/属性编辑——更改文本、替换颜色、更新数字、修正对齐方式或调整元素大小。无需进行设计思考，直接修改，并与现有内容保持一致。
• 结构性增补——添加幻灯片、重新设计某个区段的布局、更改演示文稿的配色，或引入新的视觉元素。这也包括用户要求“改进”“重新设计”或“更改样式”的情况——这些都是对现有内容进行原位编辑，而不是制作新演示文稿。需要进行设计思考，但应采用继承模式：现有演示文稿就是你的设计语言。检查它，并匹配其配色、字体、空间布局习惯和视觉主题。延续演示文稿现有的风格，而不是彻底重塑。
• 创建新演示文稿——从头制作演示文稿，或基于空白文件制作。需要进行下文所述的完整设计思考。

对于现有演示文稿的结构性增补：在进行更改前，运行检查脚本（如下所示）并截取屏幕截图。“采用什么配色？”和“使用什么字体样式？”的答案已经存在于文件中——你的任务是读懂并保持一致。slide-design.md 中的设计原则描述的是你要匹配的内容，而不是由你选择的内容。

新演示文稿的设计流程

在为新演示文稿编写任何 Plugin API 代码之前，先想清楚它应该给人怎样的感受。Figma 用户对视觉效果有很高的期待——如果演示文稿看起来像是由通用模板生成器制作的，就会以错误的方式格外显眼。

1. 阅读需求说明。 演示文稿要传达什么内容，面向哪些人？投资者路演、团队回顾、产品发布和技术深度讲解，都需要不同的视觉处理方式。设计应与内容密不可分。
2. 检查是否已有设计语言。 在构思任何设计之前，先看看用户已经提供了什么。提示词中的品牌指南——配色方案、字体规范、Logo 使用规则、风格描述——都是已经确定的设计决策。用户提供的 Figma 参考文件链接，是需要认真研究的设计语言，而不是匆匆一瞥即可。用户输入越具体，你自行发挥的空间就越小。用户提供参考时，你的工作就从设计师转变为诠释者：提炼设计语言，并将其忠实地应用到新内容中。
3. 对剩余部分做出明确选择。 如果用户提供了完整的品牌体系，你的创作空间在于布局、节奏和构图，而不是颜色或字体。如果用户只提供了一张用于启发灵感的参考幻灯片，你会有更大的发挥空间，但仍应呼应它的特质。如果用户什么都没提供，那么所有设计决策都由你负责——选择一套配色方案、一种字体处理方式、一种空间组织方式，并在每一张幻灯片中贯彻到底。与在每个决策上都求稳相比，立场鲜明的演示文稿（即使这种立场很含蓄）总是更出彩。“做出明确选择”的空间大小，与用户提供的信息量成反比。
4. 打造标志性元素。 每份优秀的演示文稿至少都有一个元素，即使脱离上下文也能让人一眼认出：独特的配色、出人意料的布局节奏，或反复出现的形状语言。遵循品牌指南设计时，标志性元素应源自品牌语言——强化已有元素，而不是添加格格不入的内容。从零开始设计时，应在动手制作之前确定标志性元素是什么。

阅读参考文件

当用户提供 Figma 文件链接作为参考时，请先研究该文件，再进行任何设计。具体提取哪些内容取决于文件类型：

• 幻灯片文件：get_metadata 无法用于幻灯片文件。请使用 get_screenshot 捕获各张幻灯片以供视觉参考，并使用 use_figma 和参考文件的 fileKey 运行只读脚本，提取主题变量、调色板、字体选择和布局模式。
• 设计文件：get_design_context 可提供全面的设计数据，包括颜色、排版和布局结构。get_screenshot 可提供视觉参考。两者都要使用。

参考文件中需要关注的内容：调色板（哪种色调占主导、强调色是什么、如何使用深色／浅色背景）、字体选择（字体系列、字重、如何处理层级）、空间布局习惯（内容锚定的位置、留白多少、元素是否延伸出边缘），以及任何反复出现的视觉元素（形状、线条处理方式、装饰元素）。这些是你需要沿用的设计决策，其余部分由你决定。

具体遵循参考文件到什么程度，取决于用户的要求。“做得和这个一样”意味着用新内容复现其设计语言。“以此为灵感”意味着呼应其风格特征，同时保留自己的创意。“这是我们的品牌指南”意味着提取品牌系统并始终如一地应用。如有疑问，请尽量贴近参考——用户更容易要求你偏离参考，也比让你撤销与其品牌冲突的自创设计更容易。

加载 slide-design.md，了解颜色、字体、布局模式、构图和需要避免的做法。若有参考文件或品牌指南，请将 slide-design.md 的原则作为用户未作决定时的默认选项，而不要用它们覆盖用户已经作出的决定。

幻灯片制作工作流

制作 5 张或更多幻灯片的新演示文稿时，请采用以下两阶段工作流。此工作流专门用于制作演示文稿，取代 figma-use 第 6 节中的通用增量工作流——原则仍然适用，但执行节奏有所不同。

阶段 1 — 设计与规划

完成上述设计思考流程（阅读需求说明、检查设计语言、明确立场、打造标志性特色），然后在编写任何 use_figma 代码之前，制定覆盖整套演示文稿的幻灯片计划：

1. 逐张幻灯片制定计划。 对每张幻灯片，说明其目的／内容、用空间位置描述布局方案（例如：“标题锚定在左上方，规格卡片占据右侧三分之一，装饰圆形从右上边缘延伸出去”），并说明背景处理方式（深色／浅色／渐变）。规划时不要计算像素坐标——用空间位置描述布局。坐标计算留到代码生成阶段。
2. 共享常量。 声明要使用的字体系列和样式、以命名角色标注的调色板（primary、accent、bgDark、surface、textPrimary、textMuted 等），以及反复出现的视觉元素或标志性元素。
3. 布局多样性检查。 按顺序通读幻灯片计划。如果布局描述显得重复——“双栏、双栏、网格、双栏”——请在开始制作前重新调整。这是增加多样性成本最低的时机。反模式请参阅 slide-design.md。
4. 代码前置部分。 写出将粘贴到每个构建脚本顶部的可复用前置代码：const C = { ... } 调色板对象、Promise.all([...]) 字体加载代码块，以及来自 slide-gotchas.md 的 addFrame／addText／addRect 辅助函数。

阶段 2 — 构建

分批大量执行计划。目标是尽量减少思考后再构建的循环次数，而不是减少每个脚本中的元素数量。

• 每次 use_figma 调用构建 3–5 张幻灯片。 结构相似的幻灯片（例如一系列产品功能幻灯片）可以放在同一批次中。每张幻灯片都是独立的子树——不存在跨幻灯片依赖，因此大批次是安全的。
• 批次之间不要重新规划。 设计已在阶段 1 中确定。如果批次成功并通过验证，就立即继续下一批。只有当批次失败，或出现需要更改方案的视觉问题时，才重新规划。
• 在每个构建脚本顶部粘贴代码前导部分（颜色、字体、辅助函数）。逐字复制阶段 1 中的内容，不要重新推导。
• 使用 slide-gotchas.md 中的确定性批次验证脚本验证每个批次。 该脚本会在约 3 秒内检查元素重叠、文本裁切和节点越界。如果检查通过，就无需截图，直接继续。如果检查失败，则为受影响的幻灯片截图并修复后再继续。
• 只在检查点截图——第一批之后（验证视觉系统：颜色、排版、设计方向），以及最后一批之后（检查整体质量）。每个检查点使用内联 await slide.screenshot() 为 1–2 张有代表性的幻灯片截图，而不是单独调用 get_screenshot。
• 始终在每个构建脚本中返回所有已创建的节点 ID。

分区

分区是幻灯片网格中的一行——每一行都是一个分区。名称会显示在编辑器中（行的旁边）和演讲者视图中（方便演讲者在不同组之间跳转）。分区是为编辑演示文稿的人提供的组织工具——由用户决定在哪里划分，而不是由你决定。

收到整理演示文稿的请求时

“整理这份演示文稿”含义模糊——可能指分组、重新排序、去重或重组。在使用 AskUserQuestion 前，先阅读演示文稿。

默认做法：提出方案，而不是提问。 大多数演示文稿都有线索——首尾呼应的标题、编号用例、重复出现的 之前 / 之后 配对、过渡幻灯片（“然后 X 加入对话”）、谢谢。有线索时，选定一种分区方案，并在一条确认消息中说明。方案中范围明确的选择（例如用一行 用例，还是分成三行；过渡幻灯片放在哪里）都可以调整——选一种并继续。

备用做法：缺少线索时再提问。 如果幻灯片顺序杂乱，或没有清晰主线，就询问哪些范围应放在一起，以及应如何命名。不要为了省事而直接按三等分切分，代替阅读演示文稿。

命名与范围

名称应简短（1–3 个词）、具体（演示 优于 展示与讲解），并在同一份演示文稿中保持一致。通常分成 2–5 个分区；只有演示文稿很长或有重复结构时才需要更多。名称不是幻灯片标题——它们用于帮助查找一组幻灯片，而非描述其内容。

重命名分区

getSlideGrid() 返回 SlideNode[][]——内部数组是普通的 JS 幻灯片数组，不是 SLIDE_ROW 节点。在这些数组上设置 .name 会静默失效。要重命名分区，请遍历节点树，并在实际的 SLIDE_ROW 上设置 .name：

const slideGrid = figma.currentPage.children.find(c => c.type === "SLIDE_GRID");
slideGrid.children[0].name = "Intro";

演讲者备注

演讲者备注是演讲者针对每张幻灯片的私人辅助材料。备注会显示在演讲者视图中（仅演讲者可见，观众不可见），可在现场演示时用作讲稿、提示单或要点参考。

何时编写演讲者备注

• 用户提出要求时：如果用户要求演讲者备注、演示者备注、谈话要点或演示文稿脚本，请为每张包含实质性内容的幻灯片编写备注（跳过章节分隔页或纯装饰性幻灯片，除非有内容需要说明）。
• 可直接用于演示的演示文稿：如果用户明确要求制作可用于现场演示的演示文稿，演讲者备注会很有用。当备注有助于演示者了解节奏、过渡或幻灯片上未呈现的背景信息时，请添加备注。
• 内容稀疏或以视觉元素为主的幻灯片：如果幻灯片围绕图表、图像、隐喻或发人深省的问题展开，备注有助于说明演示者应该说些什么。当视觉背景很重要时，可使用截图或 node.screenshot() 处理图片较多、图表较多或视觉内容较少的幻灯片，但不要默认对每张幻灯片都截图——图片会占用上下文预算。
• 不要主动添加备注：对于常规幻灯片编辑、版式工作或现有演示文稿更新，除非用户提出要求，否则不要填写演讲者备注。添加备注会改变演示流程，也可能让演示文稿的所有者感到意外。

优质演讲者备注的特点

演讲者备注是写给演示者的，不是观众。它们应该像一位值得信赖的同事俯身轻声提醒你“该说些什么”。优质备注应当：

• 补充幻灯片，而不是复述内容。 如果幻灯片写着“收入增长了 40%”，备注就不该再说“收入增长了 40%”。而应该说明增长的原因、观众应该记住什么，或者这个数据通常会引出什么问题。
• 简洁易浏览。 演示者在讲话时低头看一眼，就需要立刻找到位置。使用简短的项目符号，不要写密集的段落。每个要点只讲一个意思。
• 包含过渡语。 最好的备注会告诉演示者如何衔接幻灯片：“掌声平息后……”或“这延续了上一点——提一下 40% 这个数字。”
• 补充幻灯片无法呈现的背景信息。 数据来源（“来源：Q4 FY25 内部指标，尚未公开”）、注意事项（“如果 CFO 在场，请跳过这张幻灯片”）、时间提示（“现在到了一半，你应该已经讲了约 10 分钟”）以及预期问题（“他们会问利润率——请参阅附录第 14 张幻灯片”）。
• 符合演示文稿的语体。 面向投资者的演讲应精准且经过排练。团队复盘应轻松灵活。主题演讲可以包含舞台指示。请根据语境匹配语气。

演讲者备注中应避免的内容

• 完整脚本：大段文字会让人照稿逐字朗读，导致演示效果很差。如果用户明确要求脚本，请编写脚本；但默认使用项目符号。
• 面向观众的格式：观众看不到备注。不要为了让非演示者更容易阅读而优化备注。
• 重复幻灯片内容：如果幻灯片不言自明（例如附有联系信息的“谢谢”页），就不需要备注。留空某张幻灯片的备注也没问题。

格式

slide.speakerNotes 接受 Markdown 字符串。优先使用项目符号作为主要结构；粗体适合强调演示者不应略过的关键词语。有关支持的（列表、粗体、斜体、删除线）和不支持的（标题、代码块、行内代码、链接）Markdown 格式的完整列表，请参阅 slide-properties.md。

检查 Slides 文件

目前还没有专门用于读取 Slides 文件的工具。请使用 use_figma 配合只读脚本进行检查，并使用 get_screenshot / await node.screenshot() 获取视觉上下文。

• 先检查，再创建。 创建任何内容之前，先运行只读的 use_figma，了解现有内容，包括幻灯片、文本、组件和命名惯例。figma-use 第 6 节“先检查”中的模式也适用于此处。
• get_metadata 不适用于 Slides 文件——它仅支持 figma（Design）编辑器类型。
• 不会返回 console.log() 的输出——只有 return 值会返回。请始终 return 所需的数据。
• 使用 get_screenshot 获取视觉上下文——传入有效的 nodeId 以获取截图。也可以在 use_figma 脚本中内联使用 await node.screenshot()。

快速检查脚本

列出演示文稿中的所有幻灯片：

const grid = figma.getSlideGrid();
return grid.map((row, rowIdx) =>
  row.map((slide, colIdx) => ({
    id: slide.id,
    name: slide.name,
    row: rowIdx,
    col: colIdx,
    isSkipped: slide.isSkippedSlide,
    speakerNotes: slide.speakerNotes,
  }))
);

获取指定幻灯片中的文本内容：

const slide = figma.getNodeById("TARGET_SLIDE_ID");
// findAllWithCriteria uses an indexed type lookup — much faster than
// findAll(n => n.type === 'TEXT') on slides with many shapes/images.
const textNodes = slide.findAllWithCriteria({ types: ["TEXT"] });
const fontsToLoad = new Set();
for (const t of textNodes) {
  if (t.fontName !== figma.mixed) {
    fontsToLoad.add(JSON.stringify(t.fontName));
  } else {
    const segments = t.getStyledTextSegments(["fontName"]);
    for (const seg of segments) fontsToLoad.add(JSON.stringify(seg.fontName));
  }
}
for (const f of fontsToLoad) {
  await figma.loadFontAsync(JSON.parse(f));
}
return textNodes.map(t => ({
  id: t.id,
  name: t.name,
  characters: t.characters,
  x: t.x,
  y: t.y,
  width: t.width,
  height: t.height,
}));

参考文档

只加载任务所需的参考资料：

• slide-gotchas — Slides 特有的注意事项（坐标偏移、不透明节点类型、验证变通方法）
• slide-lifecycle — 创建、克隆、删除和重新排序幻灯片及幻灯片行
• slide-grid — 使用幻灯片网格布局（getSlideGrid、setSlideGrid）
• slide-content — 在幻灯片中构建内容（文本、形状、自动布局——SlideNode 扩展自 BaseFrameMixin）
• slide-properties — 幻灯片专属属性（speakerNotes、isSkippedSlide、focusedSlide、focusedNode、slideThemeId、InteractiveSlideElementNode）
• slide-design — 打造视觉效果丰富、多样化演示文稿的设计原则（色彩策略、排版、布局多样性、空间构成、反模式）