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 拥有该包装器的行为。
主题结构¶
家族与系统关系¶
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