变体

变体允许你把按钮、图标或开关等相似组件分组为一个可自定义组件。你不必为每种状态、尺寸或样式在单独组件之间导航，而是可以通过明确定义的属性，在一个统一组件中管理它们。

想象一个按钮组件，可以在 primary 和 secondary 样式、active 和 disabled 状态、小尺寸和大尺寸之间切换。这就是变体的能力。

为什么变体重要？

• 更清晰的库：在设计视口、图层面板和交换菜单中保持相关设计有序。变体会把组件整理为整洁、可管理的集合，并允许你在切换时保留覆盖。
• 更快的设计工作流：通过简单属性控件快速在状态或样式之间切换，更容易查找并选择正确版本。
• 更好的团队协作：变体可以匹配代码中处理状态的方式，帮助设计师和开发人员保持同步。

(视频略)

理解变体：属性和值

组件变体由属性及其值组织。

• 属性定义区分变体的维度，例如 Color、Size、State。
• 值是属性中的具体选项，例如 Primary/Secondary、Small/Large、Default/Hover/Pressed。

每个变体都是所有属性值的唯一组合，例如 Color=Primary + Size=Small + State=Hover。

变体至少需要一个属性，并且属性值应保持一致，以便切换可预测，并在连接图层之间保留覆盖。

创建和修改变体

创建变体

可以从现有组件或另一个变体创建变体：

• 从组件：按 Ctrl + K，或右键并选择 Create variant。
• 从变体：选择变体并按 Ctrl + K，或右键并选择 Create variant。
• 通过拖动：把主组件拖入已有变体组件中，将其添加为新变体。
• 从 Design 标签：选择组件或变体，打开组件名称旁的上下文菜单并选择 Create variant。

创建变体后：

• 它会出现在原始组件旁边的专用变体区域中，默认使用水平 flex 布局。
• 变体之间的共享图层会自动连接，以便保留覆盖。
• 变体会使用其属性值命名，例如 Primary / Hover。

管理变体属性

属性是定义和区分变体的关键。当选择变体或带变体组件时，它们会显示在 Design 标签中。

添加新属性

• 从 Design 标签：选择组件或其某个变体后，可通过菜单添加新属性。该属性会以默认值添加到所有现有变体中。
• 从图层面板：使用公式 [property_name]=[value]。

编辑属性

• 从 Design 标签：选择组件或变体，然后点击属性名称编辑其名称和/或值。
• 从图层面板：使用公式 [property_name]=[value]。

删除属性

• 从 Design 标签：选择主组件（不是单个变体），按属性旁边的减号按钮。
• 从图层面板：通过编辑所有变体名称，使它们的公式中不再包含该属性。

变体至少必须有一个属性，不能删除最后一个属性。

选择多个变体时，Design 标签会显示它们的所有属性和值。如果某个属性在所选变体中具有不同值，会显示 “Mixed”，允许你统一覆盖它们。

删除变体

• 选择变体，右键并选择 Delete。
• 把变体拖出组件，会将其转为独立组件，而不是删除它。

如果删除最后一个变体，整个组件会被移除。

恢复变体

如果你有某个原始变体已删除的副本，可以恢复它：

• 选择变体副本，右键并选择 Restore variant（如果主组件仍存在，该选项会显示）。

布尔变体的切换开关

当变体属性表示布尔状态时，Penpot 可以将其显示为切换开关，而不是下拉列表。这在处理副本时可更快、更直观地在两个相反值之间切换。

切换开关只会在选择副本时替代属性值下拉列表出现。

接受的值对

为了让 Penpot 识别属性为布尔值并显示切换开关，该属性必须正好定义两个相反值。可使用以下任意值对：

• true / false
• on / off
• yes / no

值的顺序不重要。Penpot 会自动映射到 ON 和 OFF 状态：

• ON 状态：true、yes、on
• OFF 状态：false、no、off

使用变体

创建变体后，可以把带变体组件的副本放入设计中，并在不同版本之间切换。

从 Assets 标签

像拖动任何其他组件一样，把带变体组件从 Assets 标签拖放到设计视口。放置后，可以在 Design 标签中使用其属性切换到所需变体。

从 Design 标签

选择变体时：

• 你会看到其属性和值。
• 更改一个或多个属性值，即可切换到另一个变体。
• 如果所选组合不存在，Penpot 会建议最接近的匹配。

理解覆盖

变体的关键优势之一，是在切换时保留覆盖。覆盖是你对组件实例所做的、偏离原始定义的特定更改，例如更改文本内容或特定颜色。

变体之间的图层满足以下条件时会被视为已连接：

1. 名称相同。
2. 类型相同。矩形、椭圆、路径和布尔运算视为同一类型。
3. 具有相同层级。组、画板和布局被视为等效。

示例：如果 Variant 1 有一个名为 label 且颜色为红色的文本图层，你在实例中把其内容改为 Click here，然后切换到也具有 label 文本图层的 Variant 2，Click here 内容会保留，同时应用 Variant 2 的颜色。

更改这些条件中的任意一项（例如重命名或对图层编组）都会断开连接；恢复该更改会重新建立连接。

批量将组件转换为变体

如果已有多个相关组件，可以把它们合并为一个带变体组件：

• 从 Assets 标签：选择同一组中的组件，右键 → Combine as variants。
• 从视口：选择多个组件 → 右键 → Combine as variants。
• 从 Design 标签：如果满足条件，组件卡片上会出现 Combine as variants 按钮。

条件：

• 组件必须在同一页面上。
• 已经具有变体的组件不能被合并。

合并后：

• 会创建包含所有原组件的变体区域。
• 属性名称和值会根据组件名称生成。

将变体转换回组件

要把变体转为独立组件：

• 将其拖出变体区域（设计视口或图层面板）。
• 剪切并粘贴到变体区域之外。

新组件的名称会包含原组件名称和该变体的属性值。