GridSpan 组件契约¶
契约概览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | 一个可选包装器,用于单个 Grid 项,带有 columns(计数或 'full')和 rows。 |
| 行为 | 计数跨越相应数量的轨道;'full' 跨越所有显式列;包装器保持零最小宽度,使可收缩内容保留在其轨道内。 |
| 终端用户影响 | 读者看到精选或较高的项占据多个轨道,而不会破坏网格的顺序。 |
| 构建方影响 | 无;此记录描述已发布的行为。 |
| 兼容性/就绪状态 | 已发布行为记录为当前状态;无 API、默认值或输出变更。 |
| 审查检查 | 拒绝将 'full' 描述为覆盖隐式轨道、丢失零最小宽度或添加语义的包装器。 |
| 治理规则 | family:layout-primitives/FR6;architecture:public-component-api/INV5,INV6,INV8;architecture:component-theming-surface/INV2。 |
此表是审查速览;下文正文具有权威性。
意图¶
GridSpan 改变单个项在 Grid 中的参与方式:它覆盖多少列或行。它只拥有该包装器,不涉及内部内容的任何方面。
兼容性与迁移¶
- 已发布默认值保留:
yes - 兼容性类别:记录已发布行为;无公共 prop、默认值、DOM 或样式输出变更
- 受控/非受控行为:不适用
- 迁移决策:无
消费者迁移说明属于消费者文档和发布说明。
所有权边界¶
拥有
- 包装器
div,承载component:Grid发布并映射的grid-span目标,以及其列和行跨度。 - 包装器的单轨道内部网格和零最小宽度。
不拥有 / 非目标
- 轨道构建、间距和对齐——由
component:Grid拥有。 - 当数字跨度超过显式网格时,浏览器创建的隐式轨道。
- 调用方内容及其语义。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| Columns | 正数;full;未设置 |
跨越 N 列,或所有显式列。 | 在 Grid 内 | 固有放置 | component:GridSpan |
稳定 | 浏览器解析数字跨度,包括隐式轨道。 |
| Rows | 正数;未设置 | 跨越 N 行。 | 在 Grid 内 | 固有放置 | component:GridSpan |
稳定 | 浏览器验证生成的 CSS。 |
行为与布局契约¶
| ID | 不变量 | 依据 |
|---|---|---|
| FR1 | GridSpan 渲染一个 div,承载 grid-span 目标,显示为具有一个 minmax(0, 1fr) 列、零最小宽度和完整高度的网格,容纳其子元素。 |
当前源码和测试 |
| FR2 | columns={N} 设置 grid-column: span N;columns="full" 设置 grid-column: 1 / -1,仅覆盖显式列;rows={N} 设置 grid-row: span N。未设置的跨度使浏览器放置保持固有。 |
当前源码和测试 |
| FR3 | 跨度声明是内联样式,在调用方的 style 之后应用。ref 指向该 div;受支持的 DOM、ARIA、data 和事件 props 也会传递到该 div;xstyle 和 className 在组件样式之后合并。 |
当前源码和测试 |
允许的变体¶
- AV1 — 调用方内容。 任何内容都可以填充包装器。
代表性状态¶
| 状态 | 必需的不变量 | 允许的变体 |
|---|---|---|
| 数字跨度 | 跨越 N 个轨道;可能创建隐式轨道。 | N。 |
| 完整跨度 | 覆盖从第 1 条网格线到 -1 的显式列。 | 列数。 |
| 行跨度 | 跨越 N 行,通常配合 Grid 的 rowHeight。 |
N。 |
| 长内容 | 可收缩的后代保留在轨道内。 | 内容。 |
转换与优先级顺序¶
- ORD1 — 跨度。
'full'→1 / -1;数字 →span N;未设置 → 固有。 - ORD2 — 内联样式。 调用方
style→ 跨度声明。
性能与资源¶
- PR1 — 静态渲染。 GridSpan 不持有状态,也不使用任何 hooks。
无障碍契约¶
- AR1 — 无语义包装器。 GridSpan 不添加自身的 role、名称或 Tab 焦点停留点,并保持 DOM 顺序。
- AR2 — 内容保持可达。 零最小宽度使可收缩的后代保留在其轨道内;无法收缩的内容在
component:GridFR1 下仍可能溢出。
设计关系¶
| 解剖结构或状态 | 设计要求 | 表示权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 跨越项 | 一个项覆盖多条轨道;仅涉及几何。 | 当前源代码和文档 | 支持 | FR1, FR2, AR2 |
主题化:包装器携带 grid-span 目标,Grid.doc.mjs 声明了该目标,component:Grid 对其进行映射。GridSpan.doc.mjs 自身未声明任何解剖结构,因此此处不声明解剖结构主题化块。
族系与系统关系¶
family:layout-primitivesFR6 将 GridSpan 命名为 Grid 的参与修饰符;其在 Grid 之外的行为属于本记录。component:Grid拥有 GridSpan 所跨越的轨道。architecture:public-component-api拥有 ref、透传和样式输入规则;FR3 应用这些规则。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计部分 |
|---|---|---|---|---|
| FR1, FR2 | Grid.test.tsx GridSpan 测试套件;GridSpanAudit.a11y.chromium.spec.ts 作用于 GridSpan.stories.tsx;rtl-audit/targets.json 中的 GridSpan 顺序目标 |
数值型、完整型、行型、组合型、无;LTR 和 RTL | 错误的行内 grid-column 或 grid-row、在未给出跨度时设置了跨度,或丢失了 grid-span 目标,都会导致单元测试套件失败。丢失单轨内部网格或最小宽度为零,或跨度未覆盖两条轨道和一条间隙、未覆盖每个显式列,或未从行内起点覆盖两行和一条间隙,都会导致浏览器规范测试失败;行跨度停止生效或停止镜像会导致 RTL 顺序目标失败。缺口:完整高度没有独立于网格默认拉伸的检查。 |
audit:GridSpan/layout |
| FR3 | Grid.test.tsx 中 GridSpan 的 ref、透传、样式优先级和样式输入测试 |
ref;额外 props;调用方样式;className 和 xstyle |
以下情况均会导致失败:ref 解析为除 span 元素之外的任何内容、aria-label 被丢弃、调用方 style 覆盖了 span 元素、未设置跨度时丢失调用方的放置位置,或 className / xstyle 被丢弃或在组件样式之前合并。 |
audit:GridSpan/api |
| AR2 | Grid.stories.tsx 长内容 play 和 AuditMatrix 完整跨度检查;GridSpanAudit.a11y.chromium.spec.ts 长内容用例 |
长且可收缩的子元素;完整跨度 | 内容逃出其轨道,或完整跨度缺少显式列,会导致 play 失败;跨度或截断的子元素逃出其 240px 宿主容器,会导致浏览器规范测试失败。 | audit:GridSpan/layout |
| AR1, PR1 | serverSafeComponents.test.ts;Grid.test.tsx 的 no-role 测试;GridSpanAudit.a11y.chromium.spec.ts |
每个状态 | 未附带客户端指令而添加客户端 API,会导致 serverSafeComponents.test.ts 失败;span 上存在 role、可访问名称或 Tab 停留点,会导致单元测试和浏览器规范测试失败。缺口:与客户端指令一同添加的客户端 API 会通过。 |
audit:GridSpan/behavior |
决策日志¶
未记录任何内容。本记录描述的是已发布的行为。
开放问题¶
无。
内容边界¶
本文件不重复使用方 prop 表格/示例、当前审计结果、实现步骤或族系/系统规则。它链接到这些内容的所属方。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx