TechUI Docs

简中

EN

简中

EN

主题

网格布局 ​

⭐明星组件
👑首创
v0.0.4+

TuiGrid 是一个基于原生 CSS Grid 规范封装的高级二维布局容器。 它允许您通过简单的配置对象，精确控制每一行的高度、每一列的宽度，以及单元格的合并（跨行/跨列）行为。

核心概念 ​

在开始之前，了解 TuiGrid 的尺寸单位逻辑非常重要：

  • 数值 (Number): 会被转换为 fr 单位（倍数/剩余空间比例）。例如 size: 2 等同于 2fr。
  • 字符串 (String): 会被直接作为 CSS 值渲染。支持 px, %, auto, minmax() 等标准 CSS Grid 语法。

基础用法 倍数比例 ​

最简单的用法是使用数字来定义行列的比例。 在下例中，第 2 列 (size: 2) 的宽度是第 1、3 列的两倍，第 4 列 (size: 3) 是第 1 列的三倍。

html
<template>
  <TuiGrid 
    :rows="2" 
    :cols="4"
    :colConfig="[
      { size: 1 },    // 1fr
      { size: 2 },    // 2fr (两倍宽)
      { size: 1 },    // 1fr
      { size: 3 }     // 3fr (三倍宽)
    ]"
    :rowConfig="[
      { size: 1 },    // 1fr
      { size: 2 }     // 2fr (两倍高)
    ]"
  >
    <template #cell-0-0><div>1fr</div></template>
    <template #cell-0-1><div>2fr</div></template>
    <template #cell-0-2><div>1fr</div></template>
    <template #cell-0-3><div>3fr</div></template>
    <template #cell-1-0><div>Row 2</div></template>
  </TuiGrid>
</template>

固定尺寸与混合布局 ​

您可以自由混合固定像素 (px)、百分比 (%) 和自适应单位 (fr)。这在构建“固定侧边栏 + 自适应内容区”的经典布局时非常有用。

html
<template>
  <TuiGrid 
    :rows="3" 
    :cols="3"
    :colConfig="[
      { size: '200px' },   // 固定左侧栏
      { size: 1 },         // 中间自适应
      { size: '20%' }      // 右侧占总宽 20%
    ]"
    :rowConfig="[
      { size: '60px' },    // 固定头部
      { size: 1 },         // 内容区自适应撑满
      { size: '40px' }     // 固定底部
    ]"
  >
    <template #cell-0-0><div>Header Left</div></template>
    <template #cell-0-1><div>Header Main</div></template>
    </TuiGrid>
</template>

单元格合并 ​

通过 cellConfig 属性，您可以指定任意单元格跨越的行数 (rowSpan) 或列数 (colSpan)。 配置的 Key 为坐标字符串 '行索引-列索引'。

提示

当一个单元格跨越了位置时，被覆盖的那些单元格位置仍然存在于逻辑中，但通常不需要为其填充内容（或通过 hidden: true 显式隐藏）。

html
<template>
  <TuiGrid 
    :rows="4" :cols="4" :gap="20"
    :cellConfig="{
      '0-0': { colSpan: 4, className: 'header-cell' },             // 头部：跨4列
      '1-0': { rowSpan: 2, colSpan: 2 },                           // 主图表：跨2行2列
      '3-0': { colSpan: 4 }                                        // 底部：跨4列
    }"
  >
    <template #cell-0-0>
      <div class="header">数据大屏标题</div>
    </template>

    <template #cell-1-0>
      <div class="big-chart">主图表区域</div>
    </template>

    <template #cell-1-2><div>图表 A</div></template>
    <template #cell-1-3><div>图表 B</div></template>
    
    <template #cell-3-0><div>Footer Info</div></template>
  </TuiGrid>
</template>

高级 CSS 函数 ​

TuiGrid 完美支持 CSS Grid 的高级函数，如 minmax() 和 auto，这使得创建响应式且健壮的布局成为可能。

  • auto: 根据内容自动调整尺寸。
  • minmax(min, max): 尺寸在最小值和最大值之间弹性变化。
html
<template>
  <TuiGrid 
    :rows="1" :cols="3"
    :colConfig="[
      { size: 'auto' },                    // 宽度由内容撑开
      { size: 'minmax(200px, 1fr)' },      // 最小200px，空间足够时占满剩余
      { size: 'minmax(100px, 300px)' }     // 在 100px 到 300px 之间伸缩
    ]"
  >
    <template #cell-0-0>
      <div>一段很长的不换行文本会撑宽此列</div>
    </template>
    </TuiGrid>
