跳转至

Grid 组件契约

契约概览

区域 契约
公共契约 Grid 使用 columns(固定数量或响应式对象)、间距、项目对齐、rowHeight 和盒子尺寸,将子元素排列在二维轨道中。
行为 正数精确创建 N 条 1fr 轨道且不进行重排;对象根据像素最小值创建 fill/fit 轨道并可选设数量上限;轴向间距覆盖统一间距。
最终用户影响 内容保持 DOM 顺序和逻辑方向,同时响应式对象形式网格会减少数量以适应布局。固定轨道在内容无法收缩时可能会变窄或溢出。
构建者影响 无;该记录描述已发布行为。构建者明确选择固定数值轨道或响应式对象轨道。
兼容性/就绪状态 已发布行为记录为当前状态;无 API、默认值、目标或运行时变更。
审查检查 拒绝数值列的自动重排、忽略最小内容内容的等宽承诺、丢失间距优先级、原始内联轨道模板,或可被调用方覆盖的属主元数据。
管理规则 family:layout-primitives/FR1–FR7;architecture:public-component-api/INV5–INV9;architecture:component-theming-surface/INV2–INV6。

此表是审查投影;下方正文具有权威性。

意图

Grid 将调用方提供的项目排列在二维轨道中。它负责轨道构建、间距、项目对齐和自身盒子尺寸;它不拥有内容、表面或结构性的页面语义。

兼容性与迁移

  • 保留已发布默认值:是;省略、为零或负数的数值 columns 解析为一条轨道。
  • 兼容性类别:记录已发布行为;无运行时、DOM、样式、目标或公共 API 变更。
  • 受控/非受控行为:不适用。
  • 迁移决策:无。

消费者迁移说明属于消费者文档和发布说明。

属主边界

拥有

  • Grid 的根容器、grid 目标、轨道构建、轴向间距、项目对齐和显式盒子尺寸。
  • GridSpan 的包装器携带的 grid-span 目标,由 Grid.doc.mjs 声明且下方解剖图列出。
  • Grid 根上的根属性和样式组合。

不拥有 / 非目标

  • 调用方内容、项目语义、表面或交互——由产品调用点或渲染的子组件拥有。
  • 共享断点或数值列的自动重排——响应性通过 Grid 的对象形式选择。
  • GridSpan 包装器的行为以及单个项目的行和列参与——由 component:GridSpan 拥有,其有自己的消费者文档和记录。

公共概念

概念 封闭值或状态 含义 按变体/方向/状态的可用性 默认值 拥有者 稳定性 无效值行为
列形状 固定数值;响应式对象;省略 选择固定 1fr 轨道或内在 fill/fit 轨道。 每个 Grid 一条轨道 component:Grid 稳定 零/负数回退为一条轨道
响应式重复 fill;fit 保留空轨道或将其折叠,使现有项目拉伸。 对象形式列 fill component:Grid 稳定 类型约束
响应式数量上限 缺省;正数 max;非正数 max 限制内在轨道数量,同时允许现有轨道填充。 对象形式列 缺省 component:Grid 稳定 非正数视为无上限
间距 共享 SpacingStep 值 分隔行/列;轴向值覆盖统一间距。 每个 Grid 浏览器网格间距默认值 family:layout-primitives 稳定 类型约束
项目对齐 start;center;end;stretch 设置 align-items 和 justify-items。 每个 Grid 浏览器 normal component:Grid 稳定 类型约束
盒子尺寸 数值;CSS 值字符串;缺省 设置 Grid 盒子尺寸;数值转换为像素。 每个 Grid 由调用方/容器决定 family:layout-primitives 稳定 浏览器验证字符串
隐式行高 数值;缺省 为行跨度使用的隐式行设置像素高度。 每个 Grid 浏览器 auto component:Grid 稳定 浏览器验证生成的 CSS

行为与布局契约

