跳转至

AspectRatio 组件契约

契约速览

方面 契约
公共契约 一个带有必需 ratio、shape 为 rectangle 或 ellipse、并可为其单个子元素设置可选 fit(cover、contain 或 center)的盒子。
行为 该盒子采用其容器的宽度,并通过类级 aspect-ratio 从 ratio 推导高度,裁剪溢出,并按 fit 布局其子元素。
最终用户影响 读者看到的是以稳定形状呈现的媒体和占位符,不会因内容加载而发生布局偏移。
构建者影响 无;该记录描述的是已发布行为。
兼容性/就绪状态 已发布行为记录为当前状态;无 API、默认值或输出变更。
审查检查 拒绝内联 aspect-ratio、会修改子元素自身 props 的 fit、反映到主题目标上的 fit,或停止裁剪的盒子。
治理规则 architecture:public-component-api/INV5,INV6,INV8;architecture:component-theming-surface/INV2,INV6。

此表是审查投影;下文正文具有权威性。

意图

AspectRatio 以固定的宽高比容纳内容,使媒体、嵌入内容和占位符在加载前预留空间。它拥有比例盒子、可选的椭圆裁剪,以及子元素填充盒子的方式。

兼容性与迁移

  • 已发布默认值保留:yes
  • 兼容性类别:记录已发布行为;公共 prop、默认值、DOM 或样式输出均无变化。内容槽保留携带 fit 的 data-astryx-aspect-ratio-override 属性,供针对它的产品 CSS 使用;该属性上没有 Astryx 样式键。
  • 受控/非受控行为:不适用
  • 迁移决策:无

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

所有权边界

拥有

  • 比例盒子:其宽度、推导高度、裁剪和椭圆形状。
  • 填充盒子并定位子元素的内容槽。
  • 当设置 fit 时,直接子元素的尺寸和 object-fit。

不拥有 / 非目标

  • 子元素的内容、语义和替代文本——由调用方拥有。
  • 响应式比例更改——由调用方 CSS 通过 xstyle 或非分层 aspect-ratio 规则拥有。
  • 头像和缩略图呈现——由 component:Avatar 和 component:Thumbnail 拥有。

公共概念

概念 封闭值或状态 含义 按变体/方向/状态的可用性 默认值 所有者 稳定性 无效值行为
Ratio 一个正数,宽 ÷ 高 盒子的 aspect-ratio。 始终 必需 component:AspectRatio 稳定 按原样传递给 CSS。
Shape rectangle、ellipse 盒子是否被裁剪为椭圆(比率为 1 时为圆形)。 始终 rectangle component:AspectRatio 稳定 TypeScript 拒绝其他值。
Fit cover、contain、center;unset 子元素如何填充盒子:拉伸并裁剪、拉伸并加黑边,或以自然尺寸居中;unset 则子元素保持无样式。 始终 unset component:AspectRatio 稳定 TypeScript 拒绝其他值。

行为与布局契约

ID 不变量 依据
FR1 比例盒子是一个相对定位、全宽的 div,具有裁剪溢出、零最小高度、无 flex 收缩,并携带反映 shape 的 aspect-ratio 目标。其 aspect-ratio 为 ratio,以类级声明形式发出,因此 xstyle、非分层调用方规则或内联 style 可以覆盖它。 当前源码和测试
FR2 shape="ellipse" 使比例盒子具有 50% 的边框半径,在比例为 1 时将其裁剪为圆形,否则裁剪为椭圆形。 当前源代码和测试
FR3 内容插槽绝对定位于盒子顶部内联起始角,占满全宽和全高,并在设置时携带等于 fit 的 data-astryx-aspect-ratio-override。 当前源代码和测试
FR4 fit="cover" 和 fit="contain" 将所有直接子元素调整为完整盒子大小,并让直接 img 或 video 子元素获得 object-fit: cover 或 contain;fit="center" 将子元素以其自然大小居中;未设置 fit 时不应用任何子元素样式。fit 从不修改子元素自身的 props,子元素规则位于基础级联层中,因此后面的层、非分层 CSS 以及内联子元素样式优先。 当前源代码、测试和浏览器测试
FR5 fit 不会反映在主题目标上。 当前源代码和测试
FR6 ref 到达比例盒子。受支持的 DOM、ARIA、data 和事件 props 到达比例盒子;xstyle、className 和 style 按该顺序在组件样式之后合并。 当前源代码和测试

允许的变化

  • AV1 — 响应式比例。 调用方可以通过 CSS 按断点或容器大小更改比例,而无需更改组件。
  • AV2 — 主题绘制。 主题可以按 shape 重新设置 aspect-ratio 的样式。

代表性状态

状态 必需的不变量 允许的变化
矩形,无 fit 盒子位于 ratio;子元素在完整尺寸插槽内未设置样式。 比例。
椭圆形,cover 椭圆形裁剪;媒体填充并裁剪。 比例。
Contain 媒体填充并留信箱黑边。 —
Center 子元素以自然大小居中。 —
调用方覆盖 调用方的 aspect-ratio 规则或内联样式优先于 ratio。 断点。

变换和优先级顺序

  • ORD1 — 比例。 组件类 aspect-ratio → xstyle → 非分层调用方 CSS → 内联 style。
  • ORD2 — 子元素尺寸。 基础层中的 fit 规则 → 后面的层、非分层 CSS 以及内联子元素样式。

性能和资源

  • PR1 — 仅使用 CSS。 AspectRatio 不持有状态,不进行任何测量;布局由 CSS 解析。

可访问性契约

  • AR1 — 不添加语义。 比例盒子和内容插槽不添加任何角色或名称;子元素的语义原样传递。

设计关系

结构或状态 设计需求 表示权威 层级角色 组件契约
比例盒子 持有比例、裁剪溢出并承载形状。 当前源代码和文档 支持 FR1, FR2, FR5
内容插槽 填充盒子并定位或调整子元素大小。 当前源代码和文档 支持 FR3, FR4

主题结构

{
  "Ratio box": {"target": "aspect-ratio"},
  "Content slot": {"inherits": "aspect-ratio"}
}

家族和系统关系

  • architecture:public-component-api 拥有 ref、透传和样式输入规则;FR1 和 FR6 将它们应用于比例盒子。
  • architecture:component-theming-surface 拥有目标限定;FR5 将结构性的 fit 轴排除在目标之外。

验证映射

契约 验证 代表性状态 变异或失败预期 审计章节
------------------- ----------------------------------------------------------------------------------------------- ----------------------------------- --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ----------------------------
FR1, FR2, FR6 AspectRatio.test.tsx 的 ratio、shape、ref、passthrough 与 merge 测试;稳定视觉基线 多种 ratio、椭圆、覆盖项 内联 ratio、丢失的内联 style 覆盖、丢失的 data-shape 反射、丢失的 ref,或丢弃的调用方 prop 均会导致失败。稳定视觉基线 core-aspectratio--default(16:9、cover)与 core-aspectratio--with-placeholder-skeleton(探针主题)若返回的盒子发生变化,则需审查。差距:没有任何单元测试断言全宽、裁剪、零最小高度、禁止收缩规则、椭圆的 50% 半径,或 xstyle 的 aspectRatio 优先于 ratio;两条基线既不溢出盒子,也不加载默认 story 的远程图片,因此裁剪和 cover 填充没有视觉检查;基线也未渲染椭圆或 flex 宿主。 audit:AspectRatio/layout
FR3–FR5 AspectRatio.test.tsx fit 套件 Cover、contain、center、unset 未设置的 fit 出现标记、子元素 className 或内联 objectFit 被改动、包装元素缺少 fill、cover、contain 或 center 样式,或目标元素上带有 fit,均会导致失败。差距:单元测试只检查包装元素携带哪些样式,而不检查这些样式的声明(子元素尺寸、object-fit、居中),并且遗漏了添加到子元素上的 props,或合并到子元素自身 style 下的尺寸设定;slot 的 inline-start 锚定没有自动化检查;浏览器级联测试覆盖 cover 和 contain 的尺寸及 object-fit,但不覆盖 center。 audit:AspectRatio/layout
FR4 (cascade) AspectRatioFitLayers.a11y.browser.spec.ts Tailwind v3 与 v4 的 layer 配置 若有 preflight 规则压过 fit 的尺寸调整,在真实浏览器中会失败。 audit:AspectRatio/layout
Theming anatomy map scripts/check-knowledge.mjs 使用方 anatomy 与当前目标 缺失、多余或过期的映射会使仓库校验失败。 audit:AspectRatio/theming
AR1, PR1 源码审查 所有状态 差距:如果 AspectRatio 增加语义、状态或测量,没有任何自动化检查会失败。 audit:AspectRatio/behavior

决策日志

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

未决问题

无。

内容边界

本文件不重复消费者 prop 表/示例、当前审计 结果、实施步骤或族/系统规则。它将链接到这些内容的所有者。

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