跳转至

Stack 组件契约

契约概览

领域 契约
公共契约 Stack 通过 direction、对齐、gap、各边缘 padding、尺寸、wrap、isScrollable 和 as 在一条 flex 轴上排列子项。HStack 和 VStack 固定方向;StackItem 控制单个子项的参与。
行为 对齐属性根据 direction 解析为主轴或交叉轴;padding 按逻辑边缘解析;padding 保持局部性,不发布任何容器内缩进。
最终用户影响 最终用户会看到遵循书写方向的一致间距和对齐。
构建者影响 无:无 API 变更;滚动的 div 或 span StackItem 无需代码更改即可获得 role 和名称(AR2)。
兼容性/就绪状态 无 API 或默认值变更;滚动 div 或 span StackItem(AR2)的 role 和名称是一个补丁 [fix]。
审查检查 拒绝物理左右 padding、覆盖显式对齐的别名、发布容器内缩进的 padding,或未重置 flex 最小尺寸的 StackItem。
治理规则 family:layout-primitives/FR1–FR6,FR8;architecture:container-padding/INV8;architecture:public-component-api/INV5,INV6,INV8。

本表是审查投影;以下正文为权威。

意图

Stack 是一维布局原语。它负责 flex 容器的方向、轴向感知对齐、间距、局部 padding、尺寸、换行和滚动;StackItem 负责其中单个子项的伸缩、对齐和滚动。

兼容性与迁移

  • 已发布默认值保留:yes
  • 兼容性类别:补丁。无公共 prop、默认值或样式输出变更。当它滚动时,没有调用方 role 的可滚动 div 或 span StackItem 会获得 role="group" 和 aria-label(DOM;AR2,[fix] 位于 spec:AST-017 FR53)
  • 受控/非受控行为:不适用
  • 迁移决策:无

消费者迁移说明应放入消费者文档和发布说明中。

所有权边界

拥有

  • Stack、HStack、VStack 和 StackItem,Stack.doc.mjs 将其记录为内联 components: 条目。本记录涵盖全部四个;它们各自没有自己的消费者文档或记录。
  • Stack 容器及其 stack 目标;StackItem 包装器及其 stack-item 目标。
  • 对齐的轴向解析、各边缘 padding 解析、间距、尺寸、换行和滚动。

不拥有 / 非目标

  • 提供给 Stack 或 StackItem 的内容——由调用方拥有。
  • 容器内缩进发布和后代溢出——由 architecture:container-padding 下的发布者拥有;Stack padding 是局部的。
  • 二维布局——由 component:Grid 拥有;居中——由 component:Center 拥有。

公共概念

概念 封闭值或状态 含义 按变体/方向/状态的可用性 默认值 拥有者 稳定性 无效值行为
方向 horizontal、vertical Flex 行或列。HStack 为水平;VStack 为垂直。 仅 Stack;在 HStack 和 VStack 上固定 vertical component:Stack 稳定 TypeScript 拒绝其他值。
对齐 主轴 start、center、end、between、around、evenly;交叉轴 start、center、end、stretch hAlign/vAlign(按物理名称),或 justify/align(按轴向)。 所有 Stack 浏览器默认值(交叉轴上为 stretch) component:Stack 稳定 Stack 在 hAlign 和 vAlign 上接受所有对齐值,并忽略不适用于已解析轴向的值;HStack、VStack、justify 和 align 在 TypeScript 中拒绝该值。
间距 间距步长 0、0.5、1、1.5、2、3、4、5、6、8、10 行间隙和列间隙。 所有 Stack 未设置 component:Stack 稳定 TypeScript 拒绝其他值。
Padding 按边、按轴或统一的间距步长 局部内边距。 所有堆叠 unset component:Stack 稳定 TypeScript 拒绝其他值。
Wrap nowrap、wrap、wrap-reverse Flex 换行。 所有堆叠 unset(nowrap) component:Stack 稳定 TypeScript 拒绝其他值。
Item size static、fill StackItem 既不增长也不收缩,或增长以填满。 StackItem static component:Stack 稳定 TypeScript 拒绝其他值。

行为与布局契约

ID 不变量 依据
FR1 Stack 将 as(默认 div)所命名的元素渲染为指定方向的 flex 容器,并携带 stack 目标,该目标反映 direction、gap 和 wrap。HStack 以 direction="horizontal" 渲染 Stack,VStack 以 direction="vertical" 渲染 Stack。 当前源代码与测试
FR2 hAlign 和 vAlign 命名物理轴:在水平堆叠中,hAlign 设置主轴对齐,vAlign 设置交叉轴对齐;在垂直堆叠中则相反。justify 和 align 分别命名主轴和交叉轴,且仅在对应的 hAlign 或 vAlign 不存在时生效。未设置对齐时保留浏览器默认值。 当前源代码与测试
FR3 gap 根据间距比例设置相等的行间距和列间距。内边距按逻辑边解析:先是边属性,然后是其轴属性(paddingInline 或 paddingBlock),最后是 padding;内联边遵循书写方向。 当前源代码与测试
FR4 Stack 的内边距是局部的:它不发布任何容器内边距变量,因此后代元素无法用它进行出血补偿。 当前源代码
FR5 width、height、maxWidth 和 minHeight 将数字作为像素值、字符串按原样应用,作为调用方 style 之后的内联样式。wrap 设置 flex 换行。isScrollable 设置 overflow: auto。 当前源代码与测试
FR6 StackItem 将 as(默认 div)所命名的元素渲染为携带 stack-item 目标的元素,该目标反映 size;它始终将最小宽度和最小高度重置为零,static 既不增长也不收缩,fill 增长以共享剩余空间,crossAlignSelf 覆盖堆叠的交叉轴对齐,isScrollable 设置 overflow: auto。 当前源代码与测试
FR7 ref 可到达 Stack、HStack、VStack 和 StackItem 渲染出的元素。受支持的 DOM、ARIA、data 和事件属性均能到达该元素;xstyle、className 和 style 按该顺序在组件样式之后合并。 当前源代码与测试

允许的变体

  • AV1 — 元素。 调用者通过 as 选择元素。
  • AV2 — 主题绘制。 主题可以重新设置 stack 和 stack-item 的样式,而无需改变轴解析或内边距优先级。

代表性状态

状态 必需不变量 允许的变体
垂直默认 flex 列;data-direction="vertical"。 子元素。
带别名的水平排列 justify 设置主轴,align 设置交叉轴,除非设置了 hAlign/vAlign。 —
逐边内边距 每条边独立解析;内联边在从右到左(RTL)中镜像。 —
填充与滚动项 StackItem size="fill" isScrollable 会增长并滚动自身溢出的内容。 —

转换与优先级顺序

  • ORD1 — 对齐。 hAlign/vAlign → 按轴的 justify/align → 浏览器默认。
  • ORD2 — 逐边内边距。 边属性 → 轴属性 → padding。
  • ORD3 — 尺寸。 调用者的 style → 尺寸属性。

性能与资源

  • PR1 — 静态渲染。 Stack、HStack、VStack 和 StackItem 不持有状态,也不使用任何 hook。唯一的例外是可滚动的 div 或 span StackItem:它通过一个客户端孤岛渲染,该孤岛观察其溢出以支持 AR2。

无障碍契约

  • AR1 — 不添加语义。 Stack 和 StackItem 自身不添加角色、名称或 Tab 停靠点;它们的语义即 as 元素的语义。唯一的例外是可滚动 StackItem 的名称(AR2)。
  • AR2 — 可滚动的 StackItem 具有名称。 当可滚动的 div 或 span StackItem 滚动时,其元素具有 role="group"(除非调用者设置了 role)和一个可访问名称(调用者的 aria-label,或翻译后的"内容"),因此到达它的屏幕阅读器(包括作为浏览器生成的 Tab 停靠点)会播报它;Tab 行为由浏览器决定(所有者决策,2026-11-04)。调用者的 role 仅采用调用者的 aria-label,其他元素保留自身的角色和名称。在浏览器不为其生成 Tab 停靠点的情况下,内容中没有任何可聚焦元素的滚动区域无法通过键盘滚动。此时调用者应添加一个可聚焦的子元素,或使用 ScrollableArea。

设计关系

解剖结构或状态 设计需求 表示权威 层级角色 组件契约
Stack 容器 一维布局容器。 当前源代码、文档和家族契约 支撑 FR1–FR5
条目 可选地控制一个子元素的参与。 当前源代码、文档和家族契约 支撑 FR6
内容 任一包装器中的调用者内容。 调用者提供的内容 上下文相关 AR1

主题解剖结构

{
  "Stack container": {"target": "stack"},
  "Item": {"target": "stack-item"},
  "Content": {
    "none": {
      "reason": "intentional: Caller-supplied content retains its own theming ownership; Stack and StackItem apply no content target."
    }
  }
}

家族与系统关系

  • family:layout-primitives 拥有共享的间距、内边距优先级和修饰符规则;Stack、HStack、VStack 和 StackItem 是其成员,FR2、FR3 和 FR6 适用于它们。
  • architecture:container-padding 将 Stack 内边距记录为局部(FR4)。
  • architecture:public-component-api 拥有 ref、透传和样式输入规则;FR7 适用于它们。

验证映射

