Skip to content

实验性响应式图片

类型:boolean
默认:false

¥Type: boolean
Default: false

Added in: astro@5.0.0

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

¥Enables support for automatic responsive images in your project.

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

启用此标志后,你可以访问其他 image 配置设置,以控制 Astro 处理和优化的所有图片的默认行为:

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

此外,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.

响应式图片配置设置

标题部分 响应式图片配置设置

¥Responsive image configuration settings

使用默认值(responsivefixedfull-width)设置 image.experimentalLayout 以在整个项目中启用响应式图片。

¥Set image.experimentalLayout with a default value (responsive, fixed, or full-width) 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.experimentalObjectFitimage.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 all 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: 'responsive',
},
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:图片的布局类型。可以是 responsivefixedfull-widthnone。默认为 image.experimentalLayout 的值。

  • fit:定义如果纵横比发生变化,应如何裁剪图片。值与 CSS object-fit 的值匹配。默认为 cover,或如果设置,则为 image.experimentalObjectFit 的值。

  • position:定义如果纵横比发生变化,裁剪图片的位置。值与 CSS object-position 的值匹配。默认为 center,或如果设置,则为 image.experimentalObjectPosition 的值。

  • priority:如果设置,则预加载图片。否则,图片将被延迟加载。将其用于最大的首屏图片。默认为 false

widthssizes 属性是根据图片的尺寸和布局类型自动生成的,在大多数情况下不应手动设置。为 responsivefull-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 responsive 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.

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

¥For example, with responsive 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

设置布局时(默认或在单个组件上),图片会根据图片的尺寸和布局类型自动生成 srcsetsizes 属性。具有 responsivefull-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 responsive 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="--w: 800; --h: 600; --fit: cover; --pos: center;"
data-astro-image="responsive"
>

应用以下样式以确保图片正确调整大小:

¥The following styles are applied to ensure the images resize correctly:

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

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

Astro v5.5 中文网 - 粤ICP备13048890号