API сервиса изображений
astro:assets
был разработан для того, чтобы любой сервис по оптимизации изображений мог легко создать сервис поверх Astro.
Что такое сервис изображений?
Заголовок раздела Что такое сервис изображений?Astro предоставляет два типа сервисов для работы с изображениями: Локальные и Внешние.
- Локальные сервисы обрабатывают преобразования изображений непосредственно при сборке для статических сайтов или во время выполнения как в режиме разработки, так и в SSR. Часто это обертки вокруг таких библиотек, как Sharp, ImageMagick или Squoosh. В режиме разработки и в SSR локальные сервисы используют конечную точку API для выполнения преобразования.
- Внешние сервисы указывают на URL-адреса и могут добавлять поддержку таких сервисов, как Cloudinary, Vercel или любого RIAPI-совместимого сервера.
Разработка с использованием API сервисов изображений
Заголовок раздела Разработка с использованием API сервисов изображенийОпределения сервисов имеют форму экспортируемого объекта по умолчанию с различными обязательными методами (“хуками”).
Внешние сервисы предоставляют метод getURL()
, который указывает на src
выходного тега <img>
.
Локальные сервисы предоставляют метод transform()
для выполнения преобразований изображения, а также методы getURL()
и parseURL()
для использования конечной точки в режиме разработки и SSR.
Оба типа сервисов могут предоставлять getHTMLAttributes()
для определения других атрибутов выходного <img>
и validateOptions()
для проверки и дополнения переданных параметров.
Внешние сервисы
Заголовок раздела Внешние сервисыВнешний сервис указывает на удаленный URL, который будет использоваться в качестве атрибута src
конечного тега <img>
. Этот удаленный URL отвечает за загрузку, преобразование и возврат изображения.
Локальные сервисы
Заголовок раздела Локальные сервисыЧтобы создать свой собственный локальный сервис, вы можете указать на встроенную конечную точку (/_image
) или дополнительно создать свою собственную конечную точку, которая сможет вызывать методы сервиса.
Во время сборки статических сайтов и предварительно отрендеренных маршрутов, как <Image />
, так и getImage(options)
вызывают функцию transform()
. Они передают опции либо через атрибуты компонента, либо через аргумент options
, соответственно. Преобразованные изображения будут собраны в папку dist/_astro
.
В режиме разработки и режиме 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}
Этот хук разбирает сгенерированные URL с помощью getURL()
обратно в объект с различными свойствами для использования transform
(в режиме SSR и разработки). Во время сборки он не используется.
transform()
Заголовок раздела transform()Необходимо только для локальных сервисов; недоступно для внешних сервисов.
transform(buffer: Uint8Array, options: { src: string, [key: string]: any }, imageConfig: AstroConfig['image']): { data: Uint8Array, format: OutputFormat }
Этот хук преобразует и возвращает изображение и вызывается во время сборки для создания финальных файлов.
Вы должны вернуть format
, чтобы гарантировать, что правильный MIME-тип обслуживается пользователям в режиме SSR и разработки.
getHTMLAttributes()
Заголовок раздела getHTMLAttributes()Опционально для локальных и внешних сервисов
getHTMLAttributes(options: ImageTransform, imageConfig: AstroConfig['image']): Record<string, any>
Этот хук возвращает все дополнительные атрибуты, используемые для рендеринга изображения в HTML, на основе параметров, переданных пользователем (options
).
getSrcSet()
Заголовок раздела getSrcSet()
Добавлено в:
astro@3.3.0
Опционально для локальных и внешних сервисов.
getSrcSet?: (options: ImageTransform, imageConfig: AstroConfig['image']): SrcSetValue[] | Promise<SrcSetValue[]>;
Этот хук генерирует несколько вариантов указанного изображения, например, чтобы создать атрибут srcset
для <img>
или source
в <picture>
.
Этот хук возвращает массив объектов со следующими свойствами:
validateOptions()
Заголовок раздела validateOptions()Опционально для локальных и внешних сервисов
validateOptions(options: ImageTransform, imageConfig: AstroConfig['image']): ImageTransform
Этот хук позволяет проверять и дополнять опции, переданные пользователем. Это полезно для установки параметров по умолчанию или указания пользователю, что тот или иной параметр является обязательным.
Смотрите, как validateOptions()
используется во встроенных сервисах Astro.
Конфигурация пользователя
Заголовок раздела Конфигурация пользователяНастройте используемый сервис изображений в файле astro.config.mjs
. Конфиг имеет следующий вид: