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 |
主题结构¶
家族和系统关系¶
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