实验性响应式图片
类型:boolean
默认:false
¥Type: boolean
Default: false
astro@5.0.0
在你的项目中启用对自动响应图片的支持。
¥Enables support for automatic responsive images in your project.
{ 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:
-
使用 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.
响应式图片配置设置
标题部分 响应式图片配置设置¥Responsive image configuration settings
使用默认值(responsive
、fixed
或 full-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.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 all Markdown images will always use the default settings.
{ 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
:图片的布局类型。可以是responsive
、fixed
、full-width
或none
。默认为image.experimentalLayout
的值。 -
fit
:定义如果纵横比发生变化,应如何裁剪图片。值与 CSSobject-fit
的值匹配。默认为cover
,或如果设置,则为image.experimentalObjectFit
的值。 -
position
:定义如果纵横比发生变化,裁剪图片的位置。值与 CSSobject-position
的值匹配。默认为center
,或如果设置,则为image.experimentalObjectPosition
的值。 -
priority
:如果设置,则预加载图片。否则,图片将被延迟加载。将其用于最大的首屏图片。默认为false
。
widths
和 sizes
属性是根据图片的尺寸和布局类型自动生成的,在大多数情况下不应手动设置。为 responsive
和 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 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
设置布局时(默认或在单个组件上),图片会根据图片的尺寸和布局类型自动生成 srcset
和 sizes
属性。具有 responsive
和 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 responsive
and full-width
layouts will have styles applied to ensure they resize according to their container.
---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:
[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.
Reference