资源 API 参考
添加于:
astro@3.0.0
Astro 提供了内置组件和辅助函数来优化和显示图像。有关功能和使用示例,请参阅我们的图像指南。
从 astro:assets
导入
段落标题 从 astro:assets 导入<Image />
段落标题 <Image />Image 属性
段落标题 Image 属性除了下面描述的属性之外,<Image />
组件还接受 HTML <img>
标签接受的所有属性。
src (必须)
段落标题 src (必须)类型: ImageMetadata | string | Promise<{ default: ImageMetadata }>
图像文件的 src
值的格式取决于图像文件的位置:
-
src/
中的本地图像 - 你必须同时导入图像,使用相对文件路径或配置并使用 导入别名。然后使用导入名称作为src
值: -
public/
文件夹中的图像 - 使用图像相对于public
文件夹的文件路径作为属性值: -
远程图像 - 使用图像的完整 URL作为属性值:
alt (必须)
段落标题 alt (必须)类型: string
使用必需的 alt
属性为图像提供 描述性的 alt 文本。
如果图像仅仅是装饰性的(即对理解页面没有帮助),请设置 alt=""
以便屏幕阅读器和其他辅助技术知道忽略该图像。
width 和 height(对于 public/
中的图像是必须的)
段落标题 width 和 height(对于 public/ 中的图像是必须的)类型: number | undefined
这些属性定义了要用于图像的尺寸。
当使用保持原始宽高比的图像时,width
和 height
是可选的。这些尺寸可以自动从位于 src/
中的图像文件自动推断出来。而对于远程图像,请将 <Image />
或 <Picture />
组件上的 inferSize
属性设置为 true
,或使用 inferRemoteSize()
函数。
但是,对于存储在你的 public/
文件夹中的图像,这两个属性都是必需的,因为 Astro 无法分析这些文件。
densities
段落标题 densities类型: (number | `${number}x`)[] | undefined
astro@3.3.0
为图像生成的像素密度列表。
如果提供了该值,将会在 <img>
标签上生成一个 srcset
属性。在使用此值时,请不要提供 widths
的值。
与原始图像相同或大于原始图像宽度的像素密度会被忽略,以避免放大图像。
widths
段落标题 widths类型: number[] | undefined
astro@3.3.0
为图像生成的宽度列表。
如果提供了该值,将会在 <img>
标签上生成一个 srcset
属性。但还需提供一个 sizes
属性。
在使用该值时,请不要提供 densities
的值。这两个值只能选择一个来生成 srcset
属性。
将忽略大于原始图像宽度的宽度值,以避免对图像进行放大。
format
段落标题 format类型: ImageOutputFormat | undefined
你可以选择指定要使用的 图像文件类型 输出。
默认情况下,<Image />
组件将生成 .webp
文件。
quality
段落标题 quality类型: ImageQuality | undefined
quality
是一个可选属性,可以是:
- 一个预设值(
low
、mid
、high
、max
),可以在不同格式之间自动标准化。 - 一个从
0
到100
的数字(不同格式之间的表现不同)。
inferSize
段落标题 inferSize类型: boolean
astro@4.4.0
允许你自动设置远程图像的原始 width
和 height
。
默认情况下,这个值被设置为 false
,你必须手动指定远程图片的宽度和高度。
在 <Image />
组件中添加 inferSize
(或者在 getImage()
中添加 inferSize: true
),以便在获取时从图片内容中推断这些值。如果你不知道远程图片的尺寸,或者这些尺寸可能会变化,这个属性对你会很有帮助:
inferSize
能够获取来自未经授权域的 远程图片的尺寸,但图片本身将保持未处理状态。
<Picture />
段落标题 <Picture />
添加于:
astro@3.3.0
使用内置的 <Picture />
Astro 组件来展示具有多种格式和(或)尺寸的响应式图像。
Picture 属性
段落标题 Picture 属性<Picture />
接受 <Image />
组件 的所有属性,以及以下属性:
formats
段落标题 formats类型: ImageOutputFormat[]
一个图像格式的数组,用于 <source>
标签。数组内的元素将按照列出的顺序添加为 <source>
元素,并且此顺序决定显示哪种格式。为了获得最佳性能,请首先列出最现代化的格式(例如 webp
或 avif
)。默认情况下,它被设置为 ['webp']
。
fallbackFormat
段落标题 fallbackFormat类型: ImageOutputFormat
用于作为 <img>
标签的回退值的格式。对于静态图像,默认为 .png
(如果图像是 JPG,则默认为 .jpg
);对于动画图像,默认为 .gif
;对于 SVG 文件,默认为 .svg
。
pictureAttributes
段落标题 pictureAttributes类型: HTMLAttributes<'picture'>
一个被添加到 <picture>
标签的属性对象。
使用该属性可将属性应用于外部的 <picture>
元素本身。除了用于图像转换的属性外,直接应用于 <Picture />
组件的属性将应用于内部的 <img>
元素。
getImage()
段落标题 getImage()类型:(options: UnresolvedImageTransform) => Promise<GetImageResult>
getImage()
依赖于仅在服务器上可用的 API,当在客户端使用时会导致构建失败。
getImage()
函数旨在生成用于在 HTML 之外的其他地方所使用的图像,例如在 API 路由 中。它还允许你创建自定义的 <Image />
组件。
getImage()
函数接受一个选项对象,其中包含与 Image 组件相同的属性(除了 alt
)。
它返回了一个具有以下类型的对象:
inferRemoteSize()
段落标题 inferRemoteSize()类型: (url: string) => Promise<Omit<ImageMetadata, 'src' | 'fsPath'>>
astro@4.12.0
推断远程图像尺寸的函数。它可以作为传递 inferSize
属性的替代方法。