实验性响应式图片

类型：boolean
默认：false

¥Type: boolean
Default: false

Added in: astro@5.0.0

在你的项目中启用对自动响应图片的支持。

¥Enables support for automatic responsive images in your project.

术语 响应式图片 指的是能够在不同设备上良好显示的图片。这尤其适用于调整大小以适应其容器的图片，并且可以根据设备的屏幕尺寸和分辨率以不同的尺寸提供。

¥The term responsive images refers images that work well on different devices. This particularly applies to images that resize to fit their container, and that can be served in different sizes depending on the device’s screen size and resolution.

可以设置许多其他属性来控制图片的显示方式，但手动处理这些属性可能很复杂。错误地处理这些属性可能会导致图片下载缓慢或显示不正确。这是导致核心 Web 指标和 Lighthouse 性能得分不佳的最常见原因之一。

¥There are a number of additional properties that can be set to control how the image is displayed, but these can be complicated to handle manually. Incorrect handling of these properties can lead to images that are slow to download or that are not displayed correctly. This is one of the most common causes of poor Core Web Vitals and Lighthouse performance scores.

启用此标志后，Astro 可以自动为图片生成所需的 srcset 和 sizes 值，并应用正确的样式以确保它们正确调整大小。此行为可以全局配置，也可以针对每个图片进行配置。

¥When this flag is enabled, Astro can automatically generate the required srcset and sizes values for images, and apply the correct styles to ensure they resize correctly. This behavior can be configured globally or on a per-image basis.

要启用该功能，首先将 responsiveImages 标志添加到你的 astro.config.mjs 文件中：

¥To enable the feature, first add the responsiveImages flag to your astro.config.mjs file:

astro.config.mjs

{
  experimental: {
    responsiveImages: true,
  },
}

启用此标志默认情况下不会更改任何内容，但可以通过全局或每张图片设置 图片布局 来配置响应式图片。

¥Enabling this flag will not change anything by default, but responsive images can then be configured by setting the image layout either globally or per image.

为此，你可以访问额外的 image 配置设置 属性，以控制 Astro 处理和优化的所有图片的默认行为：

¥To do this, you have access to additional image configuration settings for controlling the default behavior of all images processed and optimized by Astro:

• 使用 Markdown ![]() 语法 的本地和远程图片。

• <Image /> 和 <Picture /> 组件。

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

¥Additionally, Astro’s image components can receive responsive image props to override these defaults on a per-image basis.

public/ 文件夹中的图片从未优化过，也不支持响应式图片。

¥Images in your public/ folder are never optimized, and responsive images are not supported.

Note

Enabling responsive images will generate additional image sizes for all affected images. For prerendered pages this happens during the build so may increase the build time of your project, especially if you have a large number of images.

For pages rendered on-demand the images are generated as-needed, so this has no impact on build times but may increase the number of transformations performed. Depending on your image service this may incur additional costs.

图片布局

标题部分 图片布局

¥Image layout

为了生成正确的 srcset 和 sizes 属性，<Image /> 和 <Picture /> 组件需要知道当容器大小改变时，图片应该如何调整大小。这可以通过设置 layout 属性或 image.experimentalLayout 默认值来实现。支持的值包括：

¥In order to generate the correct srcset and sizes attributes, the <Image /> and <Picture /> components need to know how the image should resize when its container changes size. This is done by setting the layout prop, or image.experimentalLayout default. The supported values are:

• constrained - 图片将缩小以适应容器，保持其宽高比，但不会放大到超出指定的 width 和 height 或图片的原始尺寸。如果你希望图片尽可能以请求的大小显示，但会缩小以适应较小的屏幕，请使用此选项。这与使用 Tailwind 时图片的默认行为一致。如果你不确定，这可能是你应该选择的布局。

• full-width - 图片将缩放以适应容器的宽度，保持其宽高比。将此加载器用于英雄图片或其他应占据整个页面宽度的图片。

• fixed - 图片将保持请求的尺寸，不会调整大小。它将生成一个 srcset 以支持高密度显示器，但不适用于不同的屏幕尺寸。如果图片无法调整大小，例如图标或徽标小于任何屏幕宽度，或固定宽度容器中的其他图片，请使用此选项。

• none - 图片将不具有响应式布局。不会自动生成 srcset 或 sizes，也不会应用任何样式。如果你已启用默认布局，但想要为特定图片禁用它，这将非常有用。

所选的 layout 将用于为图片生成正确的 srcset 和 sizes 属性，并将定义应用于该 <img> 标签的默认样式。

¥The chosen layout will be used to generate the correct srcset and sizes attributes for the image, and will define the default styles applied to that <img> tag.

配置设置

标题部分 配置设置

¥Configuration settings

将 image.experimentalLayout 设置为默认值，以在整个项目中启用响应式图片。

¥Set image.experimentalLayout with a default value to enable responsive images throughout your project.

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

¥If this value is not configured, you can still pass a layout prop to any <Image /> or <Picture /> component to create a responsive image. However, Markdown images will not be responsive.

或者，你可以配置 image.experimentalObjectFit 和 image.experimentalObjectPosition，默认情况下，它们将应用于所有已处理的图片。

¥Optionally, you can configure image.experimentalObjectFit and image.experimentalObjectPosition which will apply to all processed images by default.

这些设置中的每一个都可以在任何单独的 <Image /> 或 <Picture /> 组件上使用 prop 覆盖，但 Markdown 图片将始终使用默认设置。

¥Each of these settings can be overridden on any individual <Image /> or <Picture /> component with a prop, but Markdown images will always use the default settings.

astro.config.mjs

{
  image: {
    // Used for all Markdown images; not configurable per-image
    // Used for all `<Image />` and `<Picture />` components unless overridden with a prop
    experimentalLayout: 'constrained',
  },
  experimental: {
    responsiveImages: true,
  },
}

响应式图片属性

标题部分 响应式图片属性

¥Responsive image properties

这些是启用响应式图片时 <Image /> 和 <Picture /> 组件可用的附加属性：

¥These are additional properties available to the <Image /> and <Picture /> components when responsive images are enabled:

• 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 属性以获得最佳效果。

¥The widths and sizes attributes are automatically generated based on the image’s dimensions and the layout type, and in most cases should not be set manually. The generated sizes attribute for constrained and full-width images is based on the assumption that the image is displayed at close to the full width of the screen when the viewport is smaller than the image’s width. If it is significantly different (e.g. if it’s in a multi-column layout on small screens) you may need to adjust the sizes attribute manually for best results.

densities 属性与响应式图片不兼容，如果设置将被忽略。

¥The densities attribute is not compatible with responsive images and will be ignored if set.

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

¥For example, with constrained set as the default layout, you can override any individual image’s layout property:

---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png';
---
<Image src={myImage} alt="This will use responsive 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" />

为响应式图片生成 HTML 输出

标题部分 为响应式图片生成 HTML 输出

¥Generated HTML output for responsive images

设置布局时（默认或在单个组件上），图片会根据图片的尺寸和布局类型自动生成 srcset 和 sizes 属性。具有 constrained 和 full-width 布局的图片将应用样式以确保它们根据其容器调整大小。

¥When a layout is set, either by default or on an individual component, images have automatically generated srcset and sizes attributes based on the image’s dimensions and the layout type. Images with constrained and full-width layouts will have styles applied to ensure they resize according to their container.

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 输出：

¥This <Image /> component will generate the following HTML output:

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

覆盖图片样式

标题部分 覆盖图片样式

¥Overriding image styles

响应式图片组件应用了少量样式以确保它们能够正确调整大小。应用的样式取决于布局类型，旨在为生成的 srcset 和 sizes 属性提供最佳行为。以下是默认样式：

¥The responsive image component applies a small number of styles to ensure they resize correctly. The applied styles depend on the layout type, and are designed to give the best behavior for the generated srcset and sizes attributes. These are the default styles:

Responsive Image Styles

: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 属性来覆盖 object-fit 和 object-position 的样式。

¥You can override the object-fit and object-position styles by setting the fit and position props on the <Image /> or <Picture /> component.

样式使用 :where() 伪类，其 specificity 为 0，这意味着你可以轻松用自己的样式覆盖它。任何类名或标签名的优先级都高于 :where()，因此你可以通过向图片添加自己的类名或标签名来轻松覆盖样式。

¥The styles use the :where() pseudo-class, which has a specificity of 0, meaning that it is easy to override with your own styles. Any class or tag name will have a higher specificity than :where(), so you can easily override the styles by adding your own class or tag name to the image.

Tailwind 4 是一个特例，因为它使用 cascade layers, meaning the Tailwind rules are always lower specificity than rules that don’t use layers. Astro supports browsers that do not support cascade layers, so it cannot use them for images. This means that if you need to override the styles using Tailwind 4, you must use the !important modifier。

¥Tailwind 4 is a special case, because it uses cascade layers, meaning the Tailwind rules are always lower specificity than rules that don’t use layers. Astro supports browsers that do not support cascade layers, so it cannot use them for images. This means that if you need to override the styles using Tailwind 4, you must use the !important modifier.

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

¥For a complete overview, and to give feedback on this experimental API, see the Responsive Images RFC.