---
title: "组件与变量 | Kalka docs"
description: "带有变体和属性的可复用组件，包含集合与模式的变量页面，以及变量如何变成 CSS 自定义属性和设计令牌。"
url: https://kalka.design/zh/docs/components-variables
language: zh-Hans
---

## 组件

组件是可以重复使用的设计：按钮、卡片、导航栏。它的副本叫作实例，会跟随组件变化。修改组件，所有实例都会随之改变，实例中覆盖过的部分除外。

- **创建组件：** 选中图层，按 Cmd Alt K（Ctrl Alt K）。

- **创建实例：** 从 **资源** 面板把组件拖到画布上，或使用其中的 **插入实例**。

- **转到主组件** 从实例跳转到它的组件。

- **分离实例**（Cmd Alt B，Ctrl Alt B）把实例还原为普通图层。

**资源** 面板以网格或列表列出文档中的组件，并支持搜索。

## 变体

变体是同一个组件的不同版本，比如一个按钮有主要和次要、小号和大号之分。选中多个组件，使用 **创建组件集**（Shift Cmd K，Ctrl Shift K），然后添加变体属性及其取值。每个变体的取值组合必须唯一。在实例上，可以从设计面板切换变体。

## 组件属性

除了变体，组件还可以公开：

- **文本** 属性，用于在每个实例上修改标签文字；

- **布尔值** 属性，用于显示或隐藏某个部分；

- **实例切换** 属性，用于替换嵌套的组件，比如图标；

- **插槽**，每个实例都可以在其中放入自己的图层，并可限制数量。

在设计面板中使用 **创建属性…** 创建，或者在某个字段上使用 **将组件属性应用到** 该字段。实例会在设计面板顶部显示这些属性。

## 行为

组件可以像真实控件一样工作：开关、复选框、滑块、标签页、文本框、手风琴、带有悬停、按下、聚焦和禁用状态的按钮等。在组件的 **行为** 部分中选择。随后，**视图 › 预览**（Cmd Alt Enter）会让这些控件真正运行：你可以在文本框里输入、拖动滑块、展开手风琴，也可以用键盘操作。试用期间文档不会有任何改动；按 Esc 返回编辑。

## 库

要在文档之间共享组件，先用 **发布库** 把一个文档发布为库，再在另一个文档中通过 **管理库** 启用它。库有变化时，**查看库更新** 会在你更新之前展示改动，可以并排对比，也可以叠加对比。

## 变量

变量是可复用的命名值：品牌色、间距、字号、标签文字。修改变量，所有用到它的图层都会随之改变。

### 打开变量页面

点击左侧栏中的 **变量**。在桌面编辑器中，变量页面会覆盖在面板和画布之上。再次点击 **变量**、选择其他面板或按 Esc，画布就会恢复原样。也可以通过 **视图 › 变量…**，或在未选中任何内容时点击设计面板中的 **打开变量** 来打开。在手机屏幕上，它以对话框形式打开。

_打开 Tokens 集合的变量页面：颜色、间距和圆角变量，带有浅色和深色取值及 CSS 名称，下方是生成的样式表_

变量页面：每个变量的 CSS 名称和每个模式下的取值，以及 Kalka 生成的样式表。

### 类型

| 类型 | 用于 |
| --- | --- |
| 颜色 | 填充、描边、阴影颜色 |
| 数字 | 尺寸、间距、圆角、不透明度、字号 |
| 文本 | 标签、文案、字体系列 |
| 布尔值 | 真或假，比如是否显示某个图层 |

变量可以通过 **范围** 限定在某些字段中使用，这样间距变量就不会出现在颜色列表里。它的 **CSS 表达式** 可以让它在代码中保存类似 `clamp(1rem, 4vw, 1.5rem)` 的值。

### 集合与模式

变量存放在 **集合** 中，比如 Colors 或 Spacing，并可以分组整理。集合可以有多个 **模式**：浅色和深色、紧凑和宽松、每个品牌一个。每个变量在每个模式下都有一个取值。

每个模式都规定了它在导出的 CSS 中何时生效：

- 手动切换，使用 `data-theme` 之类的属性；

- 系统处于深色或浅色模式时；

- 开启高对比度或减弱动态效果时；

- 屏幕宽度或容器宽度低于或高于某个值时；

- 或者在你编写的任意 CSS 选择器或 `@media`、`@supports`、`@container` 查询下。

### 使用变量

点击字段旁的 **使用变量**，从小列表中选择一个；悬停在颜色或数字变量上，会在画布上预览效果。**解除变量绑定** 会把它改回普通值。对于已经设置好的值，**从该值创建颜色变量** 或 **从该值创建数字变量** 可以一步把它变成变量。

## 代码中的变量

变量就是 CSS 自定义属性。每个集合的默认模式写在 `:root` 中，其他模式只在各自的条件下覆盖不同的值。名为 `Gray/50` 的变量会变成 `--color-gray-50`，`Space/small` 会变成 `--spacing-small`；你也可以自己设置 CSS 名称。

在变量页面中，你可以：

- **将所有变量复制为 CSS**，或 **将所有变量复制为 Tailwind 主题**（`@theme`）；

- **导出为设计令牌：** W3C 设计令牌的 `.zip`，每个集合模式一个文件；

- **导入设计令牌**：从 `.json`、`.tokens` 或 `.zip` 文件导入。同名变量会被更新，不会删除任何内容。

在 Kalka 文件夹中，变量以 W3C 设计令牌的形式保存在 `design-system/tokens.json`，并以 CSS 形式保存在 `design-system/tokens.css`。参见[文件与版本](https://kalka.design/zh/docs/files-versions)。
