u

2026-10-09 17:32:14 +08:00
1 parent e99a9fb274
commit 0be0b0767a
@@ -0,0 +1,117 @@
+---
+title: Grid 栅格
+description: 24 栅格布局，支持间距、偏移、位移与 flex 自适应
+---
+
+# Grid 栅格
+
+栅格把一行分成 24 等份，用 `G3Row` 表示行、`G3Col` 表示列。它适合页面级 / 表单级的块状布局；元素之间的等距排列（按钮行、标签行）请用 [Space](/ui/general/space)。
+
+## 何时使用
+
+- 卡片、表单项、图表块的成行排布；
+- 需要按比例分配宽度（12 / 6 / 8 …）或「一侧固定、一侧自适应」时；
+- 需要控制主轴分布（居中、两端对齐）与交叉轴对齐时。
+
+## 基础用法
+
+`span` 表示占多少格（0-24）；一行内累计超过 24 会自动换行。
+
+<demo vue="grid/basic.vue" />
+
+## 间距
+
+`gutter` 传数字表示水平与垂直同值，传 `[水平, 垂直]` 可分别控制。栅格间距用 `gap` 实现，子列不再需要自己写 margin。
+
+<demo vue="grid/gutter.vue" />
+
+## 偏移与位移
+
+- `offset`：左侧留空格（不参与排序，位置固定）；
+- `push` / `pull`：左右位移，常用于调整视觉顺序；
+- `order`：flex 的排序值，最小排在最前。
+
+<demo vue="grid/offset.vue" />
+
+## 对齐与分布
+
+`align` 控制交叉轴（`align-items`），`justify` 控制主轴分布（`justify-content`）。需要行内有高度差时给 `Row` 一个固定高度。
+
+<demo vue="grid/align.vue" />
+
+## flex 自适应
+
+`flex` 传数字表示 `flex-grow` 的份数，传字符串则作为完整的 `flex` 简写使用。
+
+<demo vue="grid/flex.vue" />
+
+## 不换行
+
+`wrap=false` 时列不会换行，超出 24 格的部分会被压缩，适合「横向铺满、不允许折行」的工具条。
+
+<demo vue="grid/no-wrap.vue" />
+
+## API
+
+### Props（Row）
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `gutter` | `number \| [number, number]` | `0` | 栅格间距（px）。数组为 `[水平, 垂直]` |
+| `align` | `'top' \| 'middle' \| 'bottom' \| 'stretch'` | `'top'` | 交叉轴对齐（`align-items`） |
+| `justify` | `'start' \| 'end' \| 'center' \| 'space-around' \| 'space-between' \| 'space-evenly'` | `'start'` | 主轴分布（`justify-content`） |
+| `wrap` | `boolean` | `true` | 是否换行（`flex-wrap`） |
+
+### Props（Col）
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `span` | `number \| string` | — | 占位格数 0-24。不传时按 `flex` 或内容宽度 |
+| `offset` | `number \| string` | `0` | 左侧偏移格数 |
+| `order` | `number \| string` | — | 排序值（`order`） |
+| `push` | `number \| string` | `0` | 向右移动格数 |
+| `pull` | `number \| string` | `0` | 向左移动格数 |
+| `flex` | `number \| string` | — | 数字按 `flex: n n auto` 处理；字符串作为完整 `flex` 简写，如 `'0 0 200px'` |
+
+### Slots
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `default` | — | `Row` 内放 `Col`；`Col` 内放任意内容 |
+
+### 类型定义
+
+```ts
+export type GridGutter = number | [number, number]
+export type RowAlign = 'top' | 'middle' | 'bottom' | 'stretch'
+export type RowJustify =
+  | 'start'
+  | 'end'
+  | 'center'
+  | 'space-around'
+  | 'space-between'
+  | 'space-evenly'
+
+export interface RowProps {
+  gutter?: GridGutter
+  align?: RowAlign
+  justify?: RowJustify
+  wrap?: boolean
+}
+
+export interface ColProps {
+  span?: number | string
+  offset?: number | string
+  order?: number | string
+  push?: number | string
+  pull?: number | string
+  flex?: number | string
+}
+```
+
+## 实现说明
+
+- 栅格基于 flex：`Row` 是 `display: flex` + `flex-wrap`，`Col` 通过 `flex-basis: span/24 * 100%` 占位；
+- 水平间距在 `Row` 上用负 margin + `Col` 上的 padding 抵消（首尾不外扩）；垂直间距由 `row-gap` 承担；
+- `Col` 的 `span`、`offset`、`push` / `pull` / `order` 都支持字符串，便于上层做动态计算（如设计器里按栅格配置渲染）；
+- 不做 `xs / sm / md` 断点：本库面向中后台工具，布局由容器宽度（如 `Space` / `Splitter`）控制，需要响应式时请在业务层用 CSS 媒体查询覆盖。