AspectRatio
保持媒体或预览画布比例。中文惯用名：宽高比。
稳定本期新增已接入
元信息
| 字段 | 值 |
|---|---|
| 规范 ID | component.aspect-ratio |
| 名称 | AspectRatio |
| 二级分类 | 布局（layout） |
| 用途 | 保持媒体或预览画布比例 |
| 描述 | 中文惯用名：宽高比。 |
预览
静态结构：纯 CSS 实现（data-slot="aspect-ratio"，class w-full overflow-hidden），ratio 经 inline style aspectRatio: String(ratio) 写入（数字 16/9 或字符串 "16/9" 均可，缺省 1）；宽度由父容器决定、高度按比例推导；子内容不会自动拉伸——需要填满时内容自身声明 width / height 100%（如 Image 的 width / height 或 className）。
DSL 结构
{
"type": "AspectRatio",
"props": {
"ratio": "16/9"
},
"children": [
{
"type": "Image",
"props": {
"src": "https://example.com/cover.png",
"alt": "封面图",
"preview": false
}
}
]
}何时用
何时使用
- 保持媒体或预览画布比例：视频封面、图片缩略图、地图 / 画布容器。
- 需要固定比例占位：内容加载前先按比例撑出骨架，避免加载后布局跳动。
- 图片列表需要统一视觉节奏：每格同比例裁切。
何时不用
- 高度由内容自然决定的文本块：不需要比例容器。
- 需要按容器宽度自适应列数 / 尺寸的栅格：使用 Grid。
- 需要用户拖拽调整尺寸：使用 Splitter / Resizable。
变体
| 变体 | 视觉形态 | 适用场景 |
|---|---|---|
| 16 / 9 | 宽屏画布 | 视频封面、演示区、横幅 |
| 4 / 3 | 经典画幅 | 传统图片、幻灯片预览 |
| 1 / 1（缺省） | 正方形 | 头像墙、商品图网格、图表画布 |
| 自定义比例 | 数字或 "21/9" 等字符串 | 超宽 banner、特殊媒体规格 |
API 属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
ratio | `number | string` | 1 |
children | DslNode[] | — | 容器内容（DSL 子树；需自行填满容器才被比例约束） |
className / style | string / CSSProperties | — | 通用：根节点 class 合并 / 内联样式 |
使用规范
- 同一列表内的比例保持一致，混排比例会让网格看起来错位。
- 内容必须显式填满容器（宽高 100% 或 object-cover），否则比例只约束容器、不约束内容。
- 比例容器外再设最大宽度（如 max-w）以控制整体尺寸，AspectRatio 只管比例。
- 图片类内容配合 preview / object-cover 使用，避免非等比拉伸导致变形。
正例
- ✓ 课程卡片：AspectRatio ratio="16/9" 内放封面 Image，卡片高度一致。
- ✓ 图表画布：AspectRatio ratio={1} 内放 Chart，按容器宽度自动定高。
反例
- ✕ 给 AspectRatio 内容不设宽高，却期望它自动铺满（内容会按自身尺寸渲染）。
- ✕ 用 AspectRatio 表达固定像素宽高（直接用 style width / height 更直白）。
Design Token 映射
不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。