Компонент <Image>

Полезно знать: Если вы используете версию Next.js до 13, обратитесь к документации next/legacy/image, так как компонент был переименован.

Этот справочник API поможет вам понять, как использовать пропсы и параметры конфигурации, доступные для компонента Image. Для информации о функциях и использовании см. страницу Компонент Image.

import Image from 'next/image'

export default function Page() {
  return (
    <Image
      src="/profile.png"
      width={500}
      height={500}
      alt="Picture of the author"
    />
  )
}

Пропсы

Вот сводка пропсов, доступных для компонента Image:

Обязательные пропсы

Компонент Image требует следующие свойства: src, width, height и alt.

import Image from 'next/image'

export default function Page() {
  return (
    <div>
      <Image
        src="/profile.png"
        width={500}
        height={500}
        alt="Picture of the author"
      />
    </div>
  )
}

src

Может быть одним из следующих:

• Статически импортированный файл изображения
• Строка пути. Это может быть абсолютный внешний URL или внутренний путь в зависимости от пропса loader.

При использовании внешнего URL необходимо добавить его в remotePatterns в next.config.js.

width

Свойство width представляет отображаемую ширину в пикселях, поэтому оно влияет на размер изображения.

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

height

Свойство height представляет отображаемую высоту в пикселях, поэтому оно влияет на размер изображения.

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

alt

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

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

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

Подробнее

Опциональные пропсы

Компонент <Image /> принимает ряд дополнительных свойств помимо обязательных. В этом разделе описаны наиболее часто используемые свойства компонента Image. Подробности о более редко используемых свойствах см. в разделе Расширенные пропсы.

loader

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

loader — это функция, возвращающая строку URL для изображения, принимая следующие параметры:

• src
• width
• quality

Вот пример использования пользовательского загрузчика:

import Image from 'next/image'

const imageLoader = ({ src, width, quality }) => {
  return `https://example.com/${src}?w=${width}&q=${quality || 75}`
}

export default function Page() {
  return (
    <Image
      loader={imageLoader}
      src="me.png"
      alt="Picture of the author"
      width={500}
      height={500}
    />
  )
}

Альтернативно, вы можете использовать конфигурацию loaderFile в next.config.js для настройки каждого экземпляра next/image в вашем приложении без передачи пропса.

fill

fill={true} // {true} | {false}

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

Родительский элемент должен иметь стиль position: "relative", position: "fixed" или position: "absolute".

По умолчанию элементу img автоматически назначается стиль position: "absolute".

Если к изображению не применяются стили, изображение растянется, чтобы заполнить контейнер. Возможно, вы предпочтете установить object-fit: "contain" для изображения, которое будет вписано в контейнер с сохранением пропорций.

Альтернативно, object-fit: "cover" заставит изображение заполнить весь контейнер и обрезаться для сохранения пропорций. Чтобы это выглядело правильно, родительский элемент должен иметь стиль overflow: "hidden".

Для получения дополнительной информации см. также:

• position
• object-fit
• object-position

sizes

Строка, похожая на медиа-запрос, которая предоставляет информацию о том, насколько широким будет изображение при разных точках останова. Значение sizes значительно влияет на производительность для изображений, использующих fill или стилизованных под адаптивный размер.

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

• Во-первых, значение sizes используется браузером для определения, какой размер изображения загружать из автоматически сгенерированного srcset next/image. Когда браузер делает выбор, он еще не знает размер изображения на странице, поэтому выбирает изображение того же размера или больше, чем область просмотра. Свойство sizes позволяет сообщить браузеру, что изображение на самом деле будет меньше, чем полный экран. Если вы не укажете значение sizes для изображения со свойством fill, по умолчанию будет использоваться значение 100vw (ширина полного экрана).
• Во-вторых, свойство sizes изменяет поведение автоматически сгенерированного значения srcset. Если значение sizes отсутствует, генерируется небольшой srcset, подходящий для изображения фиксированного размера (1x/2x и т.д.). Если sizes определен, генерируется большой srcset, подходящий для адаптивного изображения (640w/750w и т.д.). Если свойство sizes включает такие значения, как 50vw, которые представляют процент от ширины области просмотра, то srcset обрезается, чтобы исключить любые значения, которые слишком малы для необходимости.

