宽高比容器 · AspectRatio

宽高比容器用于布局场景。下面的官方示例展示原生用法与状态，属性名保持上游 API。

安装与前置条件

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见开始使用。

示例与使用方式

宽高比容器 · 综合展示 1：首先体验这个示例，再查看代码理解组件的组合方式。
宽高比容器 · 交互示例 2：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
宽高比容器 · 交互示例 3：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
宽高比容器 · 交互示例 4：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
宽高比容器 · 交互示例 5：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
宽高比容器 · 交互示例 6：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

API 与上游详细参考

优先使用 0.7.1 官方中文说明；上游尚未提供中文的条目保留英文。属性名、类型及默认值保持原生 API，不把示例状态名称当成组件属性。

Aspect Ratio

Maintains a fixed width-to-height ratio for its children as its container resizes. Use it for media containers like videos, images, thumbnails, or any content that needs consistent proportions. It takes its width from the container and derives its height from the ratio, so it needs an ancestor with a definite width.

属性	类型	默认值	说明
ratio *	number		宽高比，以宽/高表示（例如 16/9、1）。以类级声明输出（非内联样式），可通过 `xstyle` 规则或未分层的（unlayered）消费者 CSS 做响应式覆盖。
shape	'rectangle' \| 'ellipse'	'rectangle'	容器形状。两种形状都遵循 `ratio`。`ellipse` 裁剪为椭圆（`ratio={1}` 时为正圆）。
fit	'cover' \| 'contain' \| 'center'		子元素在比例框内的布局方式。`cover` 填满并裁剪媒体，`contain` 填满并留边，`center` 保持原始尺寸居中。省略时子元素自行设置样式。
children *	ReactNode		通过绝对定位填充容器的内容。
xstyle	StyleXStyles		用于布局自定义的 StyleX 样式（外边距、定位、尺寸）。必须是 stylex.create() 的值，而不是像 style={{}} 这样的内联样式对象。

使用建议

Express the ratio as a fraction for readability — ratio={16 / 9} rather than ratio={1.78}. It is a number, so the string form ratio="16/9" is a type error.
Use for media that needs consistent proportions across screen sizes.
Use fit="cover" for images and video so the component sizes the child; the child should not repeat width/height/objectFit styles.
Pass one child. With fit set, every direct child is stretched to fill the box, so put an overlay or caption inside a single wrapper child rather than passing it as a second child.
Describe media children with alt, or alt="" when the image is decorative. AspectRatio adds no role and no accessible name of its own, so the child carries the whole accessible description.
For a breakpoint-dependent ratio, override the ratio responsively: pass an aspectRatio rule via xstyle (StyleX), or override aspect-ratio from your own unlayered CSS under a @media/@container rule; component styles live in the astryx-base cascade layer, so unlayered consumer CSS wins. Give an xstyle rule a default branch alongside the conditional one ({default: 3, '@container ...': '3 / 2'}); with only the conditional branch the ratio is unset outside the query and the box collapses.
避免：Use for general layout containers; use standard layout components instead.
避免：Nest AspectRatio containers; one level is sufficient.
避免：Constrain the height on its own. The width comes from the container, so a height or maxHeight by itself clamps the box off ratio; pair it with width: "auto" to size from the height instead.
避免：Place it in a shrink-to-fit parent such as inline-flex, width: fit-content or a floated box. It contributes no intrinsic width there and collapses to zero.

主题 API

{
  "targets": [
    {
      "className": "astryx-aspect-ratio",
      "visualProps": [
        "shape"
      ]
    }
  ]
}

组件结构

Ratio box: The outer element that holds the aspect ratio and clips overflow. Carries the astryx-aspect-ratio theme target, and the elliptical clip when shape is ellipse.
Content slot: A wrapper that fills the ratio box and positions the child. With fit set it also sizes the child; without it the child styles itself.