</template>

CSS变量 ​

CSS 变量 ​

Grid 组件暴露了一组 CSS 变量，允许您从父级轻松控制内部单元格的默认样式。

css
.my-grid-container {
  /* 修改单元格默认背景色 */
  --tui-grid-item-bg: var(--common-bg_layer);
  
  /* 修改单元格边框 */
  --tui-grid-item-bd: 1px solid rgba(255,255,255,0.1);
  
  /* 修改单元格内边距 */
  --tui-grid-item-pd: 20px;
}

自定义类名 ​

在 cellConfig 中，您可以为特定单元格添加 className，以便进行特殊的样式覆盖（如背景色、对齐方式等）。

javascript
const cellConfig = {
  '0-0': { colSpan: 4, className: 'dashboard-header-style' }
}

单元格样式类 ​

TuiGrid 会自动为每个渲染的单元格附加一组 CSS 类名。这使得您既可以通过坐标直接定位单元格，也可以通过注入自定义语义类名来复用样式。

每个单元格的 class 列表由以下三部分组成：

  1. 基础标识: tui-grid-item 所有 TuiGrid 单元格默认拥有的基础类名。
  2. 坐标标识: tui-cell-{row}-{col} 组件根据当前单元格的行列索引自动生成的唯一标识。
    • 索引从 0 开始。
    • 例如：第 1 行第 1 列为 .tui-cell-0-0，第 2 行第 3 列为 .tui-cell-1-2。
    • 应用场景: 当您不想修改 JS 配置，只想快速通过 CSS 覆盖某个固定位置（如左上角）的样式时非常有用。
  3. 自定义标识: className 通过 cellConfig 配置项注入的自定义类名。
    • 应用场景: 用于语义化样式管理（如 .header-cell, .active-card）。

渲染示例 ​

假设您进行了如下配置：

javascript
const cellConfig = {
  // 为位置 0-0 的单元格添加自定义类名
  '0-0': { colSpan: 4, className: 'dashboard-header' }
}

最终渲染出的 HTML 结构将类似于：

html
<div class="tui-grid-item tui-cell-0-0 dashboard-header" ...>
  </div>

<div class="tui-grid-item tui-cell-0-1" ...>
  ...
</div>

样式编写技巧 ​

利用这些类名，您可以灵活地编写样式：

css
/* 1. 全局修改所有单元格 */
.tui-grid-item {
  transition: all 0.3s;
}

/* 2. 精确命中：修改第 2 行第 3 列的背景 */
.tui-cell-1-2 {
  background-color: #f5f5f5;
}

/* 3. 语义命中：修改所有头部单元格 */
.dashboard-header {
  font-weight: bold;
  border-bottom: 2px solid blue;
}

API 参考 ​

Props ​

属性名类型默认值说明
rowsNumber3网格行数。
colsNumber3网格列数。
gapNumber/String-网格间距。数字会被转为 px。
rowConfigArray[]行高配置数组。对象格式 { size: Number/String }。
colConfigArray[]列宽配置数组。对象格式 { size: Number/String }。
cellConfigObject{}单元格配置表。Key 为 'rowIndex-colIndex'。

Cell Configuration Object ​

cellConfig 中的对象支持以下属性：

属性名类型说明
rowSpanNumber单元格跨越的行数。
colSpanNumber单元格跨越的列数。
hiddenBoolean是否隐藏该单元格 (通常用于被合并覆盖的单元格)。
classNameString为该单元格添加自定义 CSS 类名。

Slots ​

插槽名称是动态生成的，格式为：cell-{rowIndex}-{colIndex}。

  • 索引从 0 开始。
  • 例如：第 1 行第 1 列为 cell-0-0，第 2 行第 3 列为 cell-1-2。

CSS Variables ​

变量名默认值说明
--tui-grid-item-bgvar(--common-bg)单元格背景颜色。
--tui-grid-item-bdvar(--common-bd)单元格边框样式。
--tui-grid-item-pd10px单元格内边距。
--tui-grid-w100%网格容器宽度。
--tui-grid-h100%网格容器高度。