Infrastructure/astro
0
Fork 0
mirror of https://github.com/withastro/astro.git synced 2024-12-30 22:03:56 -05:00
Code Issues Activity

chore: better images changeset pt 2 (#12484)

Browse source
This commit is contained in:
Matt Kane 2024-11-20 13:51:45 +00:00 committed by GitHub
parent 3f8b0725da
commit 18a04c008a
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 39 additions and 62 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

45
.changeset/proud-terms-swim.md
View file

@ -14,10 +14,9 @@ This feature is experimental and may change in future versions. To enable it, se
}
```
When this flag is enabled, you can pass a `layout` props to any `<Image />` or `<Picture />` component to create a responsive image. When a layout is set, 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.
When this flag is enabled, you can pass a `layout` prop to any `<Image />` or `<Picture />` component to create a responsive image. When a layout is set, 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.
```astro
// MyComponent.astro
---
import { Image, Picture } from 'astro:assets';
import myImage from '../assets/my_image.png';
@ -49,27 +48,17 @@ This feature is experimental and may change in future versions. To enable it, se
>
```
The following styles are applied to ensure the images resize correctly:
#### Responsive image properties
```css
[data-astro-image] {
width: 100%;
height: auto;
object-fit: var(--fit);
object-position: var(--pos);
aspect-ratio: var(--w) / var(--h)
}
These are additional properties available to the `<Image />` and `<Picture />` components when responsive images are enabled:
[data-astro-image=responsive] {
max-width: calc(var(--w) * 1px);
max-height: calc(var(--h) * 1px)
}
- `layout`: The layout type for the image. Can be `responsive`, `fixed`, `full-width` or `none`. Defaults to value of `image.experimentalLayout`.
- `fit`: Defines how the image should be cropped if the aspect ratio is changed. Values match those of CSS `object-fit`. Defaults to `cover`, or the value of `image.experimentalObjectFit` if set.
- `position`: Defines the position of the image crop if the aspect ratio is changed. Values match those of CSS `object-position`. Defaults to `center`, or the value of `image.experimentalObjectPosition` if set.
- `priority`: If set, eagerly loads the image. Otherwise images will be lazy-loaded. Use this for your largest above-the-fold image. Defaults to `false`.
#### Default responsive image settings
[data-astro-image=fixed] {
width: calc(var(--w) * 1px);
height: calc(var(--h) * 1px)
}
```
You can enable responsive images for all `<Image />` and `<Picture />` components by setting `image.experimentalLayout` with a default value. This can be overridden by the `layout` prop on each component.
**Example:**
@ -85,7 +74,7 @@ This feature is experimental and may change in future versions. To enable it, se
}
```
```astro title=MyComponent.astro
```astro
---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png';
@ -98,16 +87,4 @@ This feature is experimental and may change in future versions. To enable it, se
<Image src={myImage} alt="This will disable responsive images" layout="none" />
```
#### Responsive image properties
These are additional properties available to the `<Image />` and `<Picture />` components when responsive images are enabled:
- `layout`: The layout type for the image. Can be `responsive`, `fixed`, `full-width` or `none`. Defaults to value of `image.experimentalLayout`.
- `fit`: Defines how the image should be cropped if the aspect ratio is changed. Values match those of CSS `object-fit`. Defaults to `cover`, or the value of `image.experimentalObjectFit` if set.
- `position`: Defines the position of the image crop if the aspect ratio is changed. Values match those of CSS `object-position`. Defaults to `center`, or the value of `image.experimentalObjectPosition` if set.
- `priority`: If set, eagerly loads the image. Otherwise images will be lazy-loaded. Use this for your largest above-the-fold image. Defaults to `false`.
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.
The `densities` attribute is not compatible with responsive images and will be ignored if set.
For a complete overview, and to give feedback on this experimental API, see the [Responsive Images RFC](https://github.com/withastro/roadmap/blob/responsive-images/proposals/0053-responsive-images.md).