ID 不变式 依据
FR1 正数值 columns={N} 在每个宽度下精确创建 N 个 1fr 轨道,且从不重排;最小内容可能加宽一个轨道并溢出窄容器。省略、为零或负数的 columns 则生成一个 1fr 轨道。 DEC-1;已发布的文档、源码和测试
FR2 对象形式的 columns 默认使用 auto-fill,或在 repeat: 'fit' 时使用 auto-fit;minWidth 是轨道下限,而正数的 max 限制轨道数量,并允许单个轨道收缩到容器宽度。 已发布的文档、源码和测试
FR3 rowGap 仅对行覆盖 gap,columnGap 仅对列覆盖 gap;有效的列间距参与封顶轨道的计算。rowHeight 以像素为单位设置隐式行高。 family:layout-primitives/FR4;源码和测试
FR4 轨道模板是类级声明,因此调用方的 xstyle 和类规则(包括媒体规则)可以替换它。调用方的 style 优先于其他内联声明,而显式的 width、height、maxWidth 和 minHeight 属性会覆盖对应的 style 键。 architecture:public-component-api/INV5–INV8;源码和测试
FR5 align 和 justify 将 align-items 和 justify-items 设置为 start、center、end 或 stretch;未设置时保留浏览器默认值(normal,会拉伸没有自然尺寸或宽高比的条目)。 源码和测试
FR6 ref、DOM、data、ARIA 和事件属性、xstyle、类名以及内联样式都会到达根元素或在根元素上组合,而不会替换 grid 目标或其反射的 columns(仅限数字形式)、gap、align 和 justify。 architecture:public-component-api/INV5–INV8;源码和测试
FR7 Grid 保持调用方的 DOM 顺序,并使用文档的逻辑内联方向;它不创建独立的键盘顺序。 平台布局行为

允许的变化

  • AV1 — 调用方内容。 任何调用方拥有的元素都可以直接参与或位于 GridSpan 内部;Grid 不会检查或重写它。
  • AV2 — 轨道数量。 容器宽度、最小内容、间距和对象形式选项可以在 FR1–FR3 范围内改变渲染的响应式数量。
  • AV3 — 根元素样式。 调用方样式可以替换轨道模板或盒模型呈现,同时保留组件拥有的目标和元数据。

代表性状态

状态 必需的不变式 允许的变化
固定 Grid 恰好 N 个显式 1fr 轨道;无组件引发的重排。 N、内容最小值、间距和调用方样式。
响应式填充 空轨道保持分配,同时轨道数量响应可用宽度。 最小宽度、上限、内容数量和有效间距。
响应式适配 空轨道折叠,现有条目拉伸。 最小宽度、上限、内容数量和有效间距。
封顶的窄 Grid 轨道数量减少,一个现有轨道可以填充低于 minWidth 的容器。 容器宽度和调用方内容。
直接条目 调用方内容无需 Grid 拥有的包装器即可参与。 任何调用方拥有的元素和语义。

转换与优先级顺序

  • ORD1 — 轨道形态。 带正数 max 的响应式对象 → 封顶的 fill/fit 模板;不带正数 max 的响应式对象 → 不封顶的 fill/fit 模板;正数 → 固定的 repeat(N, 1fr);否则 → 一个 1fr 轨道。
  • ORD2 — 间距。 轴向间距 → 统一间距 → 无间距项参与封顶轨道计算。
  • ORD3 — 根元素组合。 先应用调用方属性;随后组合组件拥有的目标、反射和 StyleX;xstyle、类名和调用方内联样式保持其样式优先级;尺寸属性优先于匹配的内联键。

性能与资源

  • PR1 — CSS 拥有的布局。 Grid 不拥有状态、副作用、观察器、监听器、定时器或 JavaScript 测量;布局和回流由 CSS 负责。

无障碍契约

  • AR1 — 布局保持无语义。 Grid 渲染一个 <div>,本身不带有 grid、list、group 或 landmark 语义;当调用方的组合需要语义时,由调用方提供。
  • AR2 — 顺序保持可感知。 在 LTR 和 RTL 中,DOM 顺序仍然是阅读顺序和键盘顺序;视觉轨道不会创建第二条序列。

设计关系

解剖结构或状态 设计要求 表示权威 层级角色 组件契约
网格容器 为调用方条目提供二维轨道;仅涉及几何。 当前源码与文档 支撑性 FR1–FR6
跨越条目 一个可选包装器,记录在 Grid 旁边。 component:GridSpan 支撑性 —

主题:根节点是 grid 目标,反映 align、数字 columns、gap 和 justify。Grid.doc.mjs 记录了跨越条目部件及其 grid-span 目标,因此下方映射同时列出两者;component:GridSpan 拥有该包装器的行为。

主题结构

{
  "Grid container": {"target": "grid"},
  "Spanning item": {"target": "grid-span"}
}

家族与系统关系

  • family:layout-primitives 拥有共享的间距、尺寸、对齐和条目参与词汇;Grid 拥有二维实现,component:GridSpan 拥有参与修饰符。
  • architecture:public-component-api 拥有根属性、样式、事件、ref 和已发布类型组合。
  • architecture:component-theming-surface 设定 grid 目标及其反射轴遵循的规则。
  • architecture:component-test-sufficiency 拥有有界、对变更敏感的证据选择。

验证映射

契约 验证 代表性状态 变更或失败预期 审计部分
FR1–FR3, ORD1, ORD2 Grid.test.tsx 中的轨道模板、行高和封顶间距测试;Grid.stories.tsx AuditMatrix play guard 固定;零和负值;fill;fit;带或不带间距的封顶;行高 更改轨道模板(数量、fill 或 fit、下限、封顶或封顶内的间距)或行高会失败精确断言;超出宿主的网格会失败 play guard。缺口:gap 和 axis-gap 测试仅断言网格能够渲染,因此 rowGap 和 columnGap 在其轴上覆盖 gap 的行为没有检查。 audit:Grid/behavior
FR4, FR6, ORD3 Grid.test.tsx 中的原始内联模板、尺寸、ref、透传和自有元数据测试;themingTargets.test.ts DOM、数据、ARIA、事件;class、style、xstyle;反射轴 丢失 aria-label、替换自有元数据、原始内联轨道或错误的宽度/高度会失败。缺口:ref 测试接受任何元素,且 xstyle、className、style 的合并顺序以及尺寸属性优先于 style 的行为没有检查。 audit:Grid/api
FR5 Grid.test.tsx 中的对齐和自有元数据测试 align 和 justify 丢失 data-align 或 data-justify 反映会失败。缺口:对齐测试仅断言网格能够渲染,因此 align-items 和 justify-items 的值没有检查。 audit:Grid/behavior
FR7, AR1, AR2 Grid.stories.tsx 中 LTR 和 RTL 下的 AuditMatrix play guard 两种方向下的固定轨道 条目未按文档方向从头到尾运行会失败 play guard。缺口:没有自动化检查断言 Grid 不添加角色或保持 DOM 顺序。 audit:Grid/a11y-rtl
PR1 serverSafeComponents.test.ts;源码审查 每种状态 在未添加客户端指令的情况下添加客户端 API(state、effect)会使 serverSafeComponents.test.ts 失败。缺口:客户端 API 与客户端指令一起添加时通过,且没有自动化检查会在 Grid 添加布局测量时失败。 audit:Grid/behavior
主题结构映射 scripts/check-knowledge.mjs 消费者结构与当前目标 缺失、多余或过时的映射会使仓库验证失败。 audit:Grid/theming
RTL 关系 RTL 审计的精选 D2 目标(apps/storybook/rtl-audit/targets.json)应用于 Grid / With grid span 跨轨道和单轨道项目;LTR 和 RTL 如果第一个网格项目不在下一行的内联起始(inline start)位置,则 D2 失败。 audit:Grid/i18n-rtl

决策日志

DEC-1 — 数字 columns 保持固定;重排使用现有的对象形式

参考: component:Grid/DEC-1 决策者: cixzhang, 2026-10-11

columns={N} 表示每个宽度下正好有 N 个 1fr 轨道;在小屏幕上重排的网格使用 {minWidth, max?, repeat?}。数字是固定契约;对象形式是响应式契约。

已否决: 将数字重新定义为“最多 N 个”会破坏已发布的数字网格;{count, isFixed} 形式会重复数字和 max 上限。

开放问题

无。

内容边界

本文件不重复消费者 prop 表/示例、当前审计结果、实施步骤或家族/系统规则。它链接到这些内容的所属者。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx