---
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 媒体查询覆盖。