React Bootstrap logoReact Bootstrap

Ratio

基础布局

基于 Bootstrap 5 的宽高比容器组件，为图片、视频、iframe 等媒体内容提供固定比例的响应式容器，支持四种预设比例与数字、字符串自定义比例，并可渲染为任意语义化元素

Component Demo

Basic usage and examples of the Ratio component

基础用法

16:9 宽屏图片

子元素会被绝对定位并拉伸铺满容器，图片配合 `object-fit-cover` 即可在保持比例的同时裁切铺满，容器高度由宽度与比例自动决定

预设比例

1x1
4x3
16x9
21x9

内置 1x1、4x3、16x9、21x9 四种预设，分别渲染 `ratio-1x1`、`ratio-4x3`、`ratio-16x9`、 `ratio-21x9` 类，对应 100%、75%、56.25%、42.857% 的 padding-top

自定义数字比例

9 / 16
0.75
2（竖屏）

传入数字时写入 `--bs-aspect-ratio` 内联变量：小于 1 视为小数百分比（9 / 16 → 56.25%），大于等于 1 视为整数百分比（2 → 200%，即 1:2 竖屏比例），小于等于 0 时回退为 100%

自定义字符串比例

4x5

任意字符串会直接生成 `ratio-<aspectRatio>` 类，只需在自定义样式表中为该类设置 `--bs-aspect-ratio` 即可扩展比例；未定义时回退为默认的 100%

视频嵌入

嵌入视频是比例容器最常见的场景，iframe 随容器宽度缩放并保持 16:9 比例

图片网格

山间风景
城市街景

在网格中组合 `rounded` 与 `overflow-hidden`，即可得到统一比例、圆角裁切的图片卡片

自定义元素

示例图片
as="section"

通过 as 渲染为 figure、section 等语义化元素，在保留比例行为的同时提升页面语义

交互演示

16x9

API Documentation

Complete API reference for the Ratio component

Props

属性名类型默认值描述
asElementType'div'渲染的根元素类型，默认渲染 `div`，可传入 `figure`、`section` 等语义化元素或自定义组件
aspectRatioRatioAspectRatio | number'1x1'宽高比：预设字符串渲染 `ratio-*` 类；任意字符串生成 `ratio-<aspectRatio>` 类，可配合自定义 CSS 使用；数字则写入 `--bs-aspect-ratio` 变量——小于 1 时按小数百分比处理（0.75 → 75%），大于等于 1 时按整数百分比处理（2 → 200% 竖屏比例），小于等于 0 时回退为 100%
childrenReactNode-唯一子元素，会被绝对定位并拉伸铺满整个容器，通常传入 `img`、`iframe`、`video` 等媒体元素
classNamestring-自定义类名，可组合 `bg-*`、`rounded`、`overflow-hidden` 等工具类调整容器外观
...restHTMLAttributes<HTMLElement>-根元素的所有原生属性（如 `style`、`id` 等）；数字比例时 `style` 会与 `--bs-aspect-ratio` 合并

Type Definitions

RatioAspectRatio

宽高比类型，四个预设比例或任意自定义字符串

export type RatioAspectRatio = '16x9' | '1x1' | '21x9' | '4x3' | ({} & string);

RatioProps

比例容器组件属性接口

export interface RatioProps extends HTMLAttributes<HTMLElement> {
  as?: ElementType;
  aspectRatio?: number | RatioAspectRatio;
  children?: ReactNode;
  className?: string;
}