실험적 반응형 이미지

타입: boolean
기본값: false

추가된 버전: astro@5.0.0

프로젝트에서 자동 반응형 이미지 지원을 활성화합니다.

반응형 이미지라는 용어는 다양한 기기에서 잘 작동하는 이미지를 의미합니다. 이는 특히 컨테이너에 맞춰 크기가 조절되는 이미지와 기기의 화면 크기 및 해상도에 따라 다른 크기로 제공될 수 있는 이미지에 적용됩니다.

이미지가 표시되는 방식을 제어하기 위해 설정할 수 있는 여러 추가 속성이 있지만, 이러한 속성을 수동으로 직접 처리하는 것은 복잡할 수 있습니다. 이러한 속성을 잘못 처리하면 다운로드 속도가 느려지거나 이미지가 올바르게 표시되지 않을 수 있습니다. 이는 Core Web Vitals 및 Lighthouse 성능 점수가 낮게 측정되는 가장 흔한 원인 중 하나입니다.

이 플래그가 활성화되면 Astro는 이미지에 필요한 srcset 및 sizes 값을 자동으로 생성하고, 올바르게 크기가 조정되도록 적절한 스타일을 적용할 수 있습니다. 이 동작은 전역적으로 또는 이미지별로 구성할 수 있습니다.

해당 기능을 활성화하려면 먼저 astro.config.mjs 파일에 responsiveImages 플래그를 추가하세요.

{
  experimental: {
    responsiveImages: true,
  },
}

기본적으로 이 플래그를 활성화해도 아무것도 변경되지 않지만, 전역적으로 또는 이미지별로 이미지 레이아웃을 설정하여 반응형 이미지를 구성할 수 있습니다.

이를 수행하기 위해 Astro에서 처리되고 최적화되는 모든 이미지의 기본 동작을 제어하는 추가적인 image 구성 설정에 접근할 수 있습니다.

Markdown의 ![]() 구문을 사용하는 로컬 및 원격 이미지
<Image /> 및 <Picture /> 컴포넌트

또한 Astro의 이미지 컴포넌트는 이미지별로 이러한 기본값을 재정의하기 위해 반응형 이미지 props를 받을 수 있습니다.

public/ 폴더의 이미지는 절대 최적화되지 않으며, 반응형 이미지는 지원되지 않습니다.

이미지 레이아웃

올바른 srcset 및 sizes 속성을 생성하기 위해 <Image /> 및 <Picture /> 컴포넌트는 컨테이너 크기가 변경될 때 이미지의 크기가 어떻게 조정되어야 하는지 알아야 합니다. 이는 layout prop 또는 image.experimentalLayout 기본값을 설정하여 수행됩니다. 지원되는 값은 다음과 같습니다.

constrained: 이미지는 비율을 유지하면서 컨테이너에 맞게 축소되지만, 지정된 width 및 height 또는 이미지의 원래 크기 이상으로 확대되지는 않습니다. 가능한 경우 요청된 크기로 이미지를 표시하되, 작은 화면에 맞춰 축소하고 싶을 때 사용하세요. 이는 Tailwind를 사용할 때 이미지의 기본 동작과 일치합니다. 확실하지 않은 경우 이 레이아웃을 선택하는 것이 좋습니다.
full-width: 이미지는 비율을 유지하면서 컨테이너의 너비에 맞게 확대됩니다. 페이지의 전체 너비를 차지하는 히어로 이미지 또는 기타 이미지에 사용하세요.
fixed: 이미지는 요청된 크기를 유지하고 조정되지 않습니다. 고밀도 디스플레이를 지원하기 위한 srcset은 생성하지만, 다른 화면 크기에 대한 srcset은 생성하지 않습니다. 화면 너비보다 작은 아이콘이나 로고, 또는 고정 너비 컨테이너의 다른 이미지와 같이 이미지 크기가 조정되지 않을 경우에 사용하세요.
none: 이미지는 반응형으로 처리되지 않습니다. srcset 또는 sizes가 자동으로 생성되지 않으며, 스타일도 적용되지 않습니다. 기본 레이아웃을 활성화했지만 특정 이미지에 대해 비활성화하고 싶을 때 유용합니다.

선택한 layout은 이미지에 대한 올바른 srcset 및 sizes 속성을 생성하는 데 사용되며, 해당 <img> 태그에 적용되는 기본 스타일을 정의합니다.

구성 설정

프로젝트 전체에서 반응형 이미지를 활성화하려면 image.experimentalLayout에 기본값을 설정하세요.

이 값이 구성되지 않은 경우에도 <Image /> 또는 <Picture /> 컴포넌트에 layout prop을 전달하여 반응형 이미지를 만들 수 있습니다. 그러나 Markdown 이미지는 반응형이 되지 않습니다.

기본적으로 처리된 모든 이미지에 적용되는 image.experimentalObjectFit 및 image.experimentalObjectPosition을 선택적으로 구성할 수 있습니다.

이러한 각 설정은 prop을 사용하여 개별 <Image /> 또는 <Picture /> 컴포넌트에서 재정의할 수 있지만, Markdown 이미지는 항상 기본 설정을 사용합니다.

{
  image: {
    // 모든 Markdown 이미지에 사용되며, 이미지별로 구성할 수 없습니다.
    // prop으로 재정의되지 않는 한 모든 `<Image />` 및 `<Picture />` 컴포넌트에 사용됩니다.
    experimentalLayout: 'constrained',
  },
  experimental: {
    responsiveImages: true,
  },
}

반응형 이미지 속성

반응형 이미지가 활성화되었을 때 <Image /> 및 <Picture /> 컴포넌트에서 사용할 수 있는 추가 속성들입니다:

layout: 이미지의 레이아웃 유형입니다. constrained, fixed, full-width 또는 none이 될 수 있습니다. none으로 설정하면 이 이미지에 대한 반응형 동작이 비활성화되고 다른 모든 옵션은 무시됩니다. 기본값은 none이거나, image.experimentalLayout이 설정된 경우 해당 값입니다.
fit: 종횡비가 변경될 때 이미지를 어떻게 자를지 정의합니다. CSS object-fit의 값들과 일치합니다. 기본값은 cover이며, image.experimentalObjectFit이 설정된 경우 해당 값이 사용됩니다.
position: 종횡비가 변경될 때 이미지 자르기 위치를 정의합니다. CSS object-position의 값들과 일치합니다. 기본값은 center이며, image.experimentalObjectPosition이 설정된 경우 해당 값이 사용됩니다.
priority: 설정된 경우, 이미지를 즉시 로드합니다. 그렇지 않으면 이미지는 지연 로드됩니다. 첫 화면에서 가장 큰 이미지에 이 속성을 사용하세요. 기본값은 false입니다.

widths와 sizes 속성은 이미지의 크기와 레이아웃 타입을 기반으로 자동 생성되며, 대부분의 경우 수동으로 설정할 필요가 없습니다. constrained와 full-width 이미지에 대해 생성된 sizes 속성은 뷰포트가 이미지 너비보다 작을 때 이미지가 화면 전체 너비에 가깝게 표시된다는 가정을 기반으로 합니다. 만약 이것이 상당히 다른 경우(예: 작은 화면에서 다중 열 레이아웃인 경우) 최상의 결과를 위해 sizes 속성을 수동으로 조정해야 할 수 있습니다.

densities 속성은 반응형 이미지와 호환되지 않으며 설정하더라도 무시됩니다.

예를 들어 constrained를 기본 레이아웃으로 설정한 경우, 개별 이미지의 layout 속성을 재정의할 수 있습니다.

---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png';
---
<Image src={myImage} alt="반응형 레이아웃을 사용합니다." width={800} height={600} />
<Image src={myImage} alt="전체 너비 레이아웃을 사용합니다." layout="full-width" />
<Image src={myImage} alt="반응형 이미지를 비활성화합니다." layout="none" />

반응형 이미지 HTML 생성 결과

레이아웃이 기본적으로 또는 개별 컴포넌트에서 설정되면, 이미지는 크기와 레이아웃 유형에 따라 자동으로 생성된 srcset 및 sizes 속성을 갖게 됩니다. constrained 및 full-width 레이아웃을 가진 이미지는 컨테이너에 따라 크기가 조정되도록 스타일이 적용됩니다.

---
import { Image, Picture } from 'astro:assets';
import myImage from '../assets/my_image.png';
---
<Image src={myImage} alt="A description of my image." layout='responsive' width={800} height={600} />
<Picture src={myImage} alt="A description of my image." layout='full-width' formats={['avif', 'webp', 'jpeg']} />

이 <Image /> 컴포넌트는 다음과 같은 HTML 출력을 생성할 것입니다:

<img
  src="/_astro/my_image.hash3.webp"
  srcset="/_astro/my_image.hash1.webp 640w,
      /_astro/my_image.hash2.webp 750w,
      /_astro/my_image.hash3.webp 800w,
      /_astro/my_image.hash4.webp 828w,
      /_astro/my_image.hash5.webp 1080w,
      /_astro/my_image.hash6.webp 1280w,
      /_astro/my_image.hash7.webp 1600w"
  alt="A description of my image"
  sizes="(min-width: 800px) 800px, 100vw"
  loading="lazy"
  decoding="async"
  fetchpriority="auto"
  width="800"
  height="600"
  style="--fit: cover; --pos: center;"
  data-astro-image="constrained"
>

이미지 스타일 재정의

반응형 이미지 컴포넌트는 크기를 올바르게 조정하기 위해 몇 가지 스타일을 적용합니다. 적용되는 스타일은 레이아웃 유형에 따라 다르며, 생성된 srcset 및 sizes 속성에 최적의 동작을 제공하도록 설계되었습니다. 기본 스타일은 다음과 같습니다.

:where([data-astro-image]) {
  object-fit: var(--fit);
  object-position: var(--pos);
}
:where([data-astro-image='full-width']) {
  width: 100%;
}
:where([data-astro-image='constrained']) {
  max-width: 100%;
}

<Image /> 또는 <Picture /> 컴포넌트의 fit 및 position props를 설정하여 object-fit 및 object-position 스타일을 재정의할 수 있습니다.

해당 스타일은 특이성이 0인 :where() 가상 클래스를 사용합니다. 이는 사용자 정의 스타일로 쉽게 재정의할 수 있음을 의미합니다. 모든 클래스나 태그 이름은 :where()보다 높은 특이성을 가지므로, 이미지에 사용자 정의 클래스 또는 태그 이름을 추가하여 스타일을 쉽게 재정의할 수 있습니다.

Tailwind 4는 캐스케이드 레이어를 사용하기 때문에 특별한 경우입니다. 즉, 레이어를 사용하지 않는 규칙보다 Tailwind 규칙의 특이성이 항상 낮습니다. Astro는 캐스케이드 레이어를 지원하지 않는 브라우저를 지원하므로 이미지에 이를 사용할 수 없습니다. 따라서 Tailwind 4를 사용하여 스타일을 재정의해야 하는 경우 !important 수정자를 사용해야 합니다.

전체적인 개요를 확인하고 이 실험적인 API에 대한 피드백을 제공하려면 반응형 이미지 RFC를 참조하세요.

기여하기 커뮤니티 후원하기