Unigma

一个FigmaJSON到UGUI的导入插件.

功能列表

• 下载FigmaFile文件
• 下载 Figma Node 的 JSON 文件并把 JSON 导入为 Prefab
• 下载节点引用的 Fill 图片文件
• 转换 Figma Constraint 到 Unity RectTransform 锚点
• 转换 AutoLayout 到 Unity 的 Layout（Horizontal、Vertical、Grid）

  Note

  暂不支持 WRAP

• 转换 Figma Variant 到 Unity Animator 以及 AnimationClip
• 转换 Figma Component Instance 为已导入的 Prefab（Override Nodes）
• 通过 Plugin Tag 派发扩展逻辑（Tag 系统）
• 通过 bindingKey 自动绑定字段到 MonoBehaviour（Bind 系统）
• 设置导入目标 Layer
• 转换 Figma Variables 以及 Property
• 自动下载和解析依赖的组件

使用方法

设置 AccessToken

在 Figma 的账户设置中获得 AccessToken，并复制到 Edit > Preferences > Figma 中。

创建 FigmaFileReference

Assets/Create/Unigma/FigmaFileReference

下载 Figma 文件与节点

1. 选中 FigmaFileReference 资产，在 Inspector 中粘贴 Figma 文件链接或 File ID。 支持完整 URL 格式：https://www.figma.com/file/<ID>/... 或 https://www.figma.com/design/<ID>/...
2. 点击 Download Figma File 按钮，插件会拉取完整的 Figma 文件 JSON 并在 Inspector 中展示节点树。
3. 在节点树中选中目标节点（支持搜索过滤），点击 Download Node (.fignode) 按钮。
4. 在弹出的文件夹选择对话框中指定保存路径，插件会：
   • 在该路径下创建同名文件夹
   • 将节点 JSON 保存为 .fignode 文件
   • 自动下载节点内所有 Image Fill 贴图（PNG）并保存在同一文件夹
   • 触发 Unity 自动导入，生成 Prefab

Note

如果 Access Token 未设置，Inspector 顶部会显示警告，点击链接跳转到 Edit > Preferences > Figma 进行配置。

---

创建自定义 Processor

Processor 是导入管线的扩展点。继承自 FigmaNodeProcessor（[Serializable] 抽象类），在每个节点创建前后被调用。Processor 以 托管引用（[SerializeReference]） 的形式直接序列化在 .fignode 导入器上，无需创建 ScriptableObject 资产。

生命周期

方法	时机	说明
Initialize(context)	整棵树构建前	可获取预下载的贴图等资源
PreCreateGameObject(node, parentBounds, fileNode)	每个节点创建前	返回非 null 时接管该节点；子节点不再递归，PostCreate 不被调用
PostCreateGameObject(node, go, fileNode)	每个节点创建后	可自由添加组件或修改属性
PostBuild(root)	整棵树构建完成后	可访问完整层级，适合需要向上查找父节点的逻辑

1. 创建 Processor 脚本

using System;
using UnityEngine;
using Unigma.Figma;
using Unigma.Figma.Editor;
using Unigma.Figma.Editor.Core;

[Serializable]
public class MyProcessor : FigmaNodeProcessor
{
    // 返回非 null 时接管该节点：子节点不再递归，PostCreate 不被调用
    public override GameObject PreCreateGameObject(Node node, Rectangle parentBounds, FileNode fileNode)
    {
        return null; // 不接管，走默认创建流程
    }

    // 默认 GameObject 创建完成后调用，可自由添加组件或修改属性
    public override void PostCreateGameObject(Node node, GameObject go, FileNode fileNode)
    {
        if (node is not TextNode) return;
        // 示例：给所有文本节点挂一个自定义组件
        go.AddComponent<MyTextComponent>();
    }
}

2. 在 .fignode 导入器中添加 Processor

选中 .fignode 文件，在 Inspector 的 Processors 列表中点击 + 并从下拉菜单选择 MyProcessor。多个 Processor 按列表顺序依次执行；点击 Apply 触发重新导入。

Note

PreCreateGameObject 一旦返回非 null，后续 Processor 的 PreCreate 以及 PostCreate 均不会被调用，子节点也不会被递归——适合完全替换某类节点的渲染逻辑。

---

Tag 系统

Tag 系统允许在 Figma Plugin 数据中为节点打标签，导入时自动派发到对应的 ITagHandler 实现，无需修改 Processor 代码。

工作原理

FigmaTagNodeProcessor（内置，默认启用）在每个节点创建后读取其 Plugin 数据中的 tags，并通过 TypeCache 查找所有带 [FigmaTag("tagName")] 特性的类，实例化后调用 PostCreateGameObject。

创建 Tag Handler

using UnityEngine;
using Unigma.Figma.Editor.Tags;

[FigmaTag("MyTag")]
public class MyTagHandler : ITagHandler
{
    public void PostCreateGameObject(Node node, GameObject go, FileNode fileNode)
    {
        go.AddComponent<MyComponent>();
    }
}

只需将脚本放在 Editor 程序集中，无需注册——TypeCache 会自动发现所有带 [FigmaTag] 特性的类。

---

Bind 系统

Bind 系统允许在 Figma Plugin 数据中为节点设置 bindingKey，导入时自动将该节点上的组件赋值到父级 MonoBehaviour 的对应字段。

工作原理

FigmaBindProcessor（内置，默认启用）在 PostBuild 阶段遍历所有带 bindingKey 的节点，向上查找最近的带 [FigmaBindable] 特性的 MonoBehaviour，并将字段上 [FigmaBindKey("key")] 匹配的字段赋值为该节点对应类型的组件。

使用方法

using UnityEngine;
using UnityEngine.UI;

[FigmaBindable]
public class CraftPanel : MonoBehaviour
{
    [FigmaBindKey("CraftCommand")]
    public Button craftButton;

    [FigmaBindKey("ItemIcon")]
    public Image itemIcon;
}

在 Figma Plugin 中将对应节点的 bindingKey 设为 "CraftCommand" 或 "ItemIcon"，导入后字段会自动赋值，无需手动拖拽。

---

编辑 Override Nodes（实例替换）

Override Nodes 允许将 Figma 文件中的 Component Instance 替换为已导入的 Prefab，而非重新从节点数据构建。

工作原理

.fignode 文件被导入时，Inspector 的 Override Nodes 区域会自动列出该文件中所有的 Component（包括所属 ComponentSet）。每条记录包含：

字段	说明
name	组件名称（只读，来自 Figma）
componentId	Figma 节点 ID（只读）
prefab	要替换成的 Unity Prefab
componentSet.prefab	若该组件属于 ComponentSet，可单独指定整组使用的 Prefab

配置步骤

1. 先将子组件的 .fignode 文件单独导入，得到对应 Prefab。
2. 打开父级 .fignode 文件的 Inspector，在 Override Nodes 列表中找到对应条目。
3. 将子组件 Prefab 拖入 prefab 字段（或 componentSet.prefab 字段）。
4. 点击 Apply，所有引用该组件的 Instance 节点都会在导入时替换为指定 Prefab。

Tip

如果一个组件属于 ComponentSet（Variant 组），推荐填写 componentSet.prefab，这样同一组内所有 Variant 的 Instance 都使用同一个带 Animator 的 Prefab，由 Animator 驱动状态切换。