Справочник API Assets (Изображения)

Добавлено в: astro@3.0.0

Astro предоставляет встроенные компоненты и вспомогательные функции для оптимизации и отображения ваших изображений. Информацию о функциях и примеры использования смотрите в нашем руководстве по изображениям.

Импорт из astro:assets

Следующие помощники импортируются из виртуального модуля astro:assets:

import {
  Image,
  Picture,
  getImage,
  inferRemoteSize,
  getConfiguredImageService,
  imageConfig,
} from 'astro:assets';

<Image />

Компонент <Image /> оптимизирует и преобразует изображения.

Этот компонент также можно использовать для создания адаптивных изображений, которые могут подстраиваться под размер контейнера или размер и разрешение экрана устройства.

src/components/MyComponent.astro

---
// импорт компонента Image и изображения
import { Image } from 'astro:assets';
import myImage from "../assets/my_image.png"; // Изображение 1600x900
---

<!-- `alt` обязателен для компонента Image -->
<Image src={myImage} alt="Описание моего изображения." />

<!-- Вывод -->
<!-- Изображение оптимизировано, применены правильные атрибуты -->
<img
  src="/_astro/my_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  alt="Описание моего изображения."
/>

Компонент <Image /> принимает следующие перечисленные свойства, а также свойства адаптивного изображения в дополнение ко всем свойствам, принимаемым HTML-тегом <img>.

src (обязательно)

Тип: 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="описательный текст" />

• Изображения в папке public/ — используйте путь к файлу изображения относительно папки public:

  src/pages/index.astro

  ---
  import { Image } from 'astro:assets';
  ---
  <Image
    src="/images/my-public-image.png"
    alt="описательный текст"
    width="200"
    height="150"
  />

• Удаленные изображения — используйте полный URL изображения в качестве значения свойства:

  src/pages/index.astro

  ---
  import { Image } from 'astro:assets';
  ---
  <Image
    src="https://example.com/remote-image.jpg"
    alt="описательный текст"
    width="200"
    height="150"
  />

alt (обязательно)

Тип: string

Используйте обязательный атрибут alt, чтобы предоставить строку с описательным альтернативным текстом для изображений.

Если изображение является чисто декоративным (т.е. не способствует пониманию страницы), установите alt="", чтобы скринридеры и другие вспомогательные технологии знали, что изображение нужно игнорировать.

width и height (обязательно для изображений в public/)

Тип: number | `${number}` | undefined

Эти свойства определяют размеры, используемые для изображения.

Когда установлен тип layout, они генерируются автоматически на основе размеров изображения и в большинстве случаев не должны задаваться вручную.

При использовании изображений в исходном соотношении сторон width и height необязательны. Эти размеры могут быть автоматически выведены из файлов изображений, расположенных в src/. Для удаленных изображений добавьте атрибут inferSize, установленный в true, в компонент <Image /> или <Picture /> или используйте функцию inferRemoteSize().

Однако оба этих свойства обязательны для изображений, хранящихся в вашей папке public/, так как Astro не может анализировать эти файлы.

densities

Тип: (number | `${number}x`)[] | undefined

Добавлено в: astro@3.3.0

Список плотностей пикселей для генерации изображения.

Атрибут densities не совместим с адаптивными изображениями с установленным пропом layout или конфигурацией image.layout и будет проигнорирован, если он задан.

Если указано, это значение будет использоваться для генерации атрибута srcset в теге <img>. Не указывайте значение для 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"
/>

widths

Тип: number[] | undefined

Добавлено в: astro@3.3.0

Список значений ширины для генерации изображения.

Если указано, это значение будет использоваться для генерации атрибута srcset в теге <img>. Также должно быть предоставлено свойство sizes.

Атрибуты widths и sizes будут автоматически сгенерированы для адаптивных изображений, использующих свойство layout. Предоставление этих значений обычно не требуется, но может использоваться для переопределения любых автоматически сгенерированных значений.

Не указывайте значение для densities при использовании этого значения. Только одно из этих двух значений может быть использовано для генерации srcset.

Значения ширины, которые больше оригинального изображения, будут проигнорированы, чтобы избежать увеличения масштаба изображения.

src/components/MyComponent.astro

---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png'; // Изображение 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"
/>

sizes

Тип: string | undefined

Добавлено в: astro@3.3.0

Указывает ширину макета изображения для каждого из списка медиа-условий. Должно быть предоставлено при указании widths.

Атрибуты widths и sizes будут автоматически сгенерированы для адаптивных изображений, использующих свойство layout. Предоставление этих значений обычно не требуется, но может использоваться для переопределения любых автоматически сгенерированных значений.

Сгенерированный атрибут sizes для изображений constrained и full-width основан на предположении, что изображение отображается почти во всю ширину экрана, когда область просмотра меньше ширины изображения. Если это существенно отличается (например, если изображение находится в многоколоночном макете на маленьких экранах), вам может потребоваться вручную настроить атрибут sizes для достижения наилучших результатов.

format

Тип: ImageOutputFormat | undefined

Вы можете опционально указать тип файла изображения для вывода.

По умолчанию компонент <Image /> создает файл .webp.

quality

Тип: ImageQuality | undefined

quality — это необязательное свойство, которое может быть либо:

• предустановкой (low, mid, high, max), которая автоматически нормализуется между форматами.
• числом от 0 до 100 (интерпретируется по-разному в разных форматах).

inferSize

Тип: boolean
По умолчанию: false

Добавлено в: astro@4.4.0

Позволяет автоматически установить оригинальные width и height удаленного изображения.

По умолчанию это значение установлено в false, и вы должны вручную указать оба размера для вашего удаленного изображения.

Добавьте inferSize в компонент <Image /> (или inferSize: true в getImage()), чтобы вывести эти значения из содержимого изображения при получении. Это полезно, если вы не знаете размеров удаленного изображения или если они могут измениться:

src/components/MyComponent.astro

---
import { Image } from 'astro:assets';
---
<Image src="https://example.com/cat.png" inferSize alt="Кошка спит на солнце." />

inferSize может получить размеры удаленного изображения с домена, который не был авторизован, однако само изображение останется необработанным.

priority

Тип: boolean
По умолчанию: false

Добавлено в: astro@5.10.0

Позволяет автоматически устанавливать атрибуты loading, decoding и fetchpriority в их оптимальные значения для изображений, находящихся в верхней части страницы (above-the-fold).

src/components/MyComponent.astro

---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png';
---
<Image src={myImage} priority alt="Описание моего изображения" />

Когда priority="true" (или сокращенный синтаксис priority) добавляется в компонент <Image /> или <Picture />, он добавит следующие атрибуты, чтобы дать браузеру команду загрузить изображение немедленно:

loading="eager"
decoding="sync"
fetchpriority="high"

Эти отдельные атрибуты все еще можно установить вручную, если вам нужно настроить их дополнительно.

background

Тип: string | undefined

Добавлено в: astro@5.17.0 Новое

Цвет фона для использования при сведении слоев изображения (flattening) для преобразования его в запрошенный выходной format.

По умолчанию Sharp использует черный фон при сведении изображения. Указание другого цвета фона особенно полезно при преобразовании изображений с прозрачным фоном в формат, который не поддерживает прозрачность (например, .jpeg):

src/components/MyComponent.astro

---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png';
---
<Image
  src={myImage}
  alt="Описание моего изображения"
  format="jpeg"
  background="#ffffff"
/>

Значения передаются непосредственно в сервис изображений. Sharp принимает любое значение, которое может разобрать пакет color-string.

<Picture />

Добавлено в: astro@3.3.0

Компонент <Picture /> генерирует оптимизированное изображение с несколькими форматами и/или размерами.

Этот компонент также можно использовать для создания адаптивных изображений, которые могут подстраиваться под размер контейнера или размер и разрешение экрана устройства.

src/pages/index.astro

---
import { Picture } from 'astro:assets';
import myImage from "../assets/my_image.png"; // Изображение 1600x900
---

<!-- `alt` обязателен для компонента Picture -->
<Picture src={myImage} formats={['avif', 'webp']} alt="Описание моего изображения." />

<!-- Вывод -->
<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="Описание моего изображения."
  />
</picture>

<Picture /> принимает все свойства компонента <Image />, включая свойства адаптивного изображения, плюс следующие:

formats

Тип: ImageOutputFormat[]

Массив форматов изображений для использования в тегах <source>. Записи будут добавлены как элементы <source> в том порядке, в котором они перечислены, и этот порядок определяет, какой формат будет отображаться. Для наилучшей производительности указывайте самый современный формат первым (например, webp или avif). По умолчанию установлено значение ['webp'].

fallbackFormat

Тип: ImageOutputFormat

Формат, используемый в качестве запасного значения для тега <img>. По умолчанию .png для статических изображений (или .jpg, если изображение является JPG), .gif для анимированных изображений и .svg для файлов SVG.

pictureAttributes

Тип: HTMLAttributes<'picture'>

Объект атрибутов, которые будут добавлены к тегу <picture>.

Используйте это свойство для применения атрибутов к самому внешнему элементу <picture>. Атрибуты, примененные непосредственно к компоненту <Picture />, будут применяться к внутреннему элементу <img>, за исключением тех, которые используются для трансформации изображения.

src/components/MyComponent.astro

---
import { Picture } from "astro:assets";
import myImage from "../my_image.png"; // Изображение 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>

Свойства адаптивного изображения

Установка свойства layout на компоненте <Image /> или <Picture /> создает адаптивное изображение и включает дополнительные настройки свойств.

src/components/MyComponent.astro

---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png';
---
<Image src={myImage} alt="Описание моего изображения." layout='constrained' width={800} height={600} />

Когда задан макет (layout), атрибуты srcset и sizes генерируются автоматически на основе размеров изображения и типа макета. Предыдущий компонент <Image /> сгенерирует следующий HTML-код:

<img
  src="/_astro/my_image.hash3.webp"
  srcset="/_astro/my_image.hash1.webp 640w,
       /_astro/my_image.hash2.webp 750w,
       /_astro/my_image.hash3.webp 800w,
       /_astro/my_image.hash4.webp 828w,
       /_astro/my_image.hash5.webp 1080w,
       /_astro/my_image.hash6.webp 1280w,
       /_astro/my_image.hash7.webp 1600w"
  alt="Описание моего изображения"
  sizes="(min-width: 800px) 800px, 100vw"
  loading="lazy"
  decoding="async"
  fetchpriority="auto"
  width="800"
  height="600"
  style="--fit: cover; --pos: center;"
  data-astro-image="constrained"
>

Значение layout также определяет стили по умолчанию, применяемые к тегу <img>, чтобы определить, как изображение должно изменять размер в соответствии с его контейнером:

Стили адаптивного изображения

:where([data-astro-image]) {
  object-fit: var(--fit);
  object-position: var(--pos);
}
:where([data-astro-image='full-width']) {
  width: 100%;
}
:where([data-astro-image='constrained']) {
  max-width: 100%;
}

Вы можете переопределить стили object-fit и object-position по умолчанию, установив пропсы fit и position в компоненте <Image /> или <Picture />.

layout

Тип: 'constrained' | 'full-width' | 'fixed' | 'none'
По умолчанию: image.layout | 'none'

Добавлено в: astro@5.10.0

Определяет адаптивное изображение и то, как изображение должно изменять размер при изменении размера его контейнера. Может использоваться для переопределения значения по умолчанию, настроенного для image.layout.

• constrained — Изображение будет уменьшаться, чтобы соответствовать контейнеру, сохраняя соотношение сторон, но не будет увеличиваться больше указанных width и height или оригинальных размеров изображения.

  Используйте это, если вы хотите, чтобы изображение отображалось в запрошенном размере, где это возможно, но сжималось, чтобы поместиться на экранах меньшего размера. Это соответствует поведению по умолчанию для изображений при использовании Tailwind. Если вы не уверены, это, вероятно, тот макет, который вам следует выбрать.

• full-width — Изображение будет масштабироваться, чтобы соответствовать ширине контейнера, сохраняя соотношение сторон.

  Используйте это для hero-изображений или других изображений, которые должны занимать всю ширину страницы.

• fixed — Изображение сохранит запрошенные размеры и не будет изменять размер. Оно сгенерирует srcset для поддержки дисплеев с высокой плотностью, но не для разных размеров экрана.

  Используйте это, если изображение не будет менять размер, например, для иконок или логотипов меньше ширины любого экрана, или других изображений в контейнере фиксированной ширины.

• none — Изображение не будет адаптивным. srcset или sizes не будут генерироваться автоматически, и стили не будут применяться.

  Это полезно, если вы включили макет по умолчанию, но хотите отключить его для конкретного изображения.

Например, если constrained установлен как макет по умолчанию, вы можете переопределить свойство layout любого отдельного изображения:

src/components/MyComponent.astro

---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png';
---
<Image src={myImage} alt="Это будет использовать constrained макет" width={800} height={600} />
<Image src={myImage} alt="Это будет использовать full-width макет" layout="full-width" />
<Image src={myImage} alt="Это отключит адаптивность" layout="none" />

fit

Тип: 'contain' | 'cover' | 'fill' | 'none' | 'scale-down'
По умолчанию: image.objectFit | 'cover'

Добавлено в: astro@5.10.0

Включено, когда свойство layout установлено или настроено. Определяет, как адаптивное изображение должно быть обрезано, если его соотношение сторон изменено.

Значения соответствуют значениям CSS object-fit. По умолчанию cover или значение image.objectFit, если оно установлено. Может использоваться для переопределения стилей object-fit по умолчанию.

position

Тип: string
По умолчанию: image.objectPosition | 'center'

Добавлено в: astro@5.10.0

Включено, когда свойство layout установлено или настроено. Определяет положение обрезки изображения для адаптивного изображения, если соотношение сторон изменено.

Значения соответствуют значениям CSS object-position. По умолчанию center или значение image.objectPosition, если оно установлено. Может использоваться для переопределения стилей object-position по умолчанию.

getImage()

Тип: (options: UnresolvedImageTransform) => Promise<GetImageResult>

Осторожно

getImage() полагается на API, доступные только на сервере, и прерывает сборку при использовании на клиенте.

Функция getImage() предназначена для генерации изображений, которые будут использоваться где-то еще, кроме как непосредственно в HTML, например, в маршруте API. Она также позволяет вам создать свой собственный пользовательский компонент <Image />.

Она принимает объект опций с теми же свойствами, что и компонент Image (кроме alt) и возвращает объект GetImageResult.

Следующий пример генерирует AVIF background-image для <div />:

src/components/Background.astro

---
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});`}><slot /></div>

inferRemoteSize()

Тип: (url: string) => Promise<Omit<ImageMetadata, ‘src’ | ‘fsPath’>>

Добавлено в: astro@4.12.0

Функция для автоматической установки оригинальных width и height удаленного изображения. Может использоваться как альтернатива передаче свойства inferSize.

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

getConfiguredImageService()

Тип: () => Promise<ImageService>

Добавлено в: astro@2.1.3

Извлекает настроенный сервис изображений.

imageConfig

Тип: AstroConfig["image"]

Добавлено в: astro@3.0.9

Параметры конфигурации для изображений, установленные пользователем и объединенные со всеми значениями по умолчанию.

Типы astro:assets

Следующие типы импортируются из виртуального модуля astro:assets:

import type {
  LocalImageProps,
  RemoteImageProps,
} from "astro/assets";

LocalImageProps

Тип: ImageSharedProps<T> & { src: ImageMetadata | Promise<{ default: ImageMetadata; }> }

Описывает свойства локального изображения. Это гарантирует, что src соответствует форме импортированного изображения.

Узнайте больше об импортированных изображениях в src/ с примером использования.

RemoteImageProps

Типы:

• ImageSharedProps<T> & { src: string; inferSize: true; }
• ImageSharedProps<T> & { src: string; inferSize?: false | undefined; }

Описывает свойства удаленного изображения. Это гарантирует, что когда inferSize не предоставлено или установлено в false, оба свойства width и height обязательны.

Импорт из astro/assets

Следующие помощники импортируются из обычного модуля astro/assets:

import {
  baseService,
  getConfiguredImageService,
  getImage,
  isLocalService,
} from "astro/assets";

baseService

Тип: Omit<LocalImageService, ‘transform’>

Встроенный локальный сервис изображений, который можно расширить для создания пользовательского сервиса изображений.

Следующий пример повторно использует baseService для создания нового сервиса изображений:

src/image-service.ts

import { baseService } from "astro/assets";

const newImageService = {
 getURL: baseService.getURL,
 parseURL: baseService.parseURL,
 getHTMLAttributes: baseService.getHTMLAttributes,
 async transform(inputBuffer, transformOptions) {...}
}

getConfiguredImageService()

Смотрите getConfiguredImageService() из astro:assets.

getImage()

Тип: (options: UnresolvedImageTransform, imageConfig: AstroConfig[‘image’]) => Promise<GetImageResult>

Функция, похожая на getImage() из astro:assets, с двумя обязательными аргументами: объект options с теми же свойствами, что и у компонента Image, и второй объект для конфигурации изображений.

isLocalService()

Тип: (service: ImageService | undefined) => boolean

Проверяет тип сервиса изображений и возвращает true, когда это локальный сервис.

Типы astro/assets

Следующие типы импортируются из обычного модуля astro/assets:

import type {
  LocalImageProps,
  RemoteImageProps,
} from "astro/assets";

LocalImageProps

Смотрите LocalImageProps из astro:assets.

RemoteImageProps

Смотрите RemoteImageProps из astro:assets.

Импорт из astro/assets/utils

Следующие помощники импортируются из директории utils обычного модуля astro/assets и могут быть использованы для создания сервиса изображений:

import {
  isRemoteAllowed,
  matchHostname,
  matchPathname,
  matchPattern,
  matchPort,
  matchProtocol,
  isESMImportedImage,
  isRemoteImage,
  resolveSrc,
  imageMetadata,
  emitImageMetadata,
  getOrigQueryParams,
  inferRemoteSize,
  propsToFilename,
  hashTransform,
  /* Следующие являются устаревшими: */
  emitESMImage,
} from "astro/assets/utils";

isRemoteAllowed()

Тип: (src: string, { domains, remotePatterns }: { domains: string[], remotePatterns: RemotePattern[] }) => boolean

Добавлено в: astro@4.0.0

Определяет, разрешен ли данный удаленный ресурс, идентифицируемый по его исходному URL, на основе указанных доменов и удаленных шаблонов.

import { isRemoteAllowed } from 'astro/assets/utils';

const url = new URL('https://example.com/images/test.jpg');
const domains = ['example.com', 'anotherdomain.com'];
const remotePatterns = [
  {
    protocol: 'https',
    hostname: 'images.example.com',
    pathname: '/**', // Разрешить любой путь под этим именем хоста
  }
];

isRemoteAllowed(url.href, { domains, remotePatterns }); // Вывод: `true`

matchHostname()

Тип: (url: URL, hostname?: string, allowWildcard = false) => boolean

Добавлено в: astro@4.0.0

Сопоставляет имя хоста заданного URL с указанным именем хоста, с опциональной поддержкой шаблонов подстановки (wildcard).

import { matchHostname } from 'astro/assets/utils';

const url = new URL('https://sub.example.com/path/to/resource');

matchHostname(url, 'example.com'); // Вывод: `false`
matchHostname(url, 'example.com', true); // Вывод: `true`

matchPathname()

Тип: (url: URL, pathname?: string, allowWildcard = false) => boolean

Добавлено в: astro@4.0.0

Сопоставляет путь заданного URL с указанным шаблоном, с опциональной поддержкой подстановок.

import { matchPathname } from 'astro/assets/utils';

const testURL = new URL('https://example.com/images/photo.jpg');

matchPathname(testURL, '/images/photo.jpg'); // Вывод: `true`
matchPathname(testURL, '/images/'); // Вывод: `false`
matchPathname(testURL, '/images/*', true); // Вывод: `true`

matchPattern()

Тип: (url: URL, remotePattern: RemotePattern) => boolean

Добавлено в: astro@4.0.0

Оценивает, соответствует ли заданный URL указанному удаленному шаблону на основе протокола, имени хоста, порта и пути.

import { matchPattern } from 'astro/assets/utils';

const url = new URL('https://images.example.com/photos/test.jpg');
const remotePattern = {
  protocol: 'https',
  hostname: 'images.example.com',
  pathname: '/photos/**', // Разрешить все файлы в /photos/
};

matchPattern(url, remotePattern); // Вывод: `true`

matchPort()

Тип: (url: URL, port?: string) => boolean
По умолчанию: true

Добавлено в: astro@4.0.0

Проверяет, соответствует ли порт заданного URL указанному порту. Если порт не указан, возвращает true.

import { matchPort } from 'astro/assets/utils';

const urlWithPort = new URL('https://example.com:8080/resource');
const urlWithoutPort = new URL('https://example.com/resource');

matchPort(urlWithPort, '8080'); // Вывод: `true`
matchPort(urlWithoutPort, '8080'); // Вывод: `false`

matchProtocol()

Тип: (url: URL, protocol?: string) => boolean
По умолчанию: true

Добавлено в: astro@4.0.0

Сравнивает протокол предоставленного URL с указанным протоколом. Возвращает true, если протокол совпадает или если протокол не указан.

import { matchProtocol } from 'astro/assets/utils';

const secureUrl = new URL('https://example.com/resource');
const regularUrl = new URL('http://example.com/resource');

matchProtocol(secureUrl, 'https'); // Вывод: `true`
matchProtocol(regularUrl, 'https'); // Вывод: `false`

isESMImportedImage()

Тип: (src: ImageMetadata | string) => boolean

Добавлено в: astro@4.0.0

Определяет, является ли данный источник изображением, импортированным через ECMAScript Module (ESM).

isRemoteImage()

Тип: (src: ImageMetadata | string) => boolean

Добавлено в: astro@4.0.0

Определяет, является ли предоставленный источник URL-адресом удаленного изображения в виде строки.

resolveSrc()

Тип: (src: UnresolvedImageTransform[‘src’]) => Promise<string | ImageMetadata>

Добавлено в: astro@4.0.0

Возвращает источник изображения. Эта функция гарантирует, что если src является Promise (например, динамический import()), он будет ожидаться, и будет извлечен правильный src. Если src уже является разрешенным значением, он возвращается как есть.

imageMetadata()

Тип: (data: Uint8Array, src?: string) => Promise<Omit<ImageMetadata, ‘src’ | ‘fsPath’>>

Добавлено в: astro@4.0.0

Извлекает метаданные изображения, такие как размеры, формат и ориентация, из предоставленных данных изображения.

emitImageMetadata()

Тип: (id: string | undefined, fileEmitter?: Rollup.EmitFile) => Promise<(ImageMetadata & { contents?: Buffer }) | undefined>

Добавлено в: astro@5.7.0

Обрабатывает файл изображения и выдает его метаданные и, опционально, его содержимое. В режиме сборки функция использует fileEmitter для генерации ссылки на актив. В режиме разработки она разрешается в локальный URL-адрес файла с параметрами запроса для метаданных.

getOrigQueryParams()

Тип: (params: URLSearchParams) => Pick<ImageMetadata, ‘width’ | ‘height’ | ‘format’> | undefined

Добавлено в: astro@4.0.0

Извлекает width, height и format изображения из объекта URLSearchParams. Если какой-либо из этих параметров отсутствует или недействителен, функция возвращает undefined.

inferRemoteSize()

Тип: (url: string) => Promise<Omit<ImageMetadata, ‘src’ | ‘fsPath’>>

Добавлено в: astro@4.0.0

Выводит размеры удаленного изображения путем потоковой передачи его данных и анализа их по мере поступления до тех пор, пока не будет доступно достаточно метаданных.

propsToFilename()

Тип: (filePath: string, transform: ImageTransform, hash: string) => string

Добавлено в: astro@4.0.0

Генерирует отформатированное имя файла для изображения на основе его исходного пути, свойств трансформации и уникального хеша.

Отформатированное имя файла следует этой структуре:

<prefixDirname>/<baseFilename>_<hash><outputExtension>

• prefixDirname: Если изображение является импортированным ESM-изображением, это имя каталога исходного пути файла; в противном случае это будет пустая строка.
• baseFilename: Базовое имя файла или хешированное короткое имя, если файл является data: URI.
• hash: Уникальная строка хеша, сгенерированная для различения преобразованного файла.
• outputExtension: Желаемое расширение выходного файла, полученное из transform.format или исходного расширения файла.

import { propsToFilename } from 'astro/assets/utils';

const filePath = '/images/photo.jpg';
const transform = { format: 'png', src: filePath };
const hash = 'abcd1234';

const filename = propsToFilename(filePath, transform, hash);
// Пример значения: '/images/photo_abcd1234.png'

hashTransform()

Тип: (transform: ImageTransform, imageService: string, propertiesToHash: string[]) => string

Добавлено в: astro@4.0.0

Преобразует предоставленный объект transform в строку хеша на основе выбранных свойств и указанного imageService.

import { hashTransform } from 'astro/assets/utils';

const transform = {
  src: '/images/photo.jpg',
  width: 800,
  height: 600,
  format: 'jpg',
};
const imageService = 'astro/assets/services/sharp';
const propertiesToHash = ['width', 'height', 'format'];

const hash = hashTransform(transform, imageService, propertiesToHash);
// Пример значения: 'd41d8cd98f00b204e9800998ecf8427e'

emitESMImage()

Устарело

Вместо этого используйте функцию emitImageMetadata.

Тип: (id: string | undefined, _watchMode: boolean, experimentalSvgEnabled: boolean, fileEmitter?: Rollup.EmitFile) => Promise<(ImageMetadata & { contents?: Buffer }) | undefined>

Добавлено в: astro@4.0.0

Обрабатывает файл изображения и выдает его метаданные и, опционально, его содержимое. В режиме сборки функция использует fileEmitter для генерации ссылки на актив. В режиме разработки она разрешается в локальный URL-адрес файла с параметрами запроса для метаданных.

Типы astro

import type {
  GetImageResult,
  ImageTransform,
  UnresolvedImageTransform,
  ImageMetadata,
  ImageInputFormat,
  ImageOutputFormat,
  ImageQuality,
  ImageQualityPreset,
  RemotePattern,
  ImageService,
  ExternalImageService,
  LocalImageService,
  ImageServiceConfig,
} from "astro";

GetImageResult

Тип: object

Добавлено в: astro@2.2.0

Описывает результат трансформации после вызова getImage().

attributes

Тип: Record<string, any>

Определяет дополнительные HTML-атрибуты, необходимые для рендеринга изображения (например, width, height, style).

options

Тип: ImageTransform

Описывает настройки трансформации после валидации.

rawOptions

Тип: ImageTransform

Описывает оригинальные настройки трансформации.

src

Тип: string

Путь к сгенерированному изображению.

srcSet

Тип: { values: { transform: ImageTransform; descriptor?: string; attributes?: Record<string, any>; url: string; }[]; attribute: string; }

Добавлено в: astro@3.3.0

Объект, описывающий, как рендерить атрибут srcset.

values

Тип: { transform: ImageTransform; descriptor?: string; attributes?: Record<string, any>; url: string; }[]

Массив сгенерированных значений, где каждая запись включает URL и дескриптор размера. Это можно использовать для ручной генерации значения атрибута srcset.

attribute

Тип: string

Значение, готовое к использованию в атрибуте srcset.

ImageTransform

Тип: object

Определяет опции, принимаемые сервисом трансформации изображений. Содержит обязательное свойство src, необязательные предопределенные свойства и любые дополнительные свойства, требуемые сервисом изображений:

src

Тип: ImageMetadata | string

Определяет путь к локальному изображению в директории public, URL удаленного изображения или данные импортированного изображения.

width

Тип: number | undefined

Ширина изображения.

height

Тип: number | undefined

Высота изображения.

widths

Тип: number[] | undefined

Добавлено в: astro@3.3.0

Список ширин для генерации изображения.

densities

Тип: (number | `${number}x`)[] | undefined

Добавлено в: astro@3.3.0

Список плотностей пикселей для генерации изображения.

quality

Тип: ImageQuality | undefined

Желаемое качество выходного изображения.

format

Тип: ImageOutputFormat | undefined

Желаемый формат выходного изображения.

fit

Тип: 'fill' | 'contain' | 'cover' | 'none' | 'scale-down' | string | undefined

Добавлено в: astro@5.0.0

Определяет список допустимых значений для CSS-свойства object-fit, расширяемый любой строкой.

position

Тип: string | undefined

Добавлено в: astro@5.0.0

Управляет значением для CSS-свойства object-position.

UnresolvedImageTransform

Тип: Omit<ImageTransform, “src”> & { src: ImageMetadata | string | Promise<{ default: ImageMetadata }>; inferSize?: boolean; }

Представляет изображение с опциями трансформации. Содержит те же свойства, что и тип ImageTransform, но с другим типом src и дополнительным свойством inferSize.

src

Тип: ImageMetadata | string | Promise<{ default: ImageMetadata }>

Путь к изображению, импортированному или расположенному в директории public, или URL удаленного изображения.

inferSize

Тип: boolean

Определяет, должны ли быть выведены ширина и высота изображения.

Смотрите также атрибут inferSize, доступный в <Image />.

ImageMetadata

Тип: { src: string; width: number; height: number; format: ImageInputFormat; orientation?: number; }

Добавлено в: astro@2.1.3

Описывает данные, собранные во время импорта изображения. Содержит следующие свойства:

src

Тип: string

Абсолютный путь к изображению в файловой системе.

width

Тип: number

Ширина изображения.

height

Тип: number

Высота изображения.

format

Тип: ImageInputFormat

Формат изображения.

orientation

Тип: number

Добавлено в: astro@2.8.3

Ориентация изображения, если его метаданные содержат эту информацию.

ImageInputFormat

Тип: "jpeg" | "jpg" | "png" | "tiff" | "webp" | "gif" | "svg" | "avif"

Добавлено в: astro@2.2.0

Описывает объединение поддерживаемых форматов для импортированных изображений.

ImageOutputFormat

Тип: string | "jpeg" | "jpg" | "png" | "webp" | "svg" | "avif"

Добавлено в: astro@2.2.0

Указывает формат для выходных изображений. Это может быть предопределенный литерал или любая строка.

ImageQuality

Тип: ImageQualityPreset | number

Добавлено в: astro@2.2.0

Представляет воспринимаемое качество выходного изображения как объединение предопределенных литералов, строки или числа.

ImageQualityPreset

Тип: string | "low" | "mid" | "high" | "max"

Добавлено в: astro@2.2.0

Определяет доступные пресеты для управления качеством изображения, расширяемые любой строкой.

RemotePattern

Тип: { hostname?: string; pathname?: string; protocol?: string; port?: string; }

Добавлено в: astro@5.14.2

Описывает удаленный хост через четыре необязательных свойства: hostname, pathname, protocol и port.

ImageService

Тип: ExternalImageService | LocalImageService

Определяет хуки, которые должен предоставлять локальный или внешний сервис изображений.

ExternalImageService

Тип: object

Определяет хуки, которые должен предоставлять внешний сервис трансформации изображений. Требует хук getUrl() и поддерживает три дополнительных хука.

Узнайте, как создавать внешние сервисы в справочнике API Image Service с примерами использования.

LocalImageService

Тип: object

Определяет хуки, которые должен предоставлять локальный сервис трансформации изображений. Требует хуки getUrl(), parseUrl() и transform(), а также поддерживает дополнительные хуки.

Узнайте, как создавать локальные сервисы в справочнике API Image Service с примерами использования.

ImageServiceConfig

Тип: { entrypoint: 'astro/assets/services/sharp' | string; config?: T; }

Добавлено в: astro@2.3.3

Описывает объект конфигурации для сервиса изображений. Содержит следующие свойства:

entrypoint

Тип: 'astro/assets/services/sharp' | string

Пакет или путь к модулю сервиса изображений. Это может быть встроенный сервис Sharp в Astro или сторонний сервис.

config

Тип: Record<string, any>

Объект конфигурации, передаваемый в сервис изображений. Форма зависит от конкретного используемого сервиса.