이미지 및 자산 API 참조
추가된 버전:
astro@3.0.0
Astro는 최적화된 이미지를 표시하기 위한 기본 컴포넌트와 도우미 함수를 제공합니다. 기능 및 사용 예시는 이미지 가이드를 참조하세요.
astro:assets
에서 가져오기
섹션 제목: astro:assets에서 가져오기import { Image, Picture, getImage, inferRemoteSize, } from 'astro:assets';
<Image />
섹션 제목: <Image /><Image />
컴포넌트는 이미지를 최적화하고 변환합니다.
이 컴포넌트는 컨테이너 크기 또는 기기 화면의 크기와 해상도에 따라 조정할 수 있는 반응형 이미지를 만드는 데도 사용할 수 있습니다.
---// Image 컴포넌트 및 이미지 가져오기import { Image } from 'astro:assets';import myImage from "../assets/my_image.png"; // 1600x900의 이미지---
<!-- Image 컴포넌트에서는 'alt'가 필수입니다. --><Image src={myImage} alt="A description of my image." />
<!-- 결과 --><!-- 이미지가 최적화되었으며 적절한 속성이 적용되었습니다. --><img src="/_astro/my_image.hash.webp" width="1600" height="900" decoding="async" loading="lazy" alt="A description of my image."/>
Image 속성
섹션 제목: Image 속성<Image />
컴포넌트는 HTML의 <img>
태그가 허용하는 모든 속성 외에도 다음에 나열된 속성과 반응형 이미지 속성을 허용합니다.
src (필수)
섹션 제목: src (필수)타입: ImageMetadata | string | Promise<{ default: ImageMetadata }>
이미지 파일의 src
값 형식은 이미지 파일의 위치에 따라 다릅니다.
-
src/
의 로컬 이미지 - 상대 파일 경로를 사용하여 이미지도 가져오거나 가져오기 별칭을 구성하고 사용해야 합니다. 그런 다음 가져오기 이름을src
값으로 사용합니다.src/pages/index.astro ---import { Image } from 'astro:assets';import myImportedImage from '../assets/my-local-image.png';---<Image src={myImportedImage} alt="descriptive text" /> -
public/
폴더의 이미지 - 이미지의 public 폴더에 상대적인 파일 경로 사용:src/pages/index.astro ---import { Image } from 'astro:assets';---<Imagesrc="/images/my-public-image.png"alt="descriptive text"width="200"height="150"/> -
원격 이미지 - 이미지의 전체 URL을 속성 값으로 사용합니다.
src/pages/index.astro ---import { Image } from 'astro:assets';---<Imagesrc="https://example.com/remote-image.jpg"alt="descriptive text"width="200"height="150"/>
alt (필수)
섹션 제목: alt (필수)타입: string
이미지에 대한 설명 대체 텍스트 문자열을 제공하려면 필수 alt
속성을 사용하세요.
이미지가 단지 장식용인 경우 (즉, 페이지 이해에 도움이 되지 않는 경우) alt=""
를 설정하여 화면 판독기 및 기타 보조 기술이 이미지를 무시하도록 알립니다.
width 및 height (public/
의 이미지에 필요)
섹션 제목: width 및 height (public/의 이미지에 필요)타입: number | undefined
이러한 속성은 이미지에 사용할 크기를 정의합니다.
layout
유형이 설정되면, 이미지의 크기에 따라 이 값들이 자동으로 생성되므로 대부분의 경우 수동으로 설정하지 않아도 됩니다.
이미지를 원본 가로세로 비율로 사용하는 경우 width
및 height
는 선택사항입니다. 이러한 크기는 src/
에 있는 이미지 파일에서 자동으로 유추할 수 있습니다. 원격 이미지의 경우 <Image />
또는 <Picture />
컴포넌트의 inferSize
속성을 true
로 설정하거나 inferRemoteSize()
함수를 사용하세요.
그러나 Astro는 이러한 파일을 분석할 수 없으므로 public/
폴더에 저장된 이미지에는 이 두 속성이 모두 필요합니다.
densities
섹션 제목: densities타입: (number | `${number}x`)[] | undefined
astro@3.3.0
이미지에 대해 생성할 픽셀 밀도 목록입니다.
densities
속성은 layout
속성을 사용하는 반응형 이미지와 호환되지 않으며 설정된 경우 무시됩니다.
제공된 경우 이 값은 <img>
태그에 srcset
속성을 생성하는 데 사용됩니다. 이 값을 사용할 때 widths
값을 제공하지 마세요.
이미지 크기가 커지는 것을 방지하기 위해 원본 이미지보다 더 큰 너비와 동일한 밀도는 무시됩니다.
---import { Image } from 'astro:assets';import myImage from '../assets/my_image.png';---<Image src={myImage} width={myImage.width / 2} densities={[1.5, 2]} alt="A description of my image."/>
<!-- 출력 --><img src="/_astro/my_image.hash.webp" srcset=" /_astro/my_image.hash.webp 1.5x /_astro/my_image.hash.webp 2x " alt="A description of my image." width="800" height="450" loading="lazy" decoding="async"/>
widths
섹션 제목: widths타입: number[] | undefined
astro@3.3.0
이미지에 대해 생성할 너비 목록입니다.
제공된 경우 이 값은 <img>
태그에 srcset
속성을 생성하는 데 사용됩니다. sizes
속성도 제공해야 합니다.
layout
속성을 사용하는 반응형 이미지는 widths
및 sizes
속성을 자동으로 생성합니다. 일반적으로 이러한 값을 제공할 필요는 없지만 자동으로 생성된 값을 재정의하는 데 사용할 수 있습니다.
이 값을 사용할 때는 densities
값을 제공하지 마세요. 이 두 값 중 하나만 사용하여 srcset
을 생성할 수 있습니다.
이미지 크기가 커지는 것을 방지하기 위해 원본 이미지보다 큰 너비는 무시됩니다.
---import { Image } from 'astro:assets';import myImage from '../assets/my_image.png'; // 1600x900의 이미지---<Image src={myImage} widths={[240, 540, 720, myImage.width]} sizes={`(max-width: 360px) 240px, (max-width: 720px) 540px, (max-width: 1600px) 720px, ${myImage.width}px`} alt="A description of my image."/>
<!-- 출력 --><img src="/_astro/my_image.hash.webp" srcset=" /_astro/my_image.hash.webp 240w, /_astro/my_image.hash.webp 540w, /_astro/my_image.hash.webp 720w, /_astro/my_image.hash.webp 1600w " sizes=" (max-width: 360px) 240px, (max-width: 720px) 540px, (max-width: 1600px) 720px, 1600px " alt="A description of my image." width="1600" height="900" loading="lazy" decoding="async"/>
sizes
섹션 제목: sizes타입: string | undefined
astro@3.3.0
각 미디어 조건 목록에 대한 이미지의 레이아웃 너비를 지정합니다. widths
를 지정할 때 반드시 제공해야 합니다.
layout
속성을 사용하는 반응형 이미지는 widths
및 sizes
속성을 자동으로 생성합니다. 일반적으로 이러한 값을 제공할 필요는 없지만 자동으로 생성된 값을 재정의하는 데 사용할 수 있습니다.
constrained
및 full-width
이미지에 대해 생성된 sizes
속성은 뷰포트가 이미지 너비보다 작은 경우 이미지가 화면 전체 너비에 가깝게 표시된다는 가정을 기반으로 합니다. 크게 다른 경우 (예: 작은 화면의 다중 열 레이아웃)에는 최상의 결과를 위해 sizes
속성을 수동으로 조정해야 할 수 있습니다.
format
섹션 제목: format타입: ImageOutputFormat | undefined
선택적으로 사용할 이미지 파일 형식 출력을 명시할 수 있습니다.
기본적으로 <Image />
컴포넌트는 .webp
파일을 생성합니다.
quality
섹션 제목: quality타입: ImageQuality | undefined
quality
는 다음 중 하나일 수 있는 선택적 속성입니다.
- 형식 간 자동으로 표준화되는 사전 설정 (
low
,mid
,high
,max
)입니다. 0
부터100
까지의 숫자 (형식에 따라 다르게 해석됨)
inferSize
섹션 제목: inferSize타입: boolean
기본값: false
astro@4.4.0
원격 이미지의 원래 width
및 height
를 자동으로 설정할 수 있습니다.
기본적으로 이 값은 false
로 설정되어 있어 원격 이미지에 두 크기를 모두 수동으로 지정해야 합니다.
<Image />
컴포넌트에 inferSize
를 추가하거나 getImage()
에 inferSize: true
를 추가하여 가져올 때 이미지 콘텐츠에서 이러한 값을 추론합니다. 이는 원격 이미지의 크기를 모르거나 변경될 수 있는 경우에 유용합니다.
---import { Image } from 'astro:assets';---<Image src="https://example.com/cat.png" inferSize alt="A cat sleeping in the sun." />
inferSize
는 승인되지 않은 도메인의 원격 이미지의 크기를 가져올 수 있지만 이미지 자체는 처리되지 않은 상태로 유지됩니다.
priority
섹션 제목: priority타입: boolean
기본값: false
astro@5.10.0
새로운 기능
웹 페이지에 접속 시, 스크롤하지 않아도 화면에 바로 나타나는 이미지에 대해 loading
, decoding
, fetchpriority
속성을 최적화된 값으로 자동 설정합니다.
---import { Image } from 'astro:assets';import myImage from '../assets/my_image.png';---<Image src={myImage} priority alt="A description of my image" />
priority: true
(또는 단축 구문 priority
)를 <Image />
또는 <Picture />
컴포넌트에 추가하면 브라우저에 이미지를 즉시 로드하도록 지시하는 다음 속성이 추가됩니다.
loading="eager"decoding="sync"fetchpriority="high"
이러한 개별 속성을 사용자 정의하는 경우 수동으로 설정할 수 있습니다.
<Picture />
섹션 제목: <Picture />
추가된 버전:
astro@3.3.0
<Picture />
컴포넌트는 여러 형식 및/또는 크기로 최적화된 이미지를 생성합니다.
이 컴포넌트는 컨테이너 크기 또는 기기 화면의 크기와 해상도에 따라 조정할 수 있는 반응형 이미지를 만드는 데도 사용할 수 있습니다.
---import { Picture } from 'astro:assets';import myImage from "../assets/my_image.png"; // 1600x900의 이미지---
<!-- Picture 컴포넌트에서는 'alt'가 필수입니다. --><Picture src={myImage} formats={['avif', 'webp']} alt="A description of my image." />
<!-- 결과 --><picture> <source srcset="/_astro/my_image.hash.avif" type="image/avif" /> <source srcset="/_astro/my_image.hash.webp" type="image/webp" /> <img src="/_astro/my_image.hash.png" width="1600" height="900" decoding="async" loading="lazy" alt="A description of my image." /></picture>
Picture 속성
섹션 제목: Picture 속성<Picture />
는 반응형 이미지 속성을 포함하여 <Image />
컴포넌트의 모든 속성과 다음을 허용합니다.
formats
섹션 제목: formats타입: ImageOutputFormat[]
<source>
태그에 사용할 이미지 형식의 배열입니다. 항목은 나열된 순서대로 <source>
요소로 추가되며, 이 순서에 따라 표시되는 형식이 결정됩니다. 최상의 성능을 얻으려면 가장 최신 형식 (예: webp
또는 avif
)을 먼저 나열하세요. 기본적으로 ['webp']
로 설정되어 있습니다.
fallbackFormat
섹션 제목: fallbackFormat타입: ImageOutputFormat
<img>
태그에 대한 대체 값으로 사용할 형식입니다. 정적 이미지의 기본값은 .png
(또는 이미지가 JPG인 경우 .jpg
), 애니메이션 이미지의 경우 .gif
, SVG 파일의 경우 .svg
입니다.
pictureAttributes
섹션 제목: pictureAttributes타입: HTMLAttributes<'picture'>
<picture>
태그에 추가될 속성의 객체입니다.
이 속성을 사용하여 외부 <picture>
요소 자체에 속성을 적용합니다. <Picture />
컴포넌트에 직접 적용된 속성은 이미지 변환에 사용되는 속성을 제외하고 내부 <img>
요소에 적용됩니다.
---import { Picture } from "astro:assets";import myImage from "../my_image.png"; // 1600x900의 이미지---
<Picture src={myImage} alt="A description of my image." pictureAttributes={{ style: "background-color: red;" }}/>
<!-- 결과 --><picture style="background-color: red;"> <source srcset="/_astro/my_image.hash.webp" type="image/webp" /> <img src="/_astro/my_image.hash.png" alt="A description of my image." width="1600" height="900" loading="lazy" decoding="async" /></picture>
반응형 이미지 속성
섹션 제목: 반응형 이미지 속성<Image />
또는 <Picture />
컴포넌트에 layout
속성을 설정하면 반응형 이미지가 생성되고 추가 속성을 설정할 수 있게 됩니다.
---import { Image } from 'astro:assets';import myImage from '../assets/my_image.png';---<Image src={myImage} alt="A description of my image." layout='constrained' width={800} height={600} />
레이아웃이 설정되면 이미지의 크기와 레이아웃 유형에 따라 srcset
및 sizes
속성이 자동으로 생성됩니다. 이전 <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">
layout
의 값은 컨테이너에 따라 이미지 크기를 조정하는 방법을 결정하기 위해 <img>
태그에 적용되는 기본 스타일도 정의합니다.
: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
스타일을 재정의할 수 있습니다.
layout
섹션 제목: layout타입: 'constrained' | 'full-width' | 'fixed' | 'none'
기본값: image.layout | 'none'
astro@5.10.0
새로운 기능
반응형 이미지를 정의하고 컨테이너 크기가 변경될 때 이미지의 크기를 조정하는 방법을 결정합니다. image.layout
의 기본값을 재정의하는 데 사용할 수 있습니다.
-
constrained
- 이미지가 컨테이너에 맞게 축소되어 가로 세로 비율을 유지하지만 지정된width
와height
또는 이미지의 원래 크기를 초과하여 확대되지는 않습니다.이미지를 가능한 한 요청된 크기로 표시하되 작은 화면에 맞게 축소하려면 이 옵션을 사용합니다. 이는 Tailwind를 사용할 때 이미지의 기본 동작과 일치합니다. 잘 모르겠다면 이 레이아웃을 선택하는 것이 좋습니다.
-
full-width
- 이미지가 가로 세로 비율을 유지하면서 컨테이너 너비에 맞게 크기가 조정됩니다.히어로 이미지 또는 페이지의 전체 너비를 차지해야 하는 이미지에 이 옵션을 사용합니다.
-
fixed
- 이미지 크기가 조정되지 않고 요청된 크기를 유지합니다. 고밀도 디스플레이를 지원하기 위해srcset
을 생성하지만 다른 화면 크기에는 적용되지 않습니다.화면 너비보다 작은 아이콘이나 로고, 고정 너비 컨테이너의 이미지 등 이미지 크기가 조정되지 않는 경우에 이 옵션을 사용합니다.
-
none
- 이미지가 반응형으로 작동하지 않습니다.srcset
또는sizes
가 자동으로 생성되지 않으며 스타일이 적용되지 않습니다.기본 레이아웃을 사용하도록 설정했지만 특정 이미지에 대해 사용하지 않으려는 경우에 유용합니다.
예를 들어, 기본 레이아웃으로 constrained
를 설정하면 개별 이미지의 layout
속성을 재정의할 수 있습니다:
---import { Image } from 'astro:assets';import myImage from '../assets/my_image.png';---<Image src={myImage} alt="This will use constrained layout" width={800} height={600} /><Image src={myImage} alt="This will use full-width layout" layout="full-width" /><Image src={myImage} alt="This will disable responsive images" layout="none" />
fit
섹션 제목: fit타입: 'contain' | 'cover' | 'fill' | 'none' | 'scale-down'
기본값: image.objectFit | 'cover'
astro@5.10.0
새로운 기능
layout
속성이 설정되거나 구성된 경우 활성화됩니다. 가로 세로 비율이 변경된 경우 반응형 이미지를 자르는 방법을 정의합니다.
값은 CSS object-fit
의 값과 일치합니다. 기본값은 cover
이지만, image.objectFit
이 설정된 경우 이 속성의 값이 기본값입니다. 기본 object-fit
스타일을 재정의하는 데 사용할 수 있습니다.
position
섹션 제목: position타입: string
기본값: image.objectPosition | 'center'
astro@5.10.0
새로운 기능
layout
속성이 설정 또는 구성된 경우 활성화됩니다. 가로 세로 비율이 변경된 경우 반응형 이미지를 자르는 위치를 정의합니다.
값은 CSS object-position
의 값과 일치합니다. 기본값은 center
이지만, image.objectPosition
이 설정된 경우 이 속성의 값이 기본값입니다. 기본 object-position
스타일을 재정의하는 데 사용할 수 있습니다.
priority
섹션 제목: priority타입: boolean
기본값: false
astro@5.10.0
새로운 기능
layout
속성이 설정되거나 구성되면 활성화됩니다. 설정된 경우 반응형 이미지를 적극적으로 로드합니다. 설정하지 않으면 이미지가 지연 로드됩니다. 웹 페이지에 접속 시, 스크롤하지 않아도 화면에 바로 나타나는 큰 이미지에 이 옵션을 사용하세요. 기본값은 false
입니다.
getImage()
섹션 제목: getImage()타입: (options: UnresolvedImageTransform) => Promise<GetImageResult>
getImage()
는 서버 전용 API에 의존하며 클라이언트에서 사용될 때 빌드를 중단합니다.
getImage()
함수는 HTML이 아닌 다른 곳 (예: API 경로)에서 사용할 이미지를 생성하기 위한 것입니다. 또한 사용자 정의 <Image />
컴포넌트를 만들 수도 있습니다.
getImage()
는 Image 컴포넌트와 동일한 속성을 가진 옵션 객체를 사용합니다 (alt
제외).
---import { getImage } from "astro:assets";import myBackground from "../background.png"
const optimizedBackground = await getImage({src: myBackground, format: 'avif'})---
<div style={`background-image: url(${optimizedBackground.src});`}></div>
다음 타입을 가진 객체를 반환합니다.
type GetImageResult = { /* 이미지 렌더링에 필요한 추가 HTML 속성 (width, height, style 등) */ attributes: Record<string, any>; /* 검증된 매개변수 전달 */ options: ImageTransform; /* 원본 매개변수 전달 */ rawOptions: ImageTransform; /* 생성된 이미지의 경로 */ src: string; srcSet: { /* 생성된 srcset의 값, 각 항목에는 URL과 크기 설명자가 있습니다. */ values: SrcSetValue[]; /* `srcset` 속성에서 사용할 수 있는 값 */ attribute: string; };}
inferRemoteSize()
섹션 제목: inferRemoteSize()타입: (url: string) => Promise<Omit<ImageMetadata, 'src' | 'fsPath'>>
astro@4.12.0
원격 이미지의 크기를 유추하는 함수입니다. 이 함수는 inferSize
프로퍼티를 전달하는 대신 사용할 수 있습니다.
import { inferRemoteSize } from 'astro:assets';const {width, height} = await inferRemoteSize("https://example.com/cat.png");