网格 · Grid

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

安装与前置条件

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

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见开始使用。

示例与使用方式

• 网格 · 综合展示 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.

使用建议

• 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

{
  "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

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