Например, если вы знаете, что ваш стиль заставит изображение быть во всю ширину на мобильных устройствах, в 2-колоночном макете на планшетах и в 3-колоночном макете на десктопах, вы должны включить свойство sizes, например:

import Image from 'next/image'

export default function Page() {
  return (
    <div className="grid-element">
      <Image
        fill
        src="/example.png"
        sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
      />
    </div>
  )
}

Этот пример sizes может иметь драматический эффект на метрики производительности. Без 33vw размеров изображение, выбранное с сервера, будет в 3 раза шире, чем необходимо. Поскольку размер файла пропорционален квадрату ширины, без sizes пользователь загрузит изображение, которое в 9 раз больше, чем необходимо.

Узнайте больше о srcset и sizes:

• web.dev
• mdn

quality

quality={75} // {number 1-100}

Качество оптимизированного изображения, целое число от 1 до 100, где 100 — наилучшее качество и, следовательно, наибольший размер файла. По умолчанию 75.

Если в next.config.js определена конфигурация qualities, пропс quality должен соответствовать одному из значений, определенных в конфигурации.

Полезно знать: Если исходное изображение уже было низкого качества, установка пропса quality слишком высокой может привести к тому, что результирующее оптимизированное изображение будет больше исходного.

priority

priority={false} // {false} | {true}

Когда true, изображение считается высокоприоритетным и предзагружается. Ленивая загрузка автоматически отключается для изображений с priority.

Вы должны использовать свойство priority для любого изображения, обнаруженного как Наибольший контентный отрисовываемый элемент (LCP). Может быть уместно иметь несколько приоритетных изображений, так как разные изображения могут быть LCP-элементами для разных размеров области просмотра.

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

placeholder

placeholder = 'empty' // "empty" | "blur" | "data:image/..."

Заполнитель, используемый во время загрузки изображения. Возможные значения: blur, empty или data:image/.... По умолчанию empty.

Когда blur, свойство blurDataURL будет использоваться в качестве заполнителя. Если src — это объект из статического импорта и импортированное изображение имеет расширение .jpg, .png, .webp или .avif, то blurDataURL будет автоматически заполнен, за исключением случаев, когда изображение является анимированным.

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

Когда data:image/..., Data URL будет использоваться в качестве заполнителя во время загрузки изображения.

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

Попробуйте:

• Демонстрация заполнителя blur
• Демонстрация эффекта мерцания с пропсом placeholder в виде Data URL
• Демонстрация цветового эффекта с пропсом blurDataURL

Расширенные пропсы

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

style

Позволяет передавать CSS-стили для базового элемента изображения.

const imageStyle = {
  borderRadius: '50%',
  border: '1px solid #fff',
}

export default function ProfileImage() {
  return <Image src="..." style={imageStyle} />
}

Помните, что обязательные пропсы width и height могут взаимодействовать с вашими стилями. Если вы используете стили для изменения ширины изображения, вы также должны установить его высоту в auto, чтобы сохранить исходное соотношение сторон, или ваше изображение будет искажено.

onLoadingComplete

<Image onLoadingComplete={(img) => console.log(img.naturalWidth)} />

Предупреждение: Устарел, начиная с Next.js 14, в пользу onLoad.

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

Функция обратного вызова будет вызвана с одним аргументом — ссылкой на базовый элемент <img>.

onLoad

<Image onLoad={(e) => console.log(e.target.naturalWidth)} />

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

Функция обратного вызова будет вызвана с одним аргументом — Event, у которого target ссылается на базовый элемент <img>.

onError

<Image onError={(e) => console.error(e.target.id)} />

Функция обратного вызова, которая вызывается, если изображение не загружается.

loading

Рекомендация: Это свойство предназначено только для сложных случаев использования. Переключение изображения на загрузку с eager обычно ухудшает производительность. Вместо этого мы рекомендуем использовать свойство priority, которое будет активно предзагружать изображение.

loading = 'lazy' // {lazy} | {eager}

Поведение загрузки изображения. По умолчанию lazy.

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

При значении eager изображение загружается немедленно.

Узнайте больше об атрибуте loading.

blurDataURL

Data URL, который будет использоваться в качестве изображения-заполнителя до успешной загрузки изображения src. Эффект проявляется только в сочетании с placeholder="blur".

Должен быть изображением в кодировке base64. Оно будет увеличено и размыто, поэтому рекомендуется использовать очень маленькое изображение (10px или меньше). Использование больших изображений в качестве заполнителей может снизить производительность вашего приложения.

Попробуйте:

• Демонстрация стандартного свойства blurDataURL
• Демонстрация цветового эффекта с blurDataURL

Вы также можете сгенерировать Data URL сплошного цвета, чтобы он соответствовал изображению.

unoptimized

unoptimized = {false} // {false} | {true}

Если true, исходное изображение будет передаваться как есть, без изменения качества, размера или формата. По умолчанию false.

import Image from 'next/image'

const UnoptimizedImage = (props) => {
  return <Image {...props} unoptimized />
}

Начиная с Next.js 12.3.0, это свойство можно применить ко всем изображениям, обновив next.config.js следующей конфигурацией:

module.exports = {
  images: {
    unoptimized: true,
  },
}

overrideSrc

При передаче свойства src в компонент <Image>, атрибуты srcset и src генерируются автоматически для результирующего элемента <img>.

<Image src="/me.jpg" />

<img
  srcset="
    /_next/image?url=%2Fme.jpg&w=640&q=75 1x,
    /_next/image?url=%2Fme.jpg&w=828&q=75 2x
  "
  src="/_next/image?url=%2Fme.jpg&w=828&q=75"
/>

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

Например, при обновлении существующего веб-сайта с <img> до <Image> вы можете сохранить тот же атрибут src для целей SEO, таких как ранжирование изображений или избежание повторного сканирования.

<Image src="/me.jpg" overrideSrc="/override.jpg" />

<img
  srcset="
    /_next/image?url=%2Fme.jpg&w=640&q=75 1x,
    /_next/image?url=%2Fme.jpg&w=828&q=75 2x
  "
  src="/override.jpg"
/>

decoding

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

Возможные значения:

• async — Декодировать изображение асинхронно и разрешить отображение другого контента до завершения.
• sync — Декодировать изображение синхронно для атомарного отображения с другим контентом.
• auto — Нет предпочтений по режиму декодирования; браузер решает, что лучше.

Узнайте больше об атрибуте decoding.

Другие свойства

Остальные свойства компонента <Image /> будут переданы в базовый элемент img, за исключением следующих:

• srcSet. Вместо этого используйте Device Sizes.

Параметры конфигурации

В дополнение к свойствам, вы можете настроить компонент Image в next.config.js. Доступны следующие опции:

localPatterns

Вы можете дополнительно настроить localPatterns в файле next.config.js, чтобы разрешить оптимизацию определенных путей и заблокировать все остальные.

module.exports = {
  images: {
    localPatterns: [
      {
        pathname: '/assets/images/**',
        search: '',
      },
    ],
  },
}

Полезно знать: В примере выше свойство src next/image должно начинаться с /assets/images/ и не должно содержать строки запроса. Попытка оптимизировать любой другой путь вернет 400 Bad Request.

remotePatterns

Для защиты вашего приложения от злоумышленников требуется настройка для использования внешних изображений. Это гарантирует, что только внешние изображения из вашего аккаунта могут быть обработаны API оптимизации изображений Next.js. Эти внешние изображения можно настроить с помощью свойства remotePatterns в файле next.config.js, как показано ниже:

module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'example.com',
        port: '',
        pathname: '/account123/**',
        search: '',
      },
    ],
  },
}

Полезно знать: В примере выше свойство src next/image должно начинаться с https://example.com/account123/ и не должно содержать строки запроса. Любой другой протокол, имя хоста, порт или несоответствующий путь вернет 400 Bad Request.

Ниже приведен пример свойства remotePatterns в файле next.config.js с использованием шаблона с подстановочными знаками в hostname:

