# 网格 · Grid

- 页面: https://jiguang132.com/zh/resources/astryx/docs/grid
- 资源: Astryx (https://jiguang132.com/zh/resources/astryx.md)
- 全部指南: https://jiguang132.com/zh/resources/astryx/docs.md

网格用于布局场景。下面的官方示例展示原生用法与状态，属性名保持上游 API。

## 安装与前置条件

```bash
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0
```

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见[开始使用](/resources/astryx/docs/getting-started)。

## 示例与使用方式

- **网格 · 综合展示 1**：首先体验这个示例，再查看代码理解组件的组合方式。
- **网格 · 综合展示 2**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **网格 · 交互示例 3**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **网格 · 交互示例 4**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **网格 · 响应式布局 5**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **网格 · 交互示例 6**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **网格 · 交互示例 7**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

## API 与上游详细参考

优先使用 0.7.1 官方中文说明；上游尚未提供中文的条目保留英文。属性名、类型及默认值保持原生 API，不把示例状态名称当成组件属性。

## Grid

A CSS grid layout container for arranging children in rows and columns. Use Grid for card galleries, dashboards, and any multi-column layout. For columns that reflow on small screens, use `columns={{minWidth, max}}`; a numeric `columns` is exactly N columns at every width and never reflows.

| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| columns | number \| {minWidth: number, max?: number, repeat?: 'fill' \| 'fit'} |  | Column configuration. A number is exactly N equal columns at every width and never reflows (e.g. `columns={3}`); for columns that reflow on small screens, use `{minWidth, max}`. Use an object for responsive columns: `minWidth` sets the minimum column width in px, `repeat` controls track behavior (`"fill"` preserves empty tracks for consistent widths, `"fit"` collapses empty tracks so items stretch; defaults to `"fill"`), and `max` caps the maximum number of columns. |
| width | SizeValue |  | Container width. Numbers are treated as pixels, strings are used as-is. |
| height | SizeValue |  | Container height. Numbers are treated as pixels, strings are used as-is. |
| maxWidth | SizeValue |  | Maximum container width. Numbers are treated as pixels, strings are used as-is. |
| minHeight | SizeValue |  | Minimum container height. Numbers are treated as pixels, strings are used as-is. |
| gap | 0 \| 0.5 \| 1 \| 1.5 \| 2 \| 3 \| 4 \| 5 \| 6 \| 8 \| 10 |  | Spacing between all items. |
| rowGap | 0 \| 0.5 \| 1 \| 1.5 \| 2 \| 3 \| 4 \| 5 \| 6 \| 8 \| 10 |  | Row spacing; overrides `gap` for the row axis. |
| columnGap | 0 \| 0.5 \| 1 \| 1.5 \| 2 \| 3 \| 4 \| 5 \| 6 \| 8 \| 10 |  | Column spacing; overrides `gap` for the column axis. |
| align | 'start' \| 'center' \| 'end' \| 'stretch' | 'stretch' | Vertical alignment of items. |
| justify | 'start' \| 'center' \| 'end' \| 'stretch' | 'stretch' | Horizontal alignment of items. |
| children | ReactNode |  | Grid content. |
| xstyle | StyleXStyles |  | StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value: not an inline style object like style={{}}. |

### 使用建议

- Default to responsive columns for anything that must survive a phone: `columns={{minWidth: 240, max: 4}}` renders at most 4 columns, each at least 240px, and drops to one full-width column when narrow.
- 避免：Use `columns={4}` for a row that must work on small screens; a number never reflows and renders four narrow tracks on a phone. Reserve numbers for rows that must stay fixed, such as a 7-day week.
- Always pair `minWidth` with `max`: `max` caps the count on wide screens and lets the last column shrink to a narrow container; `{minWidth}` alone overflows a phone narrower than `minWidth`.
- Use `repeat: 'fill'` (the default) for consistent item widths. Use `'fit'` when items should stretch to fill leftover space.
- 避免：Write manual CSS grid; Grid handles spacing and responsive behavior for you.
- 避免：Use `HStack` with wrapping for grids; use Grid instead.
- Track templates use CSS-variable indirection (not raw inline styles), so `xstyle` overrides of `gridTemplateColumns` (including inside `@media` queries) take effect.

### 主题 API

```json
{
  "targets": [
    {
      "className": "astryx-grid",
      "visualProps": [
        "align",
        "columns",
        "gap",
        "justify"
      ]
    },
    {
      "className": "astryx-grid-span"
    }
  ]
}
```

## GridSpan



### 组件结构

- **Grid container**: Two-dimensional layout container that arranges caller-supplied items in rows and columns.
- **Spanning item**: Optional GridSpan wrapper that changes one item's column or row participation.

## Grid Span

可跨越多列或多行的网格项。

| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| columns | number \| 'full' |  | 要跨越的列数；使用 `'full'` 跨越整行。 |
| rows | number |  | 要跨越的行数。 |
| children | ReactNode |  | 内容。 |

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt