u

code/g3soft-libs/docs/content/ui/2.general/space.md

@@ -0,0 +1,107 @@
+---
+title: Space 间距
+description: 为一组内联元素设置统一间距，并支持插入分隔符
+---
+
+# Space 间距
+
+`Space` 给一组子元素之间加统一间距，省去给每个元素写 `margin` 的麻烦。
+
+**Space 与 Grid 的分工**：`Space` 面向「一行内联元素的等距排列」（按钮行、标签行、操作区），会给每个子元素包一层包装以支持分隔符与空节点隐藏；整块页面布局请用 [Grid 栅格](/ui/general/grid)。
+
+## 何时使用
+
+- 一排按钮 / 标签 / 文字之间需要统一间距时；
+- 需要在元素之间插入分隔符（`|`、`·`）时；
+- 子元素数量不确定、其中有条件渲染的节点时（空节点不会占位）。
+
+## 基础用法
+
+默认水平排列、间距 `small`（8px）、交叉轴居中对齐。
+
+:::demo{name="space/basic"}
+:::
+
+## 间距大小
+
+`size` 支持三种写法：预设名 `small` / `middle` / `large`、数字（按 px 处理）、以及 `[水平, 垂直]` 数组。
+
+:::demo{name="space/size"}
+:::
+
+| 写法 | 效果 |
+| --- | --- |
+| `size="small"` | 8px |
+| `size="middle"` | 16px（默认档，常用于行内） |
+| `size="large"` | 24px |
+| `:size="12"` | 12px |
+| `:size="[16, 8]"` | 列间距 16px、行间距 8px（配合 `wrap` 用） |
+
+## 纵向排列
+
+`vertical` 是简写；`orientation` 与它同时配置时，以 `orientation` 优先（这样上层组件透传 `orientation` 时不会被 `vertical` 覆盖）。
+
+:::demo{name="space/vertical"}
+:::
+
+## 分隔符
+
+`#separator` 插槽会在相邻子元素之间插入内容，**不会**在首尾添加。
+
+:::demo{name="space/separator"}
+:::
+
+## 自动换行
+
+`wrap` 只在水平方向生效；配合 `[水平, 垂直]` 形式的 `size` 可以分别控制列间距与行间距。
+
+:::demo{name="space/wrap"}
+:::
+
+## 空节点不占位
+
+`v-if` 关闭的节点、注释节点不会被计入间距，因此条件渲染不会留下空隙。
+
+:::demo{name="space/empty-children"}
+:::
+
+## 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"`。