Grid

Usage

Loading demo...

Simple grid layout:

<template>
  <TxGrid :cols="3" gap="16">
    <TxGridItem>Item 1</TxGridItem>
    <TxGridItem>Item 2</TxGridItem>
    <TxGridItem>Item 3</TxGridItem>
    <TxGridItem>Item 4</TxGridItem>
    <TxGridItem>Item 5</TxGridItem>
    <TxGridItem>Item 6</TxGridItem>
  </TxGrid>
</template>

Best Practices

Prefer explicit cols for known dashboard grids and minItemWidth for card collections that should auto-fit available space.
Keep TxGridItem spans predictable; oversized spans should be paired with enough columns at every responsive breakpoint.
Use numeric gaps for token-like spacing and string gaps only when the layout needs CSS units such as rem or clamp().
Do not use Grid for semantic tables or ordered lists; keep data tables in table components and navigation in list markup.

API Reference

Grid Props

Name	Type	Default	Description
cols	`number \| Responsive<number>`	`0`	Columns; 0 leaves the column template unset
rows	`number`	`0`	Rows; 0 leaves the row template unset
gap	`GridGap`	`16`	Grid gap (number → px, `{ row, col }`, or responsive object)
minItemWidth	`string`	-	Min item width (auto-fit)
justify	`'start' \| 'end' \| 'center' \| 'stretch'`	`'stretch'`	Horizontal alignment
align	`'start' \| 'end' \| 'center' \| 'stretch'`	`'stretch'`	Vertical alignment

GridItem Props

Name	Type	Default	Description
colSpan	`number`	`1`	Column span, clamped to at least 1
rowSpan	`number`	`1`	Row span, clamped to at least 1
justifySelf	`'start' \| 'end' \| 'center' \| 'stretch'`	-	Item horizontal alignment
alignSelf	`'start' \| 'end' \| 'center' \| 'stretch'`	-	Item vertical alignment

Types

type Breakpoint = 'xs' | 'sm' | 'md' | 'lg' | 'xl'

type Responsive<T> = Partial<Record<Breakpoint, T>>

type GridAlign = 'start' | 'end' | 'center' | 'stretch'

type GridGap =
  | number
  | string
  | { row?: number | string, col?: number | string }
  | Responsive<number | string>

Events

Event	Payload	Description
-	-	`TxGrid` and `TxGridItem` do not emit component-specific events.

Slots

Component	Slot	Props	Description
`TxGrid`	`default`	-	Grid item content, normally `TxGridItem` children.
`TxGridItem`	`default`	-	Cell content rendered inside the grid item wrapper.

Responsive Grid

Responsive columns

<template>
  <TxGrid :cols="{ xs: 1, sm: 2, md: 3, lg: 4, xl: 5 }" gap="20">
    <TxGridItem v-for="i in 10" :key="i">
      <TxCard>Item {{ i }}</TxCard>
    </TxGridItem>
  </TxGrid>
</template>

Auto-fit grid

<template>
  <TxGrid min-item-width="250px" gap="24">
    <TxGridItem v-for="item in items" :key="item.id">
      <TxCard>
        <h3>{{ item.title }}</h3>
        <p>{{ item.description }}</p>
      </TxCard>
    </TxGridItem>
  </TxGrid>
</template>

Grid Gaps

gap accepts three forms: a number (uniform gap converted to px), { row, col } for separate row/column gaps, and a responsive object keyed by breakpoint.

<template>
  <!-- Uniform gap: number converted to px -->
  <TxGrid :cols="3" gap="32">
    <TxGridItem v-for="i in 6" :key="i">{{ i }}</TxGridItem>
  </TxGrid>

  <!-- Separate row / column gaps -->
  <TxGrid :cols="3" :gap="{ row: 24, col: 16 }">
    <TxGridItem v-for="i in 6" :key="i">{{ i }}</TxGridItem>
  </TxGrid>

  <!-- Responsive by breakpoint -->
  <TxGrid :cols="{ xs: 1, md: 2, lg: 3 }" :gap="{ xs: 16, md: 24, lg: 32 }">
    <TxGridItem v-for="i in 6" :key="i">{{ i }}</TxGridItem>
  </TxGrid>
</template>

Grid Items

Column span

<template>
  <TxGrid :cols="4" gap="16">
    <TxGridItem>Item</TxGridItem>
    <TxGridItem :col-span="2">Span 2</TxGridItem>
    <TxGridItem>Item</TxGridItem>
    <TxGridItem :col-span="3">Span 3</TxGridItem>
    <TxGridItem>Item</TxGridItem>
  </TxGrid>
</template>

Row span

<template>
  <TxGrid :cols="3" gap="16">
    <TxGridItem>Item 1</TxGridItem>
    <TxGridItem :row-span="2">Span 2 rows</TxGridItem>
    <TxGridItem>Item 3</TxGridItem>
    <TxGridItem>Item 4</TxGridItem>
    <TxGridItem>Item 5</TxGridItem>
  </TxGrid>
</template>

Alignment

Grid alignment

<template>
  <TxGrid
    :cols="3"
    gap="16"
    justify="center"
    align="center"
    style="height: 400px;"
  >
    <TxGridItem v-for="i in 3" :key="i">
      Item {{ i }}
    </TxGridItem>
  </TxGrid>
</template>

Item alignment

<template>
  <TxGrid :cols="3" gap="16">
    <TxGridItem justify-self="start">Start</TxGridItem>
    <TxGridItem justify-self="center">Center</TxGridItem>
    <TxGridItem justify-self="end">End</TxGridItem>
  </TxGrid>
</template>

Overview

minItemWidth takes precedence over cols and outputs repeat(auto-fit, minmax(..., 1fr)).
Responsive values are resolved from the current window width with breakpoints xs < 640, sm < 768, md < 1024, lg < 1280, and xl otherwise.
Numeric gap values are converted to px; { row, col } controls row and column gaps separately.
TxGridItem clamps colSpan and rowSpan to at least 1.

Technologies

Responsive contract: TxGrid resolves responsive cols and gap against window.innerWidth; SSR/default width starts at 1024, so critical first paint layouts should also work at the md fallback.
Sizing note: minItemWidth wins over explicit cols and emits repeat(auto-fit, minmax(..., 1fr)). Use one strategy per grid to avoid surprising reviewers.
Verified coverage: grid.test.ts covers fixed columns/rows/gaps, minItemWidth precedence, responsive resize updates, resize listener cleanup, TxGridItem span clamping, self alignment, and install registration.
Grid source: packages/tuffex/packages/components/src/grid/src/TxGrid.vue.
Grid item source: packages/tuffex/packages/components/src/grid/src/TxGridItem.vue.
Coverage: packages/tuffex/packages/components/src/grid/__tests__/grid.test.ts verifies fixed templates, responsive resolution, listener cleanup, and span clamping.

查看源码

packages/tuffex/packages/components/src/grid/index.ts