跳转至

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