契约 验证 代表性状态 变异或失败预期 审计部分
FR1, FR2 Stack.test.tsx、HStack.test.tsx、VStack.test.tsx 元素测试;HStack.test.tsx 目标、反射、轴向、别名和优先级测试;HStackAudit 的 HStack / Alignment Matrix Chromium 帧;稳定视觉基线 core-stack--default 默认与 as 元素;默认 Stack 错误的默认元素或 as 元素会导致测试失败;默认方向、gap 或对齐方式发生改变时,会以变更后的结果返回供审查。如果 HStack 失去水平方向、stack 目标或其反射能力,将对齐 prop 或别名发送到错误的 Stack prop,或丢失别名优先级,则 HStack.test.tsx 失败;如果最终的水平几何形状在从右到左方向下镜像后错误,则 HStackAudit 帧失败。差距:Stack 和 VStack 的方向、对齐和别名测试仅断言内容会渲染,因此垂直 data-direction 反射和 Stack 自身的轴映射没有单元检查。 audit:Stack/layout
FR3 Stack.test.tsx padding 优先级测试;@astryx/no-physical-properties lint 规则 uniform、axis、edge、全部四条边 如果缺少某个 padding 类,在末端边缘上 edge 优先于 axis,在测试配对的边缘上 edge 优先于 uniform,或使用了物理的 left/right padding 属性,则测试失败。差距:起始边缘上 edge 优先于 axis、axis 优先于 uniform、任何未测试的 edge-over-uniform 配对,以及 gap 值(gap 测试仅断言内容会渲染)均无检查;也没有覆盖这些边缘的浏览器从右到左检查。 audit:Stack/layout
FR5 Stack.test.tsx 尺寸与滚动测试;HStack.test.tsx 合并测试;HStackAudit wrap 帧 数字和字符串尺寸;可滚动 计算出的宽度或高度错误,或 isScrollable 没有类名变化,则测试失败。如果 width 不能覆盖调用方的 style,则 HStack.test.tsx 失败;如果 wrap 不能使行换行,则 HStackAudit 帧失败。差距:height、maxWidth 和 minHeight 覆盖调用方 style 的情况、maxWidth 和 minHeight 本身,以及 Stack 和 VStack 上的 wrap,均无检查。 audit:Stack/layout
FR6 StackItem.test.tsx 元素、滚动和透传测试 默认与 as 元素;可滚动;size="fill" 且带滚动 元素错误,或 isScrollable 没有类名变化,则测试失败。差距:size 和 crossAlignSelf 测试仅断言内容会渲染,因此最小尺寸重置、static、fill、交叉对齐以及 stack-item 目标均无检查。 audit:Stack/layout
FR7 所有四个测试套件中的 ref 与透传测试;HStack.test.tsx 的精确 ref 与合并测试 默认元素和 as 元素 丢失 ref 会导致所有四个测试套件失败;在 Stack、HStack 和 StackItem 套件中,丢失 aria-label 会导致失败(VStack 的透传测试仅断言 data-testid)。HStack.test.tsx 会在 ref 到达渲染元素以外的任何元素时失败,或在 className 和 style 未合并时失败。差距:Stack、VStack 和 StackItem 的 ref 测试接受任何元素,因此 ref 落在包装器上也能通过,且 xstyle、className、style 的顺序没有检查。 audit:Stack/behavior
FR4 对照 architecture:container-padding 进行源码审查 带内边距的 Stack 差距:如果 Stack 发布 container-padding 变量,没有任何自动化检查会失败。 audit:Stack/layout
Theming anatomy map scripts/check-knowledge.mjs 消费者结构及当前目标 缺失、多余或过时的映射会使仓库验证失败。 audit:Stack/theming
AR1, PR1 serverSafeComponents.test.ts;HStack.test.tsx 的无 role 测试;HStackAudit 框架;源码审查 所有形式 在未添加客户端指令的情况下加入客户端 API(状态、effect 或 context 读取)会使 serverSafeComponents.test.ts 失败。如果 Stack 在其水平路径上添加 role 或 Tab 停靠点,HStack.test.tsx 和 HStackAudit 框架会失败。差距:客户端 API 与客户端指令一同添加时能通过,且如果 Stack 在其垂直路径上添加 role 或 Tab 停靠点,或 StackItem 添加其中任意一种,没有任何自动化检查会失败。 audit:Stack/behavior
AR2 useScrollRegionProps.test.tsx StackItem 测试;scrollRegionName.a11y.chromium.spec.ts stack-item-scrolls 和 stack-item-static 滚动项;调用方 region 角色和 aria-label;不可滚动的项目 当项目溢出时缺少 group 角色或名称,或该角色或名称出现在不可滚动的项目上,均判定为失败,在 Chromium 的无障碍树中同样如此;调用方的角色或 aria-label 丢失也会失败。 audit:Stack/behavior
RTL 关系 RTL 审计精选目标(apps/storybook/rtl-audit/targets.json):Stack 和 StackItem 在 Stack / Horizontal 和 Stack / StackItem fill size 上的 D2,HStack 在 AspectRatio / Height driven 和 HStack / Alignment Matrix 上的 D2,VStack 在 Spinner / Narrow flex host 上的 D4 水平堆叠、静态与填充项目,以及起始对齐的垂直堆叠;LTR 和 RTL 如果水平堆叠的第一个子项不在内联起始位置,或者起始对齐的垂直堆叠的子项未移动到镜像侧,则 D2 或 D4 失败。 audit:Stack/i18n-rtl

决策日志

无记录。该记录描述的是已发布的行为。

开放问题

无。

内容边界

本文件不重复消费者 prop 表格/示例、当前审计结果、实现步骤或家族/系统规则。它链接到其所属文档。

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