---
title: Space 间距
description: 为一组内联元素设置统一间距，并支持插入分隔符
---

# Space 间距

`Space` 给一组子元素之间加统一间距，省去给每个元素写 `margin` 的麻烦。

**Space 与 Grid 的分工**：`Space` 面向「一行内联元素的等距排列」（按钮行、标签行、操作区），会给每个子元素包一层包装以支持分隔符与空节点隐藏；整块页面布局请用 [Grid 栅格](/ui/general/grid)。

## 何时使用

- 一排按钮 / 标签 / 文字之间需要统一间距时；
- 需要在元素之间插入分隔符（`|`、`·`）时；
- 子元素数量不确定、其中有条件渲染的节点时（空节点不会占位）。

## 基础用法

默认水平排列、间距 `small`（8px）、交叉轴居中对齐。

<demo vue="space/basic.vue" />

## 间距大小

`size` 支持三种写法：预设名 `small` / `middle` / `large`、数字（按 px 处理）、以及 `[水平, 垂直]` 数组。

<demo vue="space/size.vue" />

| 写法 | 效果 |
| --- | --- |
| `size="small"` | 8px |
| `size="middle"` | 16px（默认档，常用于行内） |
| `size="large"` | 24px |
| `:size="12"` | 12px |
| `:size="[16, 8]"` | 列间距 16px、行间距 8px（配合 `wrap` 用） |

## 纵向排列

`vertical` 是简写；`orientation` 与它同时配置时，以 `orientation` 优先（这样上层组件透传 `orientation` 时不会被 `vertical` 覆盖）。

<demo vue="space/vertical.vue" />

## 分隔符

`#separator` 插槽会在相邻子元素之间插入内容，**不会**在首尾添加。

<demo vue="space/separator.vue" />

## 自动换行

`wrap` 只在水平方向生效；配合 `[水平, 垂直]` 形式的 `size` 可以分别控制列间距与行间距。

<demo vue="space/wrap.vue" />

## 空节点不占位

`v-if` 关闭的节点、注释节点不会被计入间距，因此条件渲染不会留下空隙。

<demo vue="space/empty-children.vue" />

## API

### Props

| 名称 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `size` | `'small' \| 'middle' \| 'large' \| number \| string \| [SpaceSize, SpaceSize]` | `'small'` | 间距。数组按 `[水平, 垂直]` 解析；数字按 px；其他字符串原样透传给 `column-gap` / `row-gap` |
| `orientation` | `'horizontal' \| 'vertical'` | 由 `vertical` 决定 | 排列方向。优先级高于 `vertical` |
| `vertical` | `boolean` | `false` | 纵向排列的简写 |
| `align` | `'start' \| 'end' \| 'center' \| 'baseline'` | 水平方向 `'center'`，纵向不设置 | 交叉轴对齐（`align-items`） |
| `wrap` | `boolean` | `false` | 是否自动换行，仅水平方向生效 |

### Slots

| 名称 | 参数 | 说明 |
| --- | --- | --- |
| `default` | — | 间距容器内的元素。每个有效子节点会被包一层 `g3-space__item` |
| `separator` | — | 相邻元素之间插入的分隔内容 |

### 类型定义

```ts
export type SpaceSize = 'small' | 'middle' | 'large' | number | string
export type SpaceOrientation = 'horizontal' | 'vertical'
export type SpaceAlign = 'start' | 'end' | 'center' | 'baseline'

export interface SpaceProps {
  size?: SpaceSize | [SpaceSize, SpaceSize]
  orientation?: SpaceOrientation
  vertical?: boolean
  align?: SpaceAlign
  wrap?: boolean
}
```

## 实现说明

- 间距用 CSS 的 `gap` 实现（`column-gap` / `row-gap`），因此**不依赖子元素是否有 margin**，也不会出现「相邻 margin 合并」的问题；
- 子元素会被包一层 `inline-flex` 的 `g3-space__item`，这让分隔符有落点，同时过滤掉注释 / 文本空节点；
- 纵向排列时默认不设置 `align`（即 `stretch`），这样「撑满宽度」的按钮才不会被压成内容宽度；需要居中时显式传 `align="center"`。