比例調整

比例調整元件會調整其內容大小以符合所需的比例。

簡介

比例調整是一個包裝元件，用於快速調整內容大小，使其符合您偏好的寬高比。媒體內容（如圖片）可以根據 CSS object-fit 屬性進行拉伸、調整大小和裁剪。

基本用法

import AspectRatio from '@mui/joy/AspectRatio';

比例調整元件會包裝要調整大小的內容。要調整大小的元素必須是第一個直接子元素。預設比例為 16/9。

16/9

<AspectRatio sx={{ width: 300 }}>
  <Typography level="h2" component="div">
    16/9
  </Typography>
</AspectRatio>

<AspectRatio sx={{ width: 300 }}>
  <Typography level="h2" component="div">
    16/9
  </Typography>
</AspectRatio>

按下 Enter 開始編輯

客製化

變體

比例調整元件支援 Joy UI 的四種全域變體：solid、soft（預設）、outlined 和 plain。

Solid

Soft

Outlined

Plain

比例

使用 ratio 屬性來變更寬高比，遵循 width/height 模式。例如，以下示範使用 4/3 的比例，這是預設 16/9 的常見替代方案

4/3

<AspectRatio
  variant="outlined"
  ratio="4/3"
  sx={{ width: 300, bgcolor: 'background.level2', borderRadius: 'md' }}
>
  <Typography level="h2" component="div">
    4/3
  </Typography>
</AspectRatio>

<AspectRatio
  variant="outlined"
  ratio="4/3"
  sx={{ width: 300, bgcolor: 'background.level2', borderRadius: 'md' }}
>
  <Typography level="h2" component="div">
    4/3
  </Typography>
</AspectRatio>

按下 Enter 開始編輯

物件 fit

當比例調整元件內的內容是圖片或影片時，您可以使用 objectFit 屬性來控制其調整大小的方式。

此屬性讓您可以存取與 CSS object-fit 屬性相關聯的所有值：cover（預設）、contain、fill、scaleDown、initial、inherit 和 none。

<AspectRatio objectFit="contain">
  <img
    src="https://images.unsplash.com/photo-1502657877623-f66bf489d236?auto=format&fit=crop&w=800"
    srcSet="https://images.unsplash.com/photo-1502657877623-f66bf489d236?auto=format&fit=crop&w=800&dpr=2 2x"
    alt="A beautiful landscape."
  />
</AspectRatio>

<AspectRatio objectFit="contain">
  <img
    src="https://images.unsplash.com/photo-1502657877623-f66bf489d236?auto=format&fit=crop&w=800"
    srcSet="https://images.unsplash.com/photo-1502657877623-f66bf489d236?auto=format&fit=crop&w=800&dpr=2 2x"
    alt="A beautiful landscape."
  />
</AspectRatio>

按下 Enter 開始編輯

媒體預留位置

當沒有提供媒體內容時，使用 <div> 或與圖示配對的 Box 元件作為後備方案

標題

卡片的描述。

<Card variant="outlined" sx={{ width: 300 }}>
  <AspectRatio>
    <div>
      <ImageIcon sx={{ fontSize: '3rem', opacity: 0.2 }} />
    </div>
  </AspectRatio>
  <div>
    <Typography level="title-md">Title</Typography>
    <Typography level="body-sm">Description of the card.</Typography>
  </div>
</Card>

<Card variant="outlined" sx={{ width: 300 }}>
  <AspectRatio>
    <div>
      <ImageIcon sx={{ fontSize: '3rem', opacity: 0.2 }} />
    </div>
  </AspectRatio>
  <div>
    <Typography level="title-md">Title</Typography>
    <Typography level="body-sm">Description of the card.</Typography>
  </div>
</Card>

按下 Enter 開始編輯

最小和最大高度

使用 minHeight 和 maxHeight 屬性來設定內容高度的下限和上限。當比例調整元件包裝動態寬度內容時，這非常有用，如下面的示範所示

