布局原语契约¶
意图¶
构建者应当能够使用同一套精简词汇,在一维或二维上排列任意内容、将其居中、调整其布局框的大小,并表达空间关系。选择 Stack、Grid 或 Center 会改变排列模型;它不会创建第二套间距刻度,也不会为共享 prop 名称赋予新的含义。
成员资格规则¶
当一个组件的主要公开用途是通过共享布局原语词汇排列任意子内容时,它属于该家族。当修饰器改变某个子项在该排列中的参与方式时,它与父组件一同归属。
- 成员: Stack、其 HStack 和 VStack 便捷形式、StackItem、Grid、GridSpan 和 Center。
- 协作者: 共享的
SpacingStep和SizeValue类型;Stack 和 StackItem 的样式工具;padding.stylex.ts;container-padding 架构;组件.doc.mjs主题元数据和运行时themeProps()输出。 - 排除项: Section、Layout、其命名区域以及 Toolbar 拥有的是结构性区域契约,而非本家族的任意子内容流式、网格和居中词汇。Layout 是一个通用原语,但其公共模型是五个命名槽位,而不是不受限制的子内容排列。FormLayout 负责字段排列和表单级可选性。AspectRatio 约束单个子项的盒子,而不是排列任意子内容。Card 和 Dialog 是表面。AppShell 负责页面外壳和应用导航组合。
成员资格依据公共职责,而非实现机制。组件不会仅仅因为其源码使用了 flexbox 或 grid 就加入该家族。
共享归属¶
SpacingStep拥有成员 gap 和 padding 属性使用的公共数值间距词汇。SizeValue拥有成员盒子尺寸的契约:数字作为像素、字符串作为 CSS 值。- Stack 拥有一维方向、换行以及主轴/交叉轴对齐。HStack 和 VStack 是该契约的固定方向形式。
- Grid 拥有固定轨道和内在/流体轨道构建。GridSpan 拥有单个子项的行和列参与。
- Center 拥有沿一个或两个轴的居中。
architecture:container-padding拥有出血几何。仅应用局部 padding 本身并不会发布该协议。
规范概念¶
| 概念 | 值或状态 | 默认语义 | 稳定性 |
|---|---|---|---|
| 间距步长 | 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10 |
由 token 支撑的距离,用于受支持的 gap 或 padding 属性 | 当前 |
| 盒子尺寸 | 数字或 CSS 值字符串 | 数字按像素处理;字符串按 CSS 值原样传递 | 当前 |
| 流动方向 | 水平或垂直 | Stack 默认垂直;HStack/VStack 固定方向 | 当前 |
| 对齐 | 主轴/交叉轴,或物理水平/垂直别名 | 由当前排列模型解析该轴 | 当前 |
| gap | 统一、行或列(若支持) | 排列项之间的空间,而非容器内缩 | 当前 |
| padding | 统一、轴向或逻辑边缘(若支持) | 成员自身盒子内部的空间 | 当前 |
| 子项参与 | 内在、填充、自对齐、跨列或跨行 | 修饰器改变一个子项在父排列中的角色 | 当前 |
| 响应性 | 内在适应、换行或消费方自定 | 每个成员记录自身可用的机制 | 组件自有 |
跨组件不变量¶
- FR1 — 共享名称保持共享的值语义。 类型为
SpacingStep或SizeValue的成员 prop 遵循共享的值与强制转换契约。成员仅暴露其排列模型支持的能力。 - FR2 — 逻辑间距遵循书写方向。 内联起始和结束是逻辑边缘。成员不得将它们重新解释为固定的左和右。
- FR3 — padding 优先级按边计算。 在具有完整 padding 梯级的成员上,显式边值优先于其轴向值,轴向值优先于统一
padding;一次覆盖只更改那一条边。 - FR4 — gap 与 padding 保持区分。 gap 分隔排列项。padding 将内容内缩在成员内部。Grid 的
rowGap和columnGap只在对应轴上覆盖其统一 gap。 - FR5 — 对齐遵循排列模型。 Stack 根据方向解析主轴和交叉轴。Grid 在轨道中对齐子项。Center 控制哪个轴或哪些轴被居中。在其他成员的 props 含义不同的情况下,成员不得照搬这些 props。
- FR6 — 修饰器组件要求其父模型存在。 StackItem 控制 Stack 中的参与;GridSpan 控制 Grid 中的参与。在预期父组件之外的行为由其各自的组件契约负责。
- FR7 — 响应行为是显式的。 Grid 可能根据内在轨道计算进行重排;Stack 仅在配置后换行;Center 不创建断点。该家族不承诺共享断点或自动区域切换。
- FR8 — 局部 padding 不是出血信号。 Stack 和 Center 当前会应用 padding,但不会发布容器内缩几何。后代只有在
architecture:container-padding所指名的发布者之下,才可以依赖出血补偿。 - FR9 — 公共契约不规定源码结构。 只要组件的可观察 API 和行为保持正确,组件可以使用成员工具或直接使用平台布局。
允许的组件变体¶
- AV1 — 布局模型。 Stack 使用一维流向,Grid 使用二维轨道,Center 使用单轴或双轴对齐。
- AV2 — 可用 props。 Stack、HStack、VStack 和 Center 暴露完整逻辑边内边距阶梯。Grid 暴露按轴区分的间距。Modifier 组件暴露针对父组件的参与方式,而非盒子级布局控制。
- AV3 — 元素所有权。 Stack、HStack、VStack 和 StackItem 是多态的。Grid、GridSpan 和 Center 目前拥有固定的 div 元素。
- AV4 — 溢出。 Stack、HStack、VStack 和 StackItem 暴露当前滚动行为;Grid 和 Center 不会因家族成员身份而获得该行为。
- AV5 — 响应式。 Grid 的固有列、Stack 换行以及使用方自定义的响应式样式仍然是组件特有的。
- AV6 — 实现。 允许直接使用 flex/grid,也允许使用共享工具。加入家族不会为仅涉及实现的选择带来迁移债务。
- AV7 — 主题化。 当前组件的
.doc.mjs元数据记录了已交付的目标和能力,运行时themeProps()调用会输出这些信息。architecture:component-theming-surface负责跨组件规则。当存在组件规范时,它可能会添加可选的解剖映射元数据;该家族既不假设,也不取代此类规范。
代表性矩阵¶
| 成员与状态 | 共享不变量 | 有意差异 |
|---|---|---|
| Stack / 垂直或水平 | 共享间距与尺寸值;方向决定对齐轴 | 可以换行、滚动或渲染指定元素 |
| HStack 或 VStack | 与 Stack 相同的契约,但方向固定 | 更窄的对齐类型与固定轴匹配 |
StackItem / size="fill" |
单个子元素可消耗 Stack 的剩余空间 | isScrollable 将溢出与 StackItem 的 flex 最小尺寸重置配对 |
| Grid / 固定列数 | 共享尺寸与间距值 | 显式的 1fr 轨道数量(columns={N});从不回流;最小内容可能加宽轨道 |
| Grid / 固有列 | 共享尺寸与间距值 | {minWidth, max?, repeat?} 构建可回流的流体轨道 |
| GridSpan / 列或行 | 修饰组件参与 Grid | 跨越轨道而非控制父级几何 |
| Center / 单轴或双轴 | 共享尺寸与内边距值 | 需要某个轴上有可用尺寸,居中效果才可见 |
采用与例外¶
| 组件或关注点 | 采用情况 | 当前缺口或例外 |
|---|---|---|
| Stack、HStack、VStack | 共享一维契约 | 间距 token 映射与 Grid 的映射分开实现 |
| StackItem | 共享修饰组件契约 | 不存在家族级的 flex-item grow/shrink/basis 词汇 |
| Grid、GridSpan | 共享二维契约 | 没有跨组件测试证明 Grid 和 Stack 对相同间距步长的解析一致 |
| Center | 共享尺寸与内边距词汇 | 与 Stack 一样,其内边距是局部的,不发布 bleed 几何信息 |
| 共享验证 | 每个组件有单元测试覆盖 | 没有计算样式矩阵证明每个共享间距和尺寸值在所有成员间一致 |
这些是已交付的覆盖缺口或采用缺口,并不表示在文档 pull request 中可以添加 props 或更改布局行为。
变更耦合¶
- 添加或更改共享空间 props 时,需要检查其名称、值类型、强制转换、逻辑方向和优先级是否仍与该家族一致。
- 更改
SpacingStep或SizeValue时,需审查所有暴露受影响类型的成员,并更新具有代表性的跨组件证据。 - 更改 Stack 的方向/对齐方式时,应在同一受审变更中同步更新 HStack 和 VStack。
- 更改 Grid 固有轨道的构建方式时,应通过针对性测试保持其已记录的 fixed、fill、fit 和 capped 状态。
- 将成员纳入 container bleed 是一个独立的
architecture:container-padding变更,并需提供渲染后的兼容性证据。 - 新组件只有在公共职责满足成员规则时才能加入;仅仅使用 flexbox、grid 或共享工具并不足以成为加入理由。
验证映射¶
| 契约 | 验证 | 证据证明了什么 | 缺失的证据 |
|---|---|---|---|
| FR1、FR3 | Stack 和 Center 源码及其内边距类集测试 | 针对所测试的值,当前的合并顺序为边内边距优先于轴内边距、轴内边距优先于统一内边距;等效拼写会生成相同的功能类集 | 没有浏览器矩阵跨成员或跨两种书写方向比较计算值 |
| FR2 | Stack 和 Center 中的逻辑属性源码声明 | 实现使用 inline-start/end 属性,而非物理 left/right 属性 | 当前测试未在 LTR 和 RTL 两种方向下渲染内边距阶梯 |
| FR4 | Stack/Grid 源码及其本地测试 | API 将 gap 与 padding 分开;Grid 接受统一和轴向 gap 属性 | Grid 的 gap/rowGap/columnGap 测试仅断言渲染成功,而非计算后的间距;且没有测试将 Grid 与 Stack 进行对比 |
| FR5 | Stack、Grid 和 Center 源码及本地渲染测试 | 每个成员当前通过自身的排列模型处理对齐 | Stack/Grid 测试未针对接受的取值断言计算后的对齐结果 |
| FR6 | StackItem 和 GridSpan 源码及本地测试 | 源码将 size="fill" 映射为 StackItem 的填充样式;滚动会改变类输出;GridSpan 断言精确的内联行/列跨度 |
StackItem 的填充测试仅断言渲染内容,而非填充行为;没有集成测试证明修饰符在所有父级状态下均有效 |
| FR7 | 精确的 Grid 轨道输出测试及 Stack/Center 源码 | Grid 的固定和固有轨道字符串已被固定;Stack 仅在配置时换行;Center 没有断点路径 | 不存在跨成员的响应式集成矩阵 |
| FR8 | 对照 architecture:container-padding 进行源码审查 |
Stack 和 Center 应用局部内边距,而不发布容器 inset 变量 | 没有浏览器断言证明 Divider/Table 后代所得出的 non-bleed 行为 |
这些测试是组件局部的,且若干测试仅断言渲染成功或类变化。它们并未证明计算后的 gap、对齐、逻辑方向或跨组件一致性。这些是已指明的验证缺口,而非隐含的覆盖范围。
决策链接¶
DEC-1 — 组合原语与结构区域各有独立负责人¶
决策者: cixzhang,2026-08-30
Stack、Grid、Center 及其修饰符构成 layout-primitives 家族。Section、Layout regions 和 Toolbar 由独立的结构区域负责人管理。这使成员归属保持可预测:原语规则描述任意子元素的组合方式,而无需将插槽(slot)、表面(surface)或工具栏(toolbar)语义强行纳入同一契约。
未决问题¶
无。采用表点明了缺失的能力与验证;它并未将这些转化为未解决的家族策略。
内容边界¶
本记录仅涵盖共享的组合词汇与行为。它不重复组件属性表、不规定实现机制、不定义结构区域、不分配响应式断点,也不负责主题化(theming)结构与目标。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx