图像服务 API
astro:assets
旨在使任何图像优化服务都能轻松地在 Astro 上构建服务。
什么是图像服务?
段落标题 什么是图像服务?Astro 提供两种类型的图像服务:本地和外部。
- 本地服务在构建静态站点时直接处理图像转换,或者在运行时同时处理开发模式和 SSR 中的图像转换。这些通常是围绕 Sharp、ImageMagick 或 Squoosh 等库的封装。在开发模式和 SSR 中,本地服务使用 API 端点进行转换。
- 外部服务指向 URL,可以添加对 Cloudinary、Vercel 或任何符合 RIAPI 的服务器等服务的支持。
使用图像服务 API 构建
段落标题 使用图像服务 API 构建服务定义采用导出默认对象的形式,具有各种必需的方法(“钩子”)。
外部服务提供一个 getURL()
,它指向输出 <img>
标记的 src
。
本地服务为开发模式和 SSR 提供 transform()
方法来对图像执行转换,并提供 getURL()
和 parseURL()
方法来使用端点。
两种类型的服务都可以提供 getHTMLAttributes()
来确定输出 <img>
的其他属性,并提供 validateOptions()
来验证和增强传递的选项。
外部服务
段落标题 外部服务外部服务指向一个远程 URL,用作最终 <img>
标记的 src
属性。该远程 URL 负责下载、转换和返回图像。
本地服务
段落标题 本地服务要创建自己的本地服务,可以指向内置端点(/_image
),或者你还可以创建自己的端点来调用服务的方法。
在构建静态站点和预渲染路由时,<Image />
和 getImage(options)
都会调用 transform()
函数。它们分别通过组件属性或 options
参数传递选项。转换后的图像将构建到 dist/_astro
文件夹中。它们的文件名将包含传递给 propertiesToHash
的属性的哈希值。此属性是可选的,默认为 ['src', 'width', 'height', 'format', 'quality']
。如果你的自定义图像服务有更多可以更改生成图像的选项,请将它们添加到数组中。
在开发模式和 SSR 模式下,Astro 并不提前知道哪些图像需要优化。Astro 使用 GET 端点(默认情况下为 /_image
)在运行时处理图像。 <Image />
和 getImage()
将它们的选项传递给 getURL()
,后者将返回端点 URL。然后,端点调用 parseURL()
并将结果属性传递给 transform()
。
getConfiguredImageService 和 imageConfig
段落标题 getConfiguredImageService 和 imageConfig如果你将自己的端点实现为 Astro 端点,则可以使用 getConfiguredImageService
和 imageConfig
来调用服务的 parseURL
和 transform
方法并提供服务的配置对象。
要访问图像服务配置(image.service.config
),你可以使用 imageConfig.service.config
。
请参阅内置端点 了解完整示例。
钩子
段落标题 钩子getURL()
段落标题 getURL()本地和外部服务所需
getURL(options: ImageTransform, imageConfig: AstroConfig['image']): string
对于本地服务,该钩子返回生成图像的端点的 URL(在 SSR 和开发模式下)。在构建期间它不可用。 getURL()
指向的本地端点可以调用 parseURL()
和 transform()
。
对于外部服务,该钩子返回图像的最终 URL。
对于这两种类型的服务,options
是用户作为 <Image />
组件的属性或 getImage()
选项传递的属性。它们属于以下类型:
parseURL()
段落标题 parseURL()本地服务所需;外部服务不可用
parseURL(url: URL, imageConfig: AstroConfig['image']): { src: string, [key: string]: any}
该钩子通过 getURL()
将生成的 URL 解析成一个对象,该对象具有可供 transform
使用的不同属性(在 SSR 和 dev 模式下)。在构建期间它不可用。
transform()
段落标题 transform()仅本地服务需要;外部服务不可用
transform(buffer: Uint8Array, options: { src: string, [key: string]: any }, imageConfig: AstroConfig['image']): { data: Uint8Array, format: OutputFormat }
该钩子转换并返回图像,并在构建过程中被调用以创建最终的资源文件。
你必须返回 format
以确保在 SSR 和开发模式下向用户提供正确的 MIME 类型。
getHTMLAttributes()
段落标题 getHTMLAttributes()本地和外部服务可选
getHTMLAttributes(options: ImageTransform, imageConfig: AstroConfig['image']): Record<string, any>
该钩子根据用户传递的参数 (options
) 返回用于将图像呈现为 HTML 的所有附加属性。
getSrcSet()
段落标题 getSrcSet()
Added in:
astro@3.3.0
对于本地和外部服务而言是可选的。
getSrcSet?: (options: ImageTransform, imageConfig: AstroConfig['image']): SrcSetValue[] | Promise<SrcSetValue[]>;
这个钩子函数会生成指定图像的多个变体,例如,在 <img>
或 <picture>
的 source
上生成 srcset
属性。
该钩子函数返回一个包含以下属性的对象数组:
validateOptions()
段落标题 validateOptions()本地和外部服务可选
validateOptions(options: ImageTransform, imageConfig: AstroConfig['image']): ImageTransform
该钩子允许你验证和增强用户传递的选项。对于设置默认选项或告诉用户参数必传来说,这非常有用。
查看 Astro 的内置服务中是如何使用 validateOptions()
的 。
用户配置
段落标题 用户配置在 astro.config.mjs
中配置要使用的图像服务。配置采用以下形式: