跳转到内容

实验性响应式图像

类型： boolean
默认： false

添加于： astro@5.0.0

启用以在你的项目中支持自动化响应式图像。

astro.config.mjs
{
  experimental: {
    responsiveImages: true,
  },
}

启用此标志后，你可以访问另外的 image 配置设置 来控制 Astro 处理和优化的所有图像的默认行为：

此外，Astro 的图像组件可以接收 响应式图像属性 以覆盖每个图像的默认值。

你的 public/ 文件夹中的图像永远不会被优化，且不支持响应式图像。

响应式图像配置设置

段落标题 响应式图像配置设置

通过设置 image.experimentalLayout 指定默认布局 (responsive，fixed，或 full-width) 以在整个项目中启用响应式图像。

如果未配置此值，仍然可以为任何 <Image /> 或 <Picture /> 组件传递 layout 属性以创建响应式图像。但是，Markdown 图像将不会是响应式的。

此外，可以配置 image.experimentalObjectFit 和 image.experimentalObjectPosition ，这将默认应用于所有处理后的图像。

每项设置都能通过属性在单个的 <Image /> 或 <Picture /> 组件上被覆盖，但是所有 Markdown 图像将始终使用默认设置。

astro.config.mjs
{
  image: {
    // 用于所有 Markdown 图像，不可按图像配置
    // 用于所有 `<Image />` 和 `<Picture />` 组件，除非通过属性覆盖
    experimentalLayout: 'responsive',
  },
  experimental: {
    responsiveImages: true,
  },
}

响应式图像属性

段落标题 响应式图像属性

当启用响应式图像时，有这些可用于 <Image /> 和 <Picture /> 组件的附加属性：

  • layout：图像的布局类型。可设置为 responsive、fixed、full-width 或 none。默认为 image.experimentalLayout 的值。
  • fit：定义在宽高比更改时应如何裁剪图像。该值与 CSS object-fit 的值匹配。默认为 cover 或 image.experimentalObjectFit 的值（如果设置）。
  • position：定义宽高比更改时图像裁剪的位置。该值与 CSS object-position 的值匹配。默认为 center 或 image.experimentalObjectPosition（如果设置）。
  • priority：如果设置该项，则立即加载图像。否则图像将被懒加载。可将其用于最大的首屏图像。默认为 false。

widths 和 sizes 属性是基于图像的尺寸和布局类型自动生成的，大部分情况下不应手动设置。针对于 responsive 和 full-width 图像而生成的 sizes 属性是基于这样的假设：当视口小于图像的宽度时，图像以接近屏幕的全宽显示。如果明显不同时（例如，如果它在小屏幕上采用多列布局），你可能需要手动调整 size 属性以获得最佳结果。

densities 属性无法与响应式图像兼容，如果设置则会被忽略。

例如，将 responsive 设置为默认布局后，你可以覆盖任何单个图像的 layout 属性：

---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png';
---
<Image src={myImage} alt="将会使用 responsive 布局" width={800} height={600} />
<Image src={myImage} alt="将会使用 full-width 布局" layout="full-width" />
<Image src={myImage} alt="将会禁用响应式图像" layout="none" />

生成的响应式图像 HTML 输出

段落标题 生成的响应式图像 HTML 输出

设置布局（layout）后，图像会根据图像的尺寸和布局类型自动生成 srcset 和 size 属性。具有 responsive 和 full-width 布局属性的图像将应用样式，以确保它们根据容器来调整大小。

MyComponent.astro
---
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="--w: 800; --h: 600; --fit: cover; --pos: center;"
  data-astro-image="responsive"
>

为确保图像正确地调整大小将会采用以下样式：

Responsive Image Styles
[data-astro-image] {
  width: 100%;
  height: auto;
  object-fit: var(--fit);
  object-position: var(--pos);
  aspect-ratio: var(--w) / var(--h)
}


[data-astro-image=responsive] {
  max-width: calc(var(--w) * 1px);
  max-height: calc(var(--h) * 1px)
}


[data-astro-image=fixed] {
  width: calc(var(--w) * 1px);
  height: calc(var(--h) * 1px)
}

有关完整概述以及提供有关此实验性 API 的反馈，请参阅 响应式图像 RFC。

贡献 社区 赞助