---
title: Container 容器
description: 限定宽度与留白的容器及 24 列栅格
category: Layout
status: beta
since: 0.3.4
tags: [container, layout, grid]
syncStatus: reviewed
verified: true
---

## 用法

:::TuffCodeBlock{lang="vue"}
---
code: |
  <template>
    <TxContainer>
      <p>这是容器内的内容</p>
    </TxContainer>
  </template>
---
:::

### 基础
`TxContainer` 负责最大宽度与左右留白，`TxRow` / `TxCol` 按断点切换列宽。
:::TuffDemoWrapper{demo="ContainerContainerDemo" code-lang="vue"}
---
code: |
  <template>
    <TxContainer max-width="680px" :padding="18">
      <TxRow :gutter="{ xs: 10, sm: 14, md: 18 }" align="stretch">
        <TxCol :xs="24" :sm="12" :md="8">概览</TxCol>
        <TxCol :xs="24" :sm="12" :md="8">指标</TxCol>
        <TxCol :xs="24" :sm="24" :md="8">操作</TxCol>
      </TxRow>
    </TxContainer>
  </template>
---
:::

### 宽度
`fluid` 填满父容器，`maxWidth` 限定最大宽度，`responsive` 按断点切换最大宽度。
:::TuffCodeBlock{lang="vue"}
---
code: |
  <template>
    <TxContainer fluid>流体容器，宽度 100%</TxContainer>
    <TxContainer max-width="1200px">最大宽度 1200px</TxContainer>
    <TxContainer responsive>响应式容器</TxContainer>
  </template>
---
:::

### 间距
:::TuffCodeBlock{lang="vue"}
---
code: |
  <template>
    <TxContainer padding="small">小间距</TxContainer>
    <TxContainer padding="large">大间距</TxContainer>
    <TxContainer :padding="32">自定义间距</TxContainer>
    <TxContainer margin="auto">水平居中</TxContainer>
  </template>
---
:::

### 栅格
:::TuffCodeBlock{lang="vue"}
---
code: |
  <template>
    <TxRow>
      <TxCol :span="12">左侧内容</TxCol>
      <TxCol :span="12">右侧内容</TxCol>
    </TxRow>

    <TxRow :gutter="{ xs: 8, sm: 16, md: 24, lg: 32 }">
      <TxCol v-for="n in 4" :key="n" :xs="24" :sm="12" :md="8" :lg="6">
        响应式列 {{ n }}
      </TxCol>
    </TxRow>
  </template>
---
:::

### 最佳实践

- 每个页面区块只用一个 `TxContainer`；多层嵌套会让宽度与留白难以判断。
- 用 `xs`–`xl` 切换布局，不要为不同断点复制多份 DOM。
- `gutter` 与页面间距尺度保持一致，不要在同一行混用过大的 gutter 与过小的列内边距。
- 三个组件都渲染中性 `div`，语义元素（`main`、`aside`、`nav`、`section`）放在其内部。
- 只有横向滚动或固定宽度的工具栏才设 `wrap=false`。

## API 参考

### TxContainer

#### 属性

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| fluid | `boolean` | `false` | 取消最大宽度，填满父容器。 |
| maxWidth | `string` | `'1200px'` | 最大宽度。 |
| responsive | `boolean` | `false` | 按断点切换最大宽度：640 / 768 / 1024 / 1280px。 |
| padding | `'small' \| 'medium' \| 'large' \| number` | `'medium'` | 左右内边距：预设 12 / 16 / 24px，或不小于 0 的像素值。 |
| margin | `'auto' \| string \| number` | `'auto'` | 左右外边距；`auto` 居中，其他值按 `0 <value>` 应用。 |

#### 插槽

| 插槽 | 参数 | 说明 |
|------|------|------|
| `default` | - | 受最大宽度与留白约束的内容。 |

### TxRow

#### 属性

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| gutter | `number \| Partial<Record<'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl', number>>` | `0` | 列间距（px），可按断点设置。 |
| align | `'top' \| 'middle' \| 'bottom' \| 'stretch'` | `'stretch'` | 列的垂直对齐。 |
| justify | `'start' \| 'end' \| 'center' \| 'space-around' \| 'space-between' \| 'space-evenly'` | `'start'` | 列的水平分布。 |
| wrap | `boolean` | `true` | 允许换行。 |

#### 插槽

| 插槽 | 参数 | 说明 |
|------|------|------|
| `default` | - | `TxCol` 或其他 flex 子项。 |

### TxCol

#### 属性

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| span | `number` | `24` | 占据的列数（共 24 列）。 |
| offset | `number` | `0` | 左侧偏移的列数。 |
| xs | `number` | - | xs 断点（< 640px）的列数。 |
| sm | `number` | - | sm 断点（≥ 640px）的列数。 |
| md | `number` | - | md 断点（≥ 768px）的列数。 |
| lg | `number` | - | lg 断点（≥ 1024px）的列数。 |
| xl | `number` | - | xl 断点（≥ 1280px）的列数。 |

#### 插槽

| 插槽 | 参数 | 说明 |
|------|------|------|
| `default` | - | 列内容。 |

## 概述

- 断点值向上沿用：当前断点未设置时取更小断点的值；都未设置时，`TxCol` 用 `span`，`TxRow` 用 `0`。
- `TxRow` 把当前 gutter 写入 `--tx-row-gutter`，每列取一半作为左右内边距，行用负外边距抵消首尾两侧。
- `span` 与 `offset` 收敛到 0–24。

## 技术实现

- 断点按 `window.innerWidth` 计算并随 `resize` 更新，与容器自身宽度无关。
- 行宽为 `calc(100% + var(--tx-row-gutter))`，配合负外边距让首尾列与容器内边距对齐。
- 源码：`packages/tuffex/packages/components/src/container/`。

<TuffDocSourceLink />

## 自定义

| 变量 | 写入方 | 用途 |
|------|--------|------|
| `--tx-container-max-width` | `maxWidth` / `fluid` | 最大宽度。 |
| `--tx-container-padding` | `padding` | 左右内边距。 |
| `--tx-row-gutter` | `gutter` | 列间距。 |

三个变量由 props 写入根节点内联样式，请通过 props 调整。