module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: '**.example.com',
        port: '',
        search: '',
      },
    ],
  },
}

Полезно знать: В примере выше свойство src next/image должно начинаться с https://img1.example.com или https://me.avatar.example.com, или любое количество поддоменов. Оно не может содержать порт или строку запроса. Любой другой протокол или несоответствующее имя хоста вернет 400 Bad Request.

Шаблоны с подстановочными знаками можно использовать как для pathname, так и для hostname, и они имеют следующий синтаксис:

• * соответствует одному сегменту пути или поддомену
• ** соответствует любому количеству сегментов пути в конце или поддоменов в начале

Синтаксис ** не работает в середине шаблона.

Полезно знать: Если опустить protocol, port, pathname или search, подразумевается подстановочный знак **. Это не рекомендуется, так как может позволить злоумышленникам оптимизировать URL-адреса, которые вы не планировали.

Ниже приведен пример свойства remotePatterns в файле next.config.js с использованием search:

module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'assets.example.com',
        search: '?v=1727111025337',
      },
    ],
  },
}

Полезно знать: В примере выше свойство src next/image должно начинаться с https://assets.example.com и должно содержать точную строку запроса ?v=1727111025337. Любой другой протокол или строка запроса вернет 400 Bad Request.

domains

Предупреждение: Устарело в Next.js 14 в пользу строгих remotePatterns для защиты вашего приложения от злоумышленников. Используйте domains только если вы владеете всем контентом, обслуживаемым с домена.

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

Однако конфигурация domains не поддерживает сопоставление с подстановочными знаками и не может ограничивать протокол, порт или путь.

Ниже приведен пример свойства domains в файле next.config.js:

module.exports = {
  images: {
    domains: ['assets.acme.com'],
  },
}

loaderFile

Если вы хотите использовать облачного провайдера для оптимизации изображений вместо встроенного API оптимизации изображений Next.js, вы можете настроить loaderFile в вашем next.config.js следующим образом:

module.exports = {
  images: {
    loader: 'custom',
    loaderFile: './my/image/loader.js',
  },
}

Это должно указывать на файл относительно корня вашего приложения Next.js. Файл должен экспортировать функцию по умолчанию, которая возвращает строку, например:

export default function myImageLoader({ src, width, quality }) {
  return `https://example.com/${src}?w=${width}&q=${quality || 75}`
}

Альтернативно, вы можете использовать свойство loader для настройки каждого экземпляра next/image.

Примеры:

• Конфигурация пользовательского загрузчика изображений

Продвинутые настройки

Следующая конфигурация предназначена для сложных случаев использования и обычно не требуется. Если вы выберете настройку свойств ниже, вы переопределите любые изменения стандартных значений Next.js в будущих обновлениях.

deviceSizes

Если вы знаете ожидаемую ширину устройств ваших пользователей, вы можете указать список точек останова ширины устройств с помощью свойства deviceSizes в next.config.js. Эти ширины используются, когда компонент next/image использует свойство sizes, чтобы гарантировать, что правильное изображение будет передано для устройства пользователя.

Если конфигурация не предоставлена, используется стандартное значение ниже.

module.exports = {
  images: {
    deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
  },
}

imageSizes

Вы можете указать список ширин изображений с помощью свойства images.imageSizes в вашем файле next.config.js. Эти ширины объединяются с массивом device sizes, чтобы сформировать полный массив размеров, используемых для генерации srcset изображений.

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

Если конфигурация не предоставлена, используется стандартное значение ниже.

module.exports = {
  images: {
    imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
  },
}

qualities

Стандартный API оптимизации изображений автоматически разрешает все качества от 1 до 100. Если вы хотите ограничить допустимые качества, вы можете добавить конфигурацию в next.config.js.

module.exports = {
  images: {
    qualities: [25, 50, 75],
  },
}

В приведенном выше примере разрешены только три качества: 25, 50 и 75. Если свойство quality не соответствует значению в этом массиве, изображение не будет загружено с ошибкой 400 Bad Request.

formats

Стандартный API оптимизации изображений автоматически определяет поддерживаемые браузером форматы изображений через заголовок Accept запроса.

