Center 组件契约¶
契约一览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | 一个弹性容器,在 axis(both、horizontal、vertical)上居中其子元素,并支持 isInline、盒尺寸以及逐边逻辑 padding。 |
| 行为 | both 在两个轴上都居中;单轴值是物理轴名称,源代码将其映射到弹性主轴和交叉轴;padding 按逻辑边解析。 |
| 最终用户影响 | 读者会看到内容在其盒子中居中,且内边距随书写方向变化。 |
| 构建方影响 | 无;该记录描述的是已发布的行为。 |
| 兼容性/就绪状态 | 已发布的行为被记录为当前状态;无 API、默认值或输出更改。一个实现差距列于“当前状态影响”之下。 |
| 评审检查 | 拒绝物理左/右内边距、发布容器 inset 的内边距、用于替代所反射轴的调用方 data-axis,或新增语义。 |
| 治理规则 | family:layout-primitives/FR1–FR5,FR7,FR8;architecture:container-padding/INV8;architecture:public-component-api/INV5,INV6,INV8。 |
此表是评审投影;以下正文为准。
意图¶
Center 将调用方内容放置在其自身盒子内的水平中心、垂直中心或两者兼有。它拥有居中轴、显示模式、盒尺寸和局部内边距。
兼容性与迁移¶
- 已发布的默认值保留:
yes - 兼容性分类:记录已发布行为;无公开类型、默认值、受支持值、DOM 元素或主题目标变更
- 受控/非受控行为:不适用
- 迁移决策:无
使用方迁移说明属于使用方文档和发布说明。
当前状态影响¶
- 垂直书写中的单轴值(FR2)。
family:layout-primitives将horizontal和vertical列为物理轴对齐别名。Center 将horizontal映射到弹性主轴居中,将vertical映射到交叉轴居中,这在水平书写中与物理轴一致,但在垂直书写模式下会互换。
职责边界¶
拥有
div容器、其 flex 或 inline-flex 显示模式,以及带有反射axis的center目标。- 在所选轴或诸轴上的居中。
- 盒尺寸与逻辑内边距的优先级。
不拥有 / 非目标
- 调用方内容的语义、绘制、交互、尺寸或顺序。
- 页面和区域布局 —— 由 Layout 和产品调用点拥有。
- 子元素之间的间距、断点和溢出。
- 容器 inset 发布与后代溢出 —— Center 内边距在
architecture:container-padding下是局部的。
公开概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| Axis | both、horizontal、vertical |
哪个轴或哪些轴被居中(FR2)。 | 始终 | both |
component:Center |
稳定 | TypeScript 拒绝其他值。 |
| Display | flex;inline-flex | 块级或行内级容器。 | 每个轴 | flex | component:Center |
稳定 | — |
| Box size | width、height、maxWidth、minHeight:以像素为单位的数字或 CSS 字符串 |
Center 自身的盒尺寸。 | 始终 | 未设置 | family:layout-primitives |
稳定 | 字符串作为 CSS 直接透传。 |
| Padding | 按边、按轴或统一的空间步长 | 局部内部内边距。 | 始终 | 未设置 | family:layout-primitives |
稳定 | TypeScript 拒绝其他值。 |
行为与布局契约¶
| ID | 不变式 | 依据 |
|---|---|---|
| FR1 | Center 渲染一个 div,默认 display: flex,使用 isInline 时为 inline-flex,按调用方顺序持有其子元素。 |
当前源码与测试 |
| FR2 | both 在两个轴上居中。horizontal 和 vertical 在每种书写模式中都将物理水平轴和垂直轴居中(family:layout-primitives 物理轴别名)。Center 为 both 设置主轴和交叉轴居中,为 horizontal 仅设置主轴居中,为 vertical 仅设置交叉轴居中。实现差距:在垂直书写模式中,单轴值使相对的物理轴居中(当前状态影响)。 |
当前源码、测试和家族记录 |
| FR3 | width、height、maxWidth 和 minHeight 将数字作为像素应用,字符串按原样应用。 |
当前源码和测试 |
| FR4 | 内边距按逻辑边缘解析:先是边缘 prop,然后是其轴 prop(paddingInline 或 paddingBlock),最后是 padding;零是显式步骤。内联边缘遵循书写方向。 |
当前源码、测试和家族记录 |
| FR5 | Center 的内边距不会发布容器内边距变量。 | 当前源码和家族记录 |
| FR6 | 根元素携带 center 目标并反映 axis;调用方的 data-axis 不会替换它。ref 到达 div;受支持的 DOM、ARIA、data 和事件 props 在组件的目标和样式之前到达它;xstyle、className 和 style 按该顺序合并。 |
当前源码和测试 |
| FR7 | Center 不添加断点、溢出行为、间距或结构区域。它在服务器上渲染,无需客户端边界。 | 当前源码和测试 |
允许的变体¶
- AV1 — 调用方内容。 任何内容都可以出现在 Center 内部,并保持其自身的语义和主题。
- AV2 — 可用空间。 父级布局和尺寸输入可以改变盒子,而不会改变轴契约。
代表性状态¶
| 状态 | 必需的不变式 | 允许的变体 |
|---|---|---|
| 两个轴 | 主轴和交叉轴居中。 | 盒子尺寸。 |
| 仅水平 | 物理水平轴居中;不添加物理垂直居中。 | 高度。 |
| 仅垂直 | 物理垂直轴居中;不添加物理水平居中。 | 宽度。 |
| 垂直书写 | 单轴值仍指代物理轴(目前它们使相对的轴居中,即 FR2 差距)。 | — |
| 内联 | inline-flex 与所选轴。 |
— |
| 非对称逻辑内边距 | 起始和结束保持其含义;物理边缘随方向交换。 | — |
转换与优先级顺序¶
- ORD1 — 每边缘内边距。 边缘 prop → 轴 prop →
padding。 - ORD2 — 根属性。 调用方 props → 组件目标、反映的轴和样式 →
xstyle→className→style。
性能与资源¶
- PR1 — 静态渲染。 Center 不持有状态,也不使用任何 hooks。
可访问性契约¶
- AR1 — 被动容器。 Center 不添加自身的角色、名称、状态、焦点行为或实时区域;调用方的 ARIA 和角色 props 到达根元素。
- AR2 — 阅读顺序。 子元素按调用方顺序渲染,不会在视觉上重新排序。
设计关系¶
| 构成或状态 | 设计要求 | 表示权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| Container | 单轴或双轴居中,可选局部内缩,无表面。 | 当前源代码、文档及 family:layout-primitives |
辅助布局 | FR1–FR7 |
| Content | 容器内的调用方内容。 | 调用方拥有的内容 | 依上下文而定 | AV1, AR1, AR2 |
主题化结构¶
{
"Container": {"target": "center"},
"Content": {
"none": {
"reason": "intentional: Caller-supplied content retains its own theming ownership; Center applies no content target."
}
}
}
家族与系统关系¶
family:layout-primitives拥有共享的尺寸和内边距词汇表、内边距优先级,以及horizontal和vertical的物理轴含义;FR2 记录 Center 相对于它的 gap。architecture:container-padding将 Center 的内边距记录为局部(FR5)。architecture:public-component-api拥有透传、样式组合、ref 可达性以及自有属性边界(FR6)。spec:AST-002拥有对此公共表面的任何变更的接纳权。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计部分 |
|---|---|---|---|---|
| FR1, FR2 | Center.test.tsx 轴与内联测试;稳定视觉基线 core-center--default(中性与探针主题) |
Both、horizontal、vertical;inline;default | 错误的计算后 display、align-items 或 justify-content 会导致失败;默认居中发生变化时会以变更形式返回以供审查。缺口:没有自动化检查运行垂直书写模式或断言子元素顺序。 |
audit:Center/behavior |
| FR3 | Center.test.tsx 尺寸测试 |
Width、height、both | 缺口:尺寸测试仅断言元素能够渲染,因此像素转换和字符串透传没有自动化检查。 | audit:Center/layout |
| FR4 | Center.test.tsx 内边距优先级套件;@astryx/no-physical-properties lint 规则;core-center--padding-per-edge 上的 RTL 审计维度 D8 |
Uniform、axis、edge、zero、all four edges;LTR 和 RTL | 结束边缘上 edge 优先于 axis、以及 inline-start、inline-end 和 block-start 上 edge 优先于 uniform 的规则若失败则测试失败;物理 left/right 内边距属性会触发 lint 失败;除非逻辑 start 和 end 内边距交换物理侧,否则 RTL 审计失败。缺口:起始边缘上 edge 优先于 axis、block-end 上 edge 优先于 uniform、以及 axis 优先于 uniform 均无检查,且 CI 将 RTL 审计结果保持为非阻塞。 | audit:Center/layout |
| FR5, FR7 | serverSafeComponents.test.ts;Center.test.tsx 服务端渲染测试;源代码审查 |
Padded container | 客户端边界会导致 serverSafeComponents.test.ts 失败;服务端渲染错误会导致 Center 测试失败。缺口:与客户端指令一起添加的 hook 能通过所有检查;发布 container-padding 变量,或添加断点、溢出规则、gap 或区域,均无自动化检查。 |
audit:Center/layout |
| FR6 | Center.test.tsx ref、透传、xstyle 和自有属性测试;themingTargets.test.ts |
每个轴;冲突的 data-axis |
目标丢失或调用方 data-axis 获胜会导致失败。缺口:ref 测试接受任何 div,因此 wrapper 上的 ref 会通过,且样式输入合并顺序无检查。 |
audit:Center/theming |
| AR1, AR2, PR1 | serverSafeComponents.test.ts;源码审查 |
多个子级 | 在没有客户端指令的情况下添加的 Hook 会导致 serverSafeComponents.test.ts 失败。缺口:与客户端指令一起添加的 Hook 会通过,如果 Center 添加语义或对子级重新排序,则没有任何自动化检查会失败。 |
audit:Center/a11y |
| 主题结构映射 | scripts/check-knowledge.mjs |
消费者的结构与当前目标 | 缺失、多余或过时的映射会导致仓库验证失败。 | audit:Center/theming |
决策日志¶
无记录。本记录描述的是已发布的行为。
待解决的问题¶
无。
内容边界¶
本文件不重复消费者 prop 表格/示例、当前审计结果、实现步骤或家族/系统规则。它链接到这些内容的所有者。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx