Изображения

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

В Astro встроены компоненты <Image /> и <Picture />, поддержка Markdown-синтаксиса (![]()), SVG-компоненты и функция генерации изображений для оптимизации и трансформации ваших файлов. Кроме того, вы можете настроить автоматическое создание адаптивных изображений по умолчанию.

Вы всегда можете использовать обычные HTML-теги <img> или <svg> в файлах .astro или Markdown. Однако в этом случае Astro не будет выполнять никакой оптимизации или обработки этих изображений.

В Astro нет нативной поддержки видео; мы рекомендуем использовать сторонние хостинги видео (EN) для стриминга и оптимизации видеоконтента.

См. полный справочник API для компонентов <Image /> и <Picture />.

Где хранить изображения

src/ против public/

Мы рекомендуем хранить локальные изображения в папке src/, чтобы Astro мог их трансформировать, оптимизировать и включать в общую сборку. Файлы в папке public/ всегда отдаются браузеру «как есть» без какой-либо обработки.

Изображения в src/ могут использоваться во всех файлах проекта: .astro, .md, .mdx и компонентах других фреймворков через обычный импорт.

Используйте папку public/, если хотите избежать обработки. Такие изображения доступны через URL-пути относительно вашего домена. Например, фавикон (favicon) сайта обычно размещают в корне этой папки.

Удаленные изображения

Вы можете хранить изображения удаленно в CMS (EN) или на платформе управления цифровыми активами (DAM) (EN). Astro может получать эти данные через API или отображать изображения по прямым ссылкам.

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

Изображения в файлах .astro

Варианты: <Image />, <Picture />, <img>, <svg>, SVG-компоненты

В шаблонах Astro вы можете использовать компонент <Image /> для рендеринга оптимизированных изображений и компонент <Picture /> для генерации различных форматов и размеров. Оба компонента поддерживают свойства адаптивности.

Также вы можете импортировать и использовать SVG-файлы как компоненты.

Обычные HTML-теги <img> и <svg> также доступны. Изображения в теге <img> не обрабатываются и копируются в папку сборки без изменений.

Значение атрибута src зависит от места хранения файла:

• Для локальных изображений в src/ используйте относительный путь при импорте. Компоненты <Image /> и <Picture /> используют сам импорт (например, src={rocket}), а тег <img> — свойство .src этого импорта (например, src={rocket.src}).

• Для удаленных изображений и файлов из public/ используйте строковый URL-путь. Указывайте полный URL для внешних ссылок или относительный путь для папки public/ (например, src="/images/my-image.jpg" для файла в public/images/my-image.jpg).

src/pages/blog/my-images.astro

---
import { Image } from 'astro:assets';
import localBirdImage from '../../images/localBirdImage.png';
---
<Image src={localBirdImage} alt="Птица в гнезде." />
<Image src="/images/public-bird.jpg" alt="Птица." width="50" height="50" />
<Image src="https://example.com/remote-bird.jpg" alt="Птица." width="50" height="50" />

<img src={localBirdImage.src} alt="Птица в гнезде.">

Изображения в файлах Markdown

Варианты: ![](), <img> (только для public или удаленных изображений)

Используйте стандартный синтаксис Markdown ![alt](src). Локальные изображения в src/ и удаленные изображения будут оптимизированы. Если настроено глобальное поведение адаптивности, эти изображения также станут адаптивными.

Файлы из папки public/ никогда не оптимизируются.

src/pages/post-1.md

# Моя страница Markdown

<!-- Локальное изображение в src/assets/ -->
![Звездное небо.](../assets/stars.png)

<!-- Изображение в public/images/ -->
![Звездное небо.](/images/stars.png)

<!-- Удаленное изображение -->
![Astro](https://example.com/images/remote-image.png)

Тег <img> можно использовать для public или удаленных изображений без оптимизации. Локальные файлы из src в теге <img> в Markdown не поддерживаются.

Компоненты <Image /> и <Picture /> недоступны в .md файлах. Если вам нужно больше контроля над атрибутами, используйте интеграцию MDX.

Изображения в компонентах UI-фреймворков

Варианты: стандартный синтаксис фреймворка (например, <img /> в JSX)

Локальные изображения должны быть сначала импортированы. Затем их можно использовать в привычном для фреймворка синтаксисе:

src/components/ReactImage.jsx

import stars from "../assets/stars.png";

export default function ReactImage() {
  return <img src={stars.src} alt="Звездное небо." />;
}

Компоненты Astro (например, <Image />) недоступны внутри компонентов фреймворков. Однако вы можете передать их как дочерние элементы внутри .astro файла.

Компоненты Astro для изображений

<Image />

Используйте компонент <Image /> для отображения оптимизированных версий локальных и разрешенных удаленных изображений.

Компонент позволяет изменять размеры, тип файла и качество. Трансформация происходит во время сборки (для статичных страниц) или «на лету» (для страниц по запросу). Итоговый тег <img> включает атрибуты alt, loading, decoding и автоматически вычисляет размеры для предотвращения Cumulative Layout Shift (CLS).

Что такое CLS?

Cumulative Layout Shift (CLS) — это метрика Core Web Vitals, измеряющая смещение контента при загрузке страницы. <Image /> оптимизирует CLS, автоматически устанавливая правильные width и height.

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

<Picture />

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

Используйте компонент <Picture /> для генерации тега <picture> с поддержкой нескольких форматов и размеров. Это позволяет браузеру выбирать оптимальный формат (например, AVIF или WebP), оставляя стандартный формат (PNG/JPG) в качестве запасного.

---
import { Picture } from 'astro:assets';
import myImage from '../assets/my_image.png';
---
<Picture src={myImage} formats={['avif', 'webp']} alt="Описание." />

Адаптивные изображения

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

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

При настройке глобального параметра image.layout это поведение применится ко всем компонентам и даже к изображениям в Markdown.

Заметка

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

SVG-компоненты

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

Astro позволяет импортировать SVG-файлы и использовать их как обычные компоненты. Содержимое SVG будет встроено (inline) прямо в HTML-код.

---
import Logo from './logo.svg';
---
<Logo width={64} height={64} fill="currentColor" />

Отображение необработанных изображений через <img>

Вы можете писать тег <img> напрямую. В этом случае Astro не будет оптимизировать файл.

Изображения в src/

Для использования локального изображения в теге <img> его нужно импортировать. Импортированный объект соответствует типу ImageMetadata:

interface ImageMetadata {
  src: string;
  width: number;
  height: number;
  format: string;
}

---
import myDog from '../../images/dog.jpg';
---
<img src={myDog.src} width={myDog.width} height={myDog.height} alt="Собака." />

Авторизация удаленных изображений

Настройте списки разрешенных доменов для оптимизации через image.domains или image.remotePatterns. Это защищает ваш сайт от нежелательного использования ресурсов внешними сервисами.

astro.config.mjs

export default defineConfig({
  image: {
    domains: ["astro.build"],
    remotePatterns: [{ protocol: "https" }],
  }
});

Изображения в коллекциях контента

Вы можете объявить изображение в метаданных (frontmatter) записи коллекции:

src/content/blog/my-post.md

---
title: "Мой пост"
cover: "./cover.jpeg"
coverAlt: "Закат в горах."
---

И используйте хелпер image() в схеме для валидации:

const blogCollection = defineCollection({
  schema: ({ image }) => z.object({
    title: z.string(),
    cover: image(),
    coverAlt: z.string(),
  }),
});

Alt-текст

Доступность (A11y) крайне важна. Всегда используйте атрибут alt для описания изображений. Для декоративных элементов, не несущих смысловой нагрузки, устанавливайте alt="", чтобы экранные дикторы игнорировали их.