컨텐츠로 건너뛰기

자산 API 참조

Added in: astro@3.0.0

Astro는 최적화된 이미지를 표시하기 위한 기본 컴포넌트와 도우미 함수를 제공합니다. 기능 및 사용 예시는 이미지 가이드를 참조하세요.

astro:assets에서 가져오기

섹션 제목: astro:assets에서 가져오기
import {
  Image,
  Picture,
  getImage,
  inferRemoteSize,
 } from 'astro:assets';

<Image />

섹션 제목: &lt;Image /&gt;
src/components/MyComponent.astro
---
// 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';
    ---
    <Image
      src="/images/my-public-image.png"
      alt="descriptive text"
      width="200"
      height="150"
    />

  • 원격 이미지 - 이미지의 전체 URL을 속성 값으로 사용합니다.

    src/pages/index.astro
    ---
    import { Image } from 'astro:assets';
    ---
    <Image
      src="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

이러한 속성은 이미지에 사용할 크기를 정의합니다.

이미지를 원본 가로세로 비율로 사용하는 경우 width 및 height는 선택사항입니다. 이러한 치수는 src/에 있는 이미지 파일에서 자동으로 유추할 수 있습니다. 원격 이미지의 경우 <Image /> 또는 <Picture /> 컴포넌트의 inferSize 속성을 true로 설정하거나 inferRemoteSize() 함수를 사용하세요.

그러나 Astro는 이러한 파일을 분석할 수 없으므로 public/ 폴더에 저장된 이미지에는 이 두 속성이 모두 필요합니다.

densities
섹션 제목: densities

타입: (number | `${number}x`)[] | undefined

Added in: astro@3.3.0

이미지에 대해 생성할 픽셀 밀도 목록입니다.

제공된 경우 이 값은 <img> 태그에 srcset 속성을 생성하는 데 사용됩니다. 이 값을 사용할 때 widths 값을 제공하지 마세요.

이미지 크기가 커지는 것을 방지하기 위해 원본 이미지보다 더 큰 너비와 동일한 밀도는 무시됩니다.

src/components/MyComponent.astro
---
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

Added in: astro@3.3.0

이미지에 대해 생성할 너비 목록입니다.

제공된 경우 이 값은 <img> 태그에 srcset 속성을 생성하는 데 사용됩니다. 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"
/>
format
섹션 제목: format

타입: ImageOutputFormat | undefined

선택적으로 사용할 이미지 파일 형식 출력을 명시할 수 있습니다.

기본적으로 <Image /> 컴포넌트는 .webp 파일을 생성합니다.

quality
섹션 제목: quality

타입: ImageQuality | undefined

quality는 다음 중 하나일 수 있는 선택적 속성입니다.

  • 형식 간 자동으로 표준화되는 사전 설정 (low, mid, high, max)입니다.
  • 0부터 100까지의 숫자 (형식에 따라 다르게 해석됨)
inferSize
섹션 제목: inferSize

타입: boolean

Added in: 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는 승인되지 않은 도메인의 원격 이미지의 크기를 가져올 수 있지만 이미지 자체는 처리되지 않은 상태로 유지됩니다.

<Picture />

섹션 제목: &lt;Picture /&gt;

Added in: astro@3.3.0

다양한 형식 및/또는 크기로 반응형 이미지를 표시하려면 Astro의 <Picture /> 컴포넌트를 사용하세요.

src/pages/index.astro
---
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> 요소에 적용됩니다.

src/components/MyComponent.astro
---
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>

getImage()

섹션 제목: getImage()

타입: (options: UnresolvedImageTransform) => Promise<GetImageResult>

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'>>

Added in: astro@4.12.0

원격 이미지의 크기를 유추하는 함수입니다. 이 함수는 inferSize 프로퍼티를 전달하는 대신 사용할 수 있습니다.

import { inferRemoteSize } from 'astro:assets';
const {width, height} = await inferRemoteSize("https://example.com/cat.png");
기여하기

여러분의 생각을 들려주세요!

GitHub Issue 생성

우리에게 가장 빨리 문제를 알려줄 수 있어요.

커뮤니티