Если заголовок Accept соответствует более чем одному из настроенных форматов, используется первое совпадение в массиве. Поэтому порядок массива имеет значение. Если совпадений нет (или исходное изображение анимировано), API оптимизации изображений вернется к исходному формату изображения.

Если конфигурация не предоставлена, используется стандартное значение ниже.

module.exports = {
  images: {
    formats: ['image/webp'],
  },
}

Вы можете включить поддержку AVIF следующей конфигурацией.

module.exports = {
  images: {
    formats: ['image/avif', 'image/webp'],
  },
}

Полезно знать:

• AVIF обычно занимает на 20% больше времени для кодирования, но сжимается на 20% лучше по сравнению с WebP. Это означает, что при первом запросе изображения оно обычно будет загружаться медленнее, а последующие запросы, которые кэшируются, будут быстрее.
• Если вы используете собственный хостинг с Proxy/CDN перед Next.js, вы должны настроить Proxy для пересылки заголовка Accept.

Поведение кэширования

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

Изображения оптимизируются динамически при запросе и сохраняются в директории <distDir>/cache/images. Оптимизированный файл изображения будет обслуживаться для последующих запросов до истечения срока действия. Когда делается запрос, соответствующий кэшированному, но устаревшему файлу, устаревшее изображение сразу же отдается как устаревшее. Затем изображение оптимизируется повторно в фоновом режиме (также называется ревалидацией) и сохраняется в кэше с новой датой истечения срока действия.

Статус кэша изображения можно определить, прочитав значение заголовка ответа x-nextjs-cache. Возможные значения:

• MISS — путь отсутствует в кэше (происходит максимум один раз, при первом посещении)
• STALE — путь есть в кэше, но превышено время ревалидации, поэтому он будет обновлен в фоновом режиме
• HIT — путь есть в кэше и не превышено время ревалидации

Срок действия (или, точнее, Max Age) определяется либо конфигурацией minimumCacheTTL, либо заголовком Cache-Control исходного изображения, в зависимости от того, что больше. В частности, используется значение max-age заголовка Cache-Control. Если найдены и s-maxage, и max-age, предпочтение отдается s-maxage. Значение max-age также передается любым нижестоящим клиентам, включая CDN и браузеры.

• Вы можете настроить minimumCacheTTL, чтобы увеличить срок кэширования, когда исходное изображение не включает заголовок Cache-Control или значение очень низкое.
• Вы можете настроить deviceSizes и imageSizes, чтобы уменьшить общее количество возможных генерируемых изображений.
• Вы можете настроить formats, чтобы отключить несколько форматов в пользу одного формата изображения.

minimumCacheTTL

Вы можете настроить время жизни (TTL) в секундах для кэшированных оптимизированных изображений. Во многих случаях лучше использовать Статический импорт изображений, который автоматически хэширует содержимое файла и кэширует изображение навсегда с заголовком Cache-Control со значением immutable.

module.exports = {
  images: {
    minimumCacheTTL: 60,
  },
}

Срок действия (или Max Age) оптимизированного изображения определяется либо minimumCacheTTL, либо заголовком Cache-Control исходного изображения, в зависимости от того, что больше.

Если вам нужно изменить поведение кэширования для каждого изображения, вы можете настроить headers, чтобы установить заголовок Cache-Control для исходного изображения (например, /some-asset.jpg, а не /_next/image).

На данный момент нет механизма для инвалидации кэша, поэтому лучше держать minimumCacheTTL низким. В противном случае вам может потребоваться вручную изменить свойство src или удалить <distDir>/cache/images.

disableStaticImages

Стандартное поведение позволяет импортировать статические файлы, такие как import icon from './icon.png', а затем передавать их в свойство src.

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

Вы можете отключить статический импорт изображений в вашем next.config.js:

module.exports = {
  images: {
    disableStaticImages: true,
  },
}

dangerouslyAllowSVG

По умолчанию загрузчик (loader) не оптимизирует SVG-изображения по нескольким причинам. Во-первых, SVG — это векторный формат, что означает возможность масштабирования без потерь. Во-вторых, SVG имеет множество функций, аналогичных HTML/CSS, что может привести к уязвимостям без правильных заголовков Content Security Policy (CSP).

Поэтому мы рекомендуем использовать свойство unoptimized, когда известно, что свойство src содержит SVG. Это происходит автоматически, если src заканчивается на ".svg".

Однако, если вам необходимо обслуживать SVG-изображения через API оптимизации изображений по умолчанию, вы можете установить dangerouslyAllowSVG в вашем next.config.js:

module.exports = {
  images: {
    dangerouslyAllowSVG: true,
    contentDispositionType: 'attachment',
    contentSecurityPolicy: "default-src 'self'; script-src 'none'; sandbox;",
  },
}

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

Анимированные изображения

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

Автоматическое определение анимированных файлов работает по принципу "best-effort" и поддерживает GIF, APNG и WebP. Если вы хотите явно отключить оптимизацию для конкретного анимированного изображения, используйте свойство unoptimized.

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

Сгенерированный по умолчанию srcset содержит изображения 1x и 2x для поддержки различных плотностей пикселей устройств. Однако вам может потребоваться отобразить адаптивное изображение, которое растягивается вместе с областью просмотра. В этом случае вам нужно установить sizes, а также style (или className).

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

Адаптивное изображение с помощью статического импорта

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

import Image from 'next/image'
import me from '../photos/me.jpg'

export default function Author() {
  return (
    <Image
      src={me}
      alt="Фото автора"
      sizes="100vw"
      style={{
        width: '100%',
        height: 'auto',
      }}
    />
  )
}

Попробуйте:

• Демонстрация адаптивного изображения к области просмотра

Адаптивное изображение с соотношением сторон

Если исходное изображение динамическое или имеет удаленный URL, вам также потребуется указать width и height, чтобы установить правильное соотношение сторон адаптивного изображения:

import Image from 'next/image'

export default function Page({ photoUrl }) {
  return (
    <Image
      src={photoUrl}
      alt="Фото автора"
      sizes="100vw"
      style={{
        width: '100%',
        height: 'auto',
      }}
      width={500}
      height={300}
    />
  )
}

Попробуйте:

• Демонстрация адаптивного изображения к области просмотра

Адаптивное изображение с fill

Если вы не знаете соотношение сторон, вам нужно установить свойство fill и position: relative для родительского элемента. Дополнительно вы можете установить стиль object-fit в зависимости от желаемого поведения (растягивание или обрезка):

import Image from 'next/image'

export default function Page({ photoUrl }) {
  return (
    <div style={{ position: 'relative', width: '300px', height: '500px' }}>
      <Image
        src={photoUrl}
        alt="Фото автора"
        sizes="300px"
        fill
        style={{
          objectFit: 'contain',
        }}
      />
    </div>
  )
}

Попробуйте:

• Демонстрация свойства fill

CSS для определения темы

Если вы хотите отображать разные изображения для светлой и темной темы, вы можете создать компонент, который оборачивает два компонента <Image> и показывает правильный на основе CSS media query.

.imgDark {
  display: none;
}

@media (prefers-color-scheme: dark) {
  .imgLight {
    display: none;
  }
  .imgDark {
    display: unset;
  }
}

import styles from './theme-image.module.css'
import Image, { ImageProps } from 'next/image'

type Props = Omit<ImageProps, 'src' | 'priority' | 'loading'> & {
  srcLight: string
  srcDark: string
}

const ThemeImage = (props: Props) => {
  const { srcLight, srcDark, ...rest } = props

  return (
    <>
      <Image {...rest} src={srcLight} className={styles.imgLight} />
      <Image {...rest} src={srcDark} className={styles.imgDark} />
    </>
  )
}

import styles from './theme-image.module.css'
import Image from 'next/image'

const ThemeImage = (props) => {
  const { srcLight, srcDark, ...rest } = props

  return (
    <>
      <Image {...rest} src={srcLight} className={styles.imgLight} />
      <Image {...rest} src={srcDark} className={styles.imgDark} />
    </>
  )
}

Полезно знать: Поведение по умолчанию loading="lazy" гарантирует, что загружается только правильное изображение. Вы не можете использовать priority или loading="eager", так как это приведет к загрузке обоих изображений. Вместо этого вы можете использовать fetchPriority="high".

Попробуйте:

• Демонстрация определения светлой/темной темы

getImageProps

Для более сложных случаев использования вы можете вызвать getImageProps(), чтобы получить свойства, которые будут переданы базовому элементу <img>, и затем передать их другому компоненту, стилю, canvas и т. д.

Это также позволяет избежать вызова React useState(), что может улучшить производительность, но нельзя использовать с свойством placeholder, так как placeholder никогда не будет удален.

Определение темы с помощью <picture>

Если вы хотите отображать разные изображения для светлой и темной темы, вы можете использовать элемент <picture> для отображения разных изображений на основе предпочитаемой цветовой схемы пользователя.

import { getImageProps } from 'next/image'

export default function Page() {
  const common = { alt: 'Пример темы', width: 800, height: 400 }
  const {
    props: { srcSet: dark },
  } = getImageProps({ ...common, src: '/dark.png' })
  const {
    props: { srcSet: light, ...rest },
  } = getImageProps({ ...common, src: '/light.png' })

  return (
    <picture>
      <source media="(prefers-color-scheme: dark)" srcSet={dark} />
      <source media="(prefers-color-scheme: light)" srcSet={light} />
      <img {...rest} />
    </picture>
  )
}

Арт-дирекшн

Если вы хотите отображать разные изображения для мобильных и десктопных устройств (иногда называемое арт-дирекшн), вы можете передать разные свойства src, width, height и quality в getImageProps().

import { getImageProps } from 'next/image'

export default function Home() {
  const common = { alt: 'Пример арт-дирекшн', sizes: '100vw' }
  const {
    props: { srcSet: desktop },
  } = getImageProps({
    ...common,
    width: 1440,
    height: 875,
    quality: 80,
    src: '/desktop.jpg',
  })
  const {
    props: { srcSet: mobile, ...rest },
  } = getImageProps({
    ...common,
    width: 750,
    height: 1334,
    quality: 70,
    src: '/mobile.jpg',
  })

  return (
    <picture>
      <source media="(min-width: 1000px)" srcSet={desktop} />
      <source media="(min-width: 500px)" srcSet={mobile} />
      <img {...rest} style={{ width: '100%', height: 'auto' }} />
    </picture>
  )
}

Фоновое изображение в CSS

Вы даже можете преобразовать строку srcSet в CSS-функцию image-set() для оптимизации фонового изображения.

import { getImageProps } from 'next/image'

function getBackgroundImage(srcSet = '') {
  const imageSet = srcSet
    .split(', ')
    .map((str) => {
      const [url, dpi] = str.split(' ')
      return `url("${url}") ${dpi}`
    })
    .join(', ')
  return `image-set(${imageSet})`
}

export default function Home() {
  const {
    props: { srcSet },
  } = getImageProps({ alt: '', width: 128, height: 128, src: '/img.png' })
  const backgroundImage = getBackgroundImage(srcSet)
  const style = { height: '100vh', width: '100vw', backgroundImage }

  return (
    <main style={style}>
      <h1>Hello World</h1>
    </main>
  )
}

Известные ошибки браузеров

Компонент next/image использует нативную ленивую загрузку (lazy loading) браузера, которая может переключаться на eager loading для старых браузеров до Safari 15.4. При использовании blur-up placeholder старые браузеры до Safari 12 будут использовать пустой placeholder. При использовании стилей с width/height равными auto возможно возникновение Layout Shift в старых браузерах до Safari 15, которые не сохраняют соотношение сторон. Подробнее см. это видео от MDN.

• Safari 15 - 16.3 отображают серую границу во время загрузки. Safari 16.4 исправил эту проблему. Возможные решения:
  • Используйте CSS @supports (font: -apple-system-body) and (-webkit-appearance: none) { img[loading="lazy"] { clip-path: inset(0.6px) } }
  • Используйте priority, если изображение находится выше сгиба
• Firefox 67+ отображают белый фон во время загрузки. Возможные решения:
  • Включите AVIF formats
  • Используйте placeholder

История версий