跳转到内容

资源 API 参考

添加于: astro@3.0.0

Astro 提供了内置组件和辅助函数来优化和显示图像。有关功能和使用示例,请参阅我们的图像指南

import {
Image,
Picture,
getImage,
inferRemoteSize,
} from 'astro:assets';
src/components/MyComponent.astro
---
// 导入图像组件和图片
import { Image } from 'astro:assets';
import myImage from "../assets/my_image.png"; // Image is 1600x900
---
<!-- `alt` 在 Image 组件中是必需的属性 -->
<Image src={myImage} alt="A description of my image." />
<!-- 输出 -->
<!-- Image 组件已经过优化,并且对应的属性也被强制使用。 -->
<img
src="/_astro/my_image.hash.webp"
width="1600"
height="900"
decoding="async"
loading="lazy"
alt="一段关于我图片的描述。"
/>

除了下面描述的属性之外,<Image /> 组件还接受 HTML <img> 标签接受的所有属性。

类型: ImageMetadata | string | Promise<{ default: ImageMetadata }>

图像文件的 src 值的格式取决于图像文件的位置:

  • src/ 中的本地图像 - 你必须同时导入图像,使用相对文件路径或配置并使用 导入别名。然后使用导入名称作为 src 值:

    src/pages/index.astro
    ---
    import { Image } from 'astro:assets';
    import myImportedImage from '../assets/my-local-image.png';
    ---
    <Image src={myImportedImage} alt="descriptive text" />
  • public/ 文件夹中的图像 - 使用图像相对于 public 文件夹的文件路径作为属性值:

    src/pages/index.astro
    ---
    import { Image } from 'astro:assets';
    ---
    <Image
    src="/images/my-public-image.png"
    alt="descriptive text"
    width="200"
    height="150"
    />
  • 远程图像 - 使用图像的完整 URL作为属性值:

    src/pages/index.astro
    ---
    import { Image } from 'astro:assets';
    ---
    <Image
    src="https://example.com/remote-image.jpg"
    alt="descriptive text"
    width="200"
    height="150"
    />

类型: string

使用必需的 alt 属性为图像提供 描述性的 alt 文本

如果图像仅仅是装饰性的(即对理解页面没有帮助),请设置 alt="" 以便屏幕阅读器和其他辅助技术知道忽略该图像。

width 和 height(对于 public/ 中的图像是必须的)
段落标题 width 和 height(对于 public/ 中的图像是必须的)

类型: number | undefined

这些属性定义了要用于图像的尺寸。

当使用保持原始宽高比的图像时,widthheight 是可选的。这些尺寸可以自动从位于 src/ 中的图像文件自动推断出来。而对于远程图像,请将 <Image /><Picture /> 组件上的 inferSize 属性设置为 true,或使用 inferRemoteSize() 函数。

但是,对于存储在你的 public/ 文件夹中的图像,这两个属性都是必需的,因为 Astro 无法分析这些文件。

类型: (number | `${number}x`)[] | undefined

添加于: astro@3.3.0

为图像生成的像素密度列表。

如果提供了该值,将会在 <img> 标签上生成一个 srcset 属性。在使用此值时,请不要提供 widths 的值。

与原始图像相同或大于原始图像宽度的像素密度会被忽略,以避免放大图像。

src/components/MyComponent.astro
---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png';
---
<Image
src={myImage}
width={myImage.width / 2}
densities={[1.5, 2]}
alt="我的图片描述"
/>
<!-- 输出 -->
<img
src="/_astro/my_image.hash.webp"
srcset="
/_astro/my_image.hash.webp 1.5x
/_astro/my_image.hash.webp 2x
"
alt="我的图片描述"
width="800"
height="450"
loading="lazy"
decoding="async"
/>

类型: number[] | undefined

添加于: astro@3.3.0

为图像生成的宽度列表。

如果提供了该值,将会在 <img> 标签上生成一个 srcset 属性。但还需提供一个 sizes 属性

在使用该值时,请不要提供 densities 的值。这两个值只能选择一个来生成 srcset 属性。

将忽略大于原始图像宽度的宽度值,以避免对图像进行放大。

src/components/MyComponent.astro
---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png'; // Image is 1600x900
---
<Image
src={myImage}
widths={[240, 540, 720, myImage.width]}
sizes={`(max-width: 360px) 240px, (max-width: 720px) 540px, (max-width: 1600px) 720px, ${myImage.width}px`}
alt="我的图片描述"
/>
<!-- 输出 -->
<img
src="/_astro/my_image.hash.webp"
srcset="
/_astro/my_image.hash.webp 240w,
/_astro/my_image.hash.webp 540w,
/_astro/my_image.hash.webp 720w,
/_astro/my_image.hash.webp 1600w
"
sizes="
(max-width: 360px) 240px,
(max-width: 720px) 540px,
(max-width: 1600px) 720px,
1600px
"
alt="我的图片描述"
width="1600"
height="900"
loading="lazy"
decoding="async"
/>

类型: ImageOutputFormat | undefined

你可以选择指定要使用的 图像文件类型 输出。

默认情况下,<Image /> 组件将生成 .webp 文件。

类型: ImageQuality | undefined

quality 是一个可选属性,可以是:

  • 一个预设值(lowmidhighmax),可以在不同格式之间自动标准化。
  • 一个从 0100 的数字(不同格式之间的表现不同)。

类型: boolean

添加于: astro@4.4.0

允许你自动设置远程图像的原始 widthheight

默认情况下,这个值被设置为 false,你必须手动指定远程图片的宽度和高度。

<Image /> 组件中添加 inferSize(或者在 getImage() 中添加 inferSize: true),以便在获取时从图片内容中推断这些值。如果你不知道远程图片的尺寸,或者这些尺寸可能会变化,这个属性对你会很有帮助:

---
import { Image } from 'astro:assets';
---
<Image src="https://example.com/cat.png" inferSize alt="一只猫在阳光下睡觉。" />

inferSize 能够获取来自未经授权域的 远程图片的尺寸,但图片本身将保持未处理状态。

添加于: astro@3.3.0

使用内置的 <Picture /> Astro 组件来展示具有多种格式和(或)尺寸的响应式图像。

src/pages/index.astro
---
import { Picture } from 'astro:assets';
import myImage from "../assets/my_image.png"; // 图像的分辨率为 1600x900
---
<!-- 在图片组件上 `alt` 属性是必需的 -->
<Picture src={myImage} formats={['avif', 'webp']} alt="A description of my image." />
<!-- 输出 -->
<picture>
<source srcset="/_astro/my_image.hash.avif" type="image/avif" />
<source srcset="/_astro/my_image.hash.webp" type="image/webp" />
<img
src="/_astro/my_image.hash.png"
width="1600"
height="900"
decoding="async"
loading="lazy"
alt="A description of my image."
/>
</picture>

<Picture /> 接受 <Image /> 组件 的所有属性,以及以下属性:

类型: ImageOutputFormat[]

一个图像格式的数组,用于 <source> 标签。数组内的元素将按照列出的顺序添加为 <source> 元素,并且此顺序决定显示哪种格式。为了获得最佳性能,请首先列出最现代化的格式(例如 webpavif)。默认情况下,它被设置为 ['webp']

类型: ImageOutputFormat

用于作为 <img> 标签的回退值的格式。对于静态图像,默认为 .png(如果图像是 JPG,则默认为 .jpg);对于动画图像,默认为 .gif;对于 SVG 文件,默认为 .svg

类型: HTMLAttributes<'picture'>

一个被添加到 <picture> 标签的属性对象。

使用该属性可将属性应用于外部的 <picture> 元素本身。除了用于图像转换的属性外,直接应用于 <Picture /> 组件的属性将应用于内部的 <img> 元素。

src/components/MyComponent.astro
---
import { Picture } from "astro:assets";
import myImage from "../my_image.png"; // Image 为 1600x900
---
<Picture
src={myImage}
alt="我的图片描述。"
pictureAttributes={{ style: "background-color: red;" }}
/>
<!-- 输出 -->
<picture style="background-color: red;">
<source srcset="/_astro/my_image.hash.webp" type="image/webp" />
<img
src="/_astro/my_image.hash.png"
alt="我的图片描述。"
width="1600"
height="900"
loading="lazy"
decoding="async"
/>
</picture>

类型:(options: UnresolvedImageTransform) => Promise<GetImageResult>

getImage()函数旨在生成用于在 HTML 之外的其他地方所使用的图像,例如在 API 路由 中。它还允许你创建自定义的 <Image /> 组件。

getImage() 函数接受一个选项对象,其中包含与 Image 组件相同的属性(除了 alt)。

---
import { getImage } from "astro:assets";
import myBackground from "../background.png"
const optimizedBackground = await getImage({src: myBackground, format: 'avif'})
---
<div style={`background-image: url(${optimizedBackground.src});`}></div>

它返回了一个具有以下类型的对象:

type GetImageResult = {
/* 渲染图像所需的附加 HTML 属性(宽度、高度、样式等) */
attributes: Record<string, any>;
/* 已通过校验的参数 */
options: ImageTransform;
/* 传递的原始参数 */
rawOptions: ImageTransform;
/* 生成图像的路径 */
src: string;
srcSet: {
/* 为 srcset 生成值,每个条目都有一个 url 和一个 size */
values: SrcSetValue[];
/* 准备在`srcset`属性中使用的值 */
attribute: string;
};
}

类型: (url: string) => Promise<Omit<ImageMetadata, 'src' | 'fsPath'>>

添加于: astro@4.12.0

推断远程图像​​尺寸的函数。它可以作为传递 inferSize 属性的替代方法。

import { inferRemoteSize } from 'astro:assets';
const {width, height} = await inferRemoteSize("https://example.com/cat.png");
贡献

你有什么想法?

社区