# 代码连接组件 ## 概述此技能可帮助您使用 Figma 的代码连接功能将 Figma 设计组件连接到其相应的代码实现。它分析 Figma 设计结构，搜索代码库以查找匹配组件，并建立保持设计代码一致性的映射。 ## 先决条件 * Figma MCP 服务器必须已连接且可访问 * 在继续之前，请通过检查 Figma MCP 工具（例如“get_code_connect_suggestions”）是否可用来验证 Figma MCP 服务器是否已连接。 * 如果工具不可用，Figma MCP 服务器可能无法启用。指导用户启用插件附带的 Figma MCP 服务器。之后他们可能需要重新启动 MCP 客户端。 * 用户必须提供带有节点 ID 的 Figma URL：`https://figma.com/design/:fileKey/:fileName?node-id=1-2` * **重要：** Figma URL 必须包含 `node-id` 参数。如果没有它，Code Connect 映射将会失败。 * **重要：** Figma 组件必须发布到团队库。 Code Connect 仅适用于已发布的组件或组件集。 * **重要提示：** Code Connect 仅适用于组织和企业计划。 * 访问项目代码库以进行组件扫描 ## 所需的工作流程 **按顺序执行这些步骤。不要跳过步骤。** ### 第 1 步：获取代码连接建议调用“get_code_connect_suggestions”以在单个操作中识别所有未映射的组件。该工具自动： * 从 Figma 场景图中获取组件信息 * 标识选择中已发布的组件 * 检查现有的 Code Connect 映射并过滤掉已连接的组件 * 返回每个未映射组件的组件名称、属性和缩略图解析 URL 以提取“fileKey”和“nodeId”，然后调用“get_code_connect_suggestions”。 **重要：** 从 Figma URL 中提取节点 ID 时，请转换格式： * URL 格式使用连字符：`node-id=1-2` * 工具需要冒号：`nodeId=1:2` **解析Figma URL：** * URL 格式：`https://figma.com/design/:fileKey/:fileName?node-id=1-2` * 提取文件密钥： `:fileKey` （`/design/` 之后的段） * 从URL中提取节点ID：`1-2`，然后转换为`1:2`以供工具使用 get_code_connect_suggestions(fileKey=":fileKey", nodeId="1:2") **处理响应：** * 如果工具返回 **“在此选择中未找到已发布的组件”** → 通知用户并停止。可能需要首先将组件发布到团队库。 * 如果工具返回 **“此选择中的所有组件实例已通过 Code Connect 连接到代码”** → 通知用户所有内容都已映射。 * 否则，响应包含未映射组件的列表，每个组件具有： * 组件名称 * 节点ID * 组件属性（带有 prop 名称和值的 JSON） * 组件的缩略图（用于目视检查） ### 第 2 步：扫描代码库以查找匹配的组件对于“get_code_connect_suggestions”返回的每个未映射组件，在代码库中搜索匹配的代码组件。 **要寻找什么：** * 与 Figma 组件名称匹配或相似的组件名称 * 与 Figma 层次结构一致的组件结构 * 与 Figma 属性相对应的道具（变体、文本、样式） * 典型组件目录中的文件（`src/components/`、`components/`、`ui/` 等） **搜索策略：** 1. 搜索名称匹配的组件文件 2. 阅读候选文件以检查结构和道具 3.将代码组件的props与步骤1中返回的Figma组件属性进行比较 4.检测编程语言（TypeScript、JavaScript）和框架（React、Vue等） 5. 根据结构相似性确定最佳匹配，权衡： * 道具名称及其与 Figma 属性的对应关系 * 默认值与 Figma 默认值匹配 * CSS 类或样式对象 * 澄清意图的描述性评论 6. 如果多个候选者都同样优秀，请选择与 prop-interface 匹配最接近的一个，并在工具调用之前用 1-2 句话的注释记录您的推理 **搜索模式示例：** * 如果 Figma 组件是“PrimaryButton”，则搜索 `Button.tsx`、`PrimaryButton.tsx`、`Button.jsx` * 检查常用组件路径：`src/components/`、`app/components/`、`lib/ui/` * 寻找与Figma变体相匹配的变体道具，如“variant”、“size”、“color” ### 第 3 步：向用户呈现匹配展示您的发现并让用户选择要创建的映射。用户可以接受全部、部分或不接受建议的映射。 **以这种格式呈现匹配：** 以下组件与设计相匹配： - [组件名称]（路径/到/组件）：节点 ID 处的设计组件名称 [节点 ID](figmaUrl?node-id=X-Y) - [AnotherComponent](路径/到/另一个): AnotherDesign at nodeId [nodeId2](figmaUrl?node-id=X-Y) 您想连接这些组件吗？您可以接受全部、选择特定的或跳过。 **如果没有找到精确匹配的组件：** * 显示 2 个最接近的候选人 * 解释差异 * 要求用户确认使用哪个组件或提供正确的路径 **如果用户拒绝所有映射**，请通知他们并停止。不需要进一步的工具调用。 ### 步骤 4：创建代码连接映射用户确认其选择后，仅使用接受的映射调用“send_code_connect_mappings”。该工具可以在一次调用中批量创建所有映射。 **示例：** 发送代码连接映射（文件密钥=“：文件密钥”，节点ID =“1：2”，映射=[ { nodeId: "1:2", componentName: "Button", 来源: "src/components/Button.tsx", label: "React" }, { nodeId: "1:5", componentName: "Card", 来源: "src/components/Card.tsx", label: "React" } ] ） **每个映射的关键参数：** * `nodeId`：Figma 节点 ID（冒号格式：`1:2`） * `componentName`：要连接的组件的名称（例如“Button”、“Card”） * `source`: 代码组件文件的路径（相对于项目根目录） * `label`：此 Code Connect 映射的框架或语言标签。有效值包括： * Web：“React”、“Web Components”、“Vue”、“Svelte”、“Storybook”、“Javascript” * iOS：“Swift UIKit”、“Objective-C UIKit”、“SwiftUI” * Android：“Compose”、“Java”、“Kotlin”、“Android XML 布局” * 跨平台：“颤动” * 文档：“Markdown” **通话后：** * 成功时：该工具确认映射已创建 * 出错时：该工具报告哪些特定映射失败以及原因（例如，“组件已映射到代码”、“未找到已发布的组件”、“权限不足”） **处理后提供摘要**：代码连接摘要： - 成功连接：3 - 按钮 (1:2) → src/components/Button.tsx - 卡 (1:5) → src/components/Card.tsx - 输入 (1:8) → src/components/Input.tsx - 无法连接：1 - CustomWidget (1:10) - 在代码库中找不到匹配的组件 ## 示例 ### 示例 1：连接按钮组件用户说：“将此 Figma 按钮连接到我的代码：” **行动：** 1.解析URL：fileKey=`kL9xQn2VwM8pYrTb4ZcHjF`,nodeId=`42-15`→转换为`42:15` 2. 运行 `get_code_connect_suggestions(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42:15")` 3. 响应显示：具有“variant”（主要/次要）和“size”（sm/md/lg）属性的按钮组件（未映射）以及缩略图 4. 在代码库中搜索 Button 组件：查找 `src/components/Button.tsx` 5. 读取 `Button.tsx` 并确认它具有 `variant` 和 `size` 属性 6. 向用户呈现：“我找到了匹配项： * [按钮]()：nodeId 处的按钮 [42:15]() 您想连接这个组件吗？” 7. 用户确认：“是” 8. 检测它是 TypeScript React 组件 9. 运行 `send_code_connect_mappings(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42:15", mappings=[{ nodeId: "42:15", componentName: "Button", source: "src/components/Button.tsx", label: "React" }])` **结果：** Figma 按钮组件现在已连接到代码 Button 组件。 ### 示例 2：部分选择的多个组件用户说：“连接此框架中的组件：” **行动：** 1.解析URL：fileKey=`pR8mNv5KqXzGwY2JtCfL4D`,nodeId=`10-50`→转换为`10:50` 2. 运行 `get_code_connect_suggestions(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId="10:50")` 3. 响应显示 3 个未映射的组件：ProductCard、Badge 和 CustomWidget 4. 搜索代码库： * ProductCard：找到`src/components/ProductCard.tsx`（道具匹配） *徽章：找到`src/components/Badge.tsx`（道具匹配） * CustomWidget：找不到匹配的组件 5. 向用户展示：“以下组件符合设计： * [ProductCard]()：nodeId 处的 ProductCard [10:51]() * [徽章]()：nodeId 处的徽章[10:52]() 我找不到 CustomWidget 的匹配项 (10:53)。您想连接这些组件吗？您可以接受全部、选择特定的或跳过。” 6. 用户：“只需连接 ProductCard，暂时跳过 Badge” 7. 运行 `send_code_connect_mappings(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId="10:50", mappings=[{ nodeId: "10:51", componentName: "ProductCard", source: "src/components/ProductCard.tsx", label: "React" }])` **结果：** 根据用户的选择，仅连接 ProductCard。 ### 示例 3：组件需要创建用户说：“连接此图标：” **行动：** 1.解析URL：fileKey=`8yJDMeWDyBz71EnMOSuUiw`,nodeId=`5-20`→转换为`5:20` 2. 运行 `get_code_connect_suggestions(fileKey="8yJDMeWDyBz71EnMOSuUiw", nodeId="5:20")` 3. 响应显示：具有颜色和大小属性的 CheckIcon 组件（未映射） 4. 搜索 CheckIcon 的代码库：未找到匹配项 5. 搜索通用图标组件：找到包含其他图标的`src/icons/`目录 6. 向用户报告：“我找不到 CheckIcon 组件，但我在 src/icons/ 找到了一个图标目录。您是否愿意： * 先新建一个CheckIcon.tsx组件，然后连接它 * 连接到不同的现有图标 * 提供 CheckIcon 的路径（如果它存在于其他地方） 7. 用户提供路径：“src/icons/CheckIcon.tsx” 8. 从文件中检测语言和框架 9. 运行 `send_code_connect_mappings(fileKey="8yJDMeWDyBz71EnMOSuUiw", nodeId="5:20", mappings=[{ nodeId: "5:20", componentName: "CheckIcon", source: "src/icons/CheckIcon.tsx", label: "React" }])` **结果：** CheckIcon组件已成功连接到Figma设计。 ## 最佳实践 ### 主动组件发现不要只询问用户文件路径 - 主动搜索他们的代码库以查找匹配的组件。这提供了更好的体验并抓住潜在的绘图机会。 ### 精准的结构匹配将 Figma 组件与代码组件进行比较时，不要只关注名称。检查： * 道具对齐（变体类型、尺寸选项等） * 组件层次结构匹配（嵌套元素） * 该组件具有相同的用途 ### 清晰的沟通当提出创建映射时，请清楚地解释： * 你发现了什么 * 为什么这是一个很好的匹配 * 映射会做什么 * 道具如何连接 ### 处理歧义如果多个组件可以匹配，请提供选项而不是猜测。让用户最终决定连接哪个组件。 ### 优雅的降级如果您找不到完全匹配的内容，请提供有用的后续步骤： * 显示接近的候选人 * 建议组件创建 * 请求用户指导 ## 常见问题及解决方案 ### 问题：“在此选择中未找到已发布的组件” **原因：** Figma 组件未发布到团队库。 Code Connect 仅适用于已发布的组件。 **解决方案：** 用户需要将组件发布到 Figma 中的团队库中： 1. 在 Figma 中，选择组件或组件集 2.右键单击并选择“发布到库”或使用团队库发布模式 3. 发布组件 4. 发布后，使用相同的节点 ID 重试 Code Connect 映射 ### 问题：“Code Connect 仅适用于组织和企业计划” **原因：** 用户的 Figma 计划不包括 Code Connect 访问权限。 **解决方案：** 用户需要升级到组织或企业计划，或联系其管理员。 ### 问题：在代码库中找不到匹配的组件 **原因：** 代码库搜索未找到具有匹配名称或结构的组件。 **解决方案：** 询问用户该组件是否以不同的名称存在或位于不同的位置。他们可能需要首先创建组件，或者它可能位于意外的目录中。 ### 问题：“未找到已发布的组件”(CODE_CONNECT_ASSET_NOT_FOUND) **原因：** 源文件路径不正确，该位置不存在组件，或者组件名称与实际导出不匹配。 **解决方案：** 验证源路径是否正确并且相对于项目根目录。检查组件是否已从指定了确切的组件名称的文件中正确导出。 ### 问题：“组件已映射到代码”(CODE_CONNECT_MAPPING_ALREADY_EXISTS) **原因：** 此组件已存在 Code Connect 映射。 **解决方案：** 组件已连接。如果用户想要更新映射，他们可能需要先在 Figma 中删除现有的映射。 ### 问题：“没有足够的权限来创建映射”(CODE_CONNECT_INSUFFICIENT_PERMISSIONS) **原因：** 用户没有 Figma 文件或库的编辑权限。 **解决方案：** 用户需要对包含该组件的文件进行编辑访问。联系文件所有者或团队管理员。 ### 问题：Code Connect 映射失败并出现 URL 错误 **原因：** Figma URL 格式不正确或缺少 `node-id` 参数。 **解决方案：** 验证 URL 是否符合所需格式：`https://figma.com/design/:fileKey/:fileName?node-id=1-2`。 `node-id` 参数是必需的。还要确保在调用工具时将“1-2”转换为“1:2”。 ### 问题：发现多个类似组件 **原因：** 代码库包含多个可以与 Figma 组件匹配的组件。 **解决方案：** 向用户展示所有候选者及其文件路径，并让他们选择要连接的候选者。不同的组件可能用于不同的上下文（例如，“Button.tsx”与“LinkButton.tsx”）。 ## 了解代码连接 Code Connect 在设计和代码之间建立双向链接： **对于设计人员：** 查看哪个代码组件实现了 Figma 组件 **对于开发人员：** 从 Figma 设计直接导航到实现它们的代码 **对于团队：** 维护组件映射的单一事实来源您创建的映射使这些连接变得明确且可发现，有助于保持设计和代码同步。 ## 其他资源有关代码连接的更多信息： * [Code Connect 文档]() * [Figma MCP 服务器工具和提示]()

代码连接组件

包含技能