<AspectRatio minHeight={120} maxHeight={200}>
  <img
    src="https://images.unsplash.com/photo-1502657877623-f66bf489d236?auto=format&fit=crop&w=800"
    srcSet="https://images.unsplash.com/photo-1502657877623-f66bf489d236?auto=format&fit=crop&w=800&dpr=2 2x"
    alt=""
  />
</AspectRatio>

<AspectRatio minHeight={120} maxHeight={200}>
  <img
    src="https://images.unsplash.com/photo-1502657877623-f66bf489d236?auto=format&fit=crop&w=800"
    srcSet="https://images.unsplash.com/photo-1502657877623-f66bf489d236?auto=format&fit=crop&w=800&dpr=2 2x"
    alt=""
  />
</AspectRatio>

按下 Enter 開始編輯

在彈性容器列中使用

當比例調整元件是彈性容器 row 的子元件時，使用 flex-basis 來設定內容的理想寬度

優勝美地國家公園

美國加州

flexBasis

預設情況下，比例調整元件將保留提供的寬高比。如果您希望比例調整元件填滿垂直空間，請將 flex 屬性設定為 true

Flex

21 / 9

2023 年 4 月 20 日

小工具標題

Lorem ipsum 是圖形中常用的預留位置文字。

與 Next.js Image 搭配使用

比例調整元件可以與 Next.js Image 元件作為子元件一起使用。Image 應始終包含 layout="fill" 屬性—否則它需要 height 和 width 值，這會破壞比例調整元件的目的。

import Image from 'next/image';
import AspectRatio from '@mui/joy/AspectRatio';
import mountains from '../public/mountains.jpg';

function App() {
  return (
    <AspectRatio variant="outlined" ratio="1" objectFit="cover">
      {/* only layout="fill" makes sense for using with AspectRatio */}
      <Image alt="Mountains" src={mountains} layout="fill" placeholder="blur" />
    </AspectRatio>
  );
}

與圖示一起使用

比例調整元件可以是建立圖示正方形容器的便利工具。

常見範例

行動裝置輪播

在此類設計中，請務必指定 minWidth 值，以防止比例調整元件縮小。

夜景

421 萬次觀看

湖景

474 萬次觀看

山景

398 萬次觀看

{data.map((item) => (
  <Card orientation="horizontal" size="sm" key={item.title} variant="outlined">
    <AspectRatio ratio="1" sx={{ minWidth: 60 }}>
      <img
        srcSet={`${item.src}?h=120&fit=crop&auto=format&dpr=2 2x`}
        src={`${item.src}?h=120&fit=crop&auto=format`}
        alt={item.title}
      />
    </AspectRatio>
    <Box sx={{ whiteSpace: 'nowrap', mx: 1 }}>
      <Typography level="title-md">{item.title}</Typography>
      <Typography level="body-sm">{item.description}</Typography>
    </Box>
  </Card>
))}

{data.map((item) => (
  <Card orientation="horizontal" size="sm" key={item.title} variant="outlined">
    <AspectRatio ratio="1" sx={{ minWidth: 60 }}>
      <img
        srcSet={`${item.src}?h=120&fit=crop&auto=format&dpr=2 2x`}
        src={`${item.src}?h=120&fit=crop&auto=format`}
        alt={item.title}
      />
    </AspectRatio>
    <Box sx={{ whiteSpace: 'nowrap', mx: 1 }}>
      <Typography level="title-md">{item.title}</Typography>
      <Typography level="body-sm">{item.description}</Typography>
    </Box>
  </Card>
))}

按下 Enter 開始編輯

列表堆疊

這是一個如何將比例調整與列表元件搭配使用的簡單說明

夜景
421 萬次觀看
湖景
474 萬次觀看
山景
398 萬次觀看

解剖結構

比例調整元件由一個根 <div> 和一個巢狀在內部的內容 <div> 組成；子元件會被賦予一個 data-first-child 屬性以用於樣式設定

<div class="MuiAspectRatio-root">
  <div class="MuiAspectRatio-content">
    <some-element data-first-child>
      <!-- Aspect Ratio contents -->
    </some-element>
  </div>
</div>

API

請參閱以下文件，以取得此處提及之元件的所有屬性和類別的完整參考。

<AspectRatio />