跳转到内容
v5-beta

资源 API 参考

添加于： 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
---
// 导入图像组件和图片
import { Image } from 'astro:assets';
import myImage from "../assets/my_image.png"; // Image is 1600x900
---


<!-- `alt` 在 Image 组件中是必需的属性 -->
<Image src={myImage} alt="A description of my image." />
<!-- 输出 -->
<!-- Image 组件已经过优化，并且对应的属性也被强制使用。 -->
<img
  src="/_astro/my_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  alt="一段关于我图片的描述。"
/>

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 文本。

如果图像仅仅是装饰性的（即对理解页面没有帮助），请设置 alt="" 以便屏幕阅读器和其他辅助技术知道忽略该图像。

width 和 height（对于 public/ 中的图像是必须的）
段落标题 width 和 height（对于 public/ 中的图像是必须的）

类型： number | undefined

这些属性定义了要用于图像的尺寸。

当使用保持原始宽高比的图像时，width 和 height 是可选的。这些尺寸可以自动从位于 src/ 中的图像文件自动推断出来。而对于远程图像，请将 <Image /> 或 <Picture /> 组件上的 inferSize 属性设置为 true，或使用 inferRemoteSize() 函数。

但是，对于存储在你的 public/ 文件夹中的图像，这两个属性都是必需的，因为 Astro 无法分析这些文件。

densities
段落标题 densities

类型： (number | `${number}x`)[] | undefined

添加于： 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="我的图片描述"
/>
<!-- 输出 -->
<img
  src="/_astro/my_image.hash.webp"
  srcset="
    /_astro/my_image.hash.webp 1.5x
    /_astro/my_image.hash.webp 2x
  "
  alt="我的图片描述"
  width="800"
  height="450"
  loading="lazy"
  decoding="async"
/>
widths
段落标题 widths

类型： number[] | undefined

添加于： astro@3.3.0

为图像生成的宽度列表。

如果提供了该值，将会在 <img> 标签上生成一个 srcset 属性。但还需提供一个 sizes 属性。

在使用该值时，请不要提供 densities 的值。这两个值只能选择一个来生成 srcset 属性。

将忽略大于原始图像宽度的宽度值，以避免对图像进行放大。

src/components/MyComponent.astro
---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png'; // Image is 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="我的图片描述"
/>
<!-- 输出 -->
<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="我的图片描述"
  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

添加于： 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="一只猫在阳光下睡觉。" />

inferSize 能够获取来自未经授权域的 远程图片的尺寸，但图片本身将保持未处理状态。

<Picture />

段落标题 &lt;Picture /&gt;

添加于： astro@3.3.0

使用内置的 <Picture /> Astro 组件来展示具有多种格式和（或）尺寸的响应式图像。

src/pages/index.astro
---
import { Picture } from 'astro:assets';
import myImage from "../assets/my_image.png"; // 图像的分辨率为 1600x900
---


<!-- 在图片组件上 `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"; // Image 为 1600x900
---


<Picture
  src={myImage}
  alt="我的图片描述。"
  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="我的图片描述。"
    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 属性（宽度、高度、样式等） */
  attributes: Record<string, any>;
  /* 已通过校验的参数 */
  options: ImageTransform;
  /* 传递的原始参数 */
  rawOptions: ImageTransform;
  /* 生成图像的路径 */
  src: string;
  srcSet: {
    /* 为 srcset 生成值，每个条目都有一个 url 和一个 size */
    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");
贡献

你有什么想法？

创建 GitHub Issue

向我们的团队发出问题警报的最快方法。

社区