跳转至

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:Grid FR1 下仍可能溢出。

设计关系

解剖结构或状态 设计要求 表示权威 层级角色 组件契约
跨越项 一个项覆盖多条轨道;仅涉及几何。 当前源代码和文档 支持 FR1, FR2, AR2

主题化:包装器携带 grid-span 目标,Grid.doc.mjs 声明了该目标,component:Grid 对其进行映射。GridSpan.doc.mjs 自身未声明任何解剖结构,因此此处不声明解剖结构主题化块。

族系与系统关系

  • family:layout-primitives FR6 将 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