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

Например, если вы знаете, что ваш стиль приведет к тому, что изображение будет полноширинным на мобильных устройствах, в двухколоночном макете на планшетах и ​​в трехколоночном макете на настольных компьютерах, вам следует указать свойство 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 sizes выбранное из сервера изображение будет в 3 раза шире, чем необходимо. Поскольку размер файла пропорционален квадрату ширины, без sizes пользователь загрузит изображение, которое на 9 раз больше, чем необходимо.

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

• web.dev
• mdn

Качество

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

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

Приоритет

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

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

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

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

Заполнитель

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 /> по желанию принимает следующие дополнительные свойства.

Стиль

Позволяет передавать 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)} />

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

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

onError

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

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

Загрузка

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

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

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

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

Когда eager, загрузить изображение немедленно.

Дополнительные сведения об атрибуте loading.

blurDataURL

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

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

Попробуйте:

• Демонстрация свойства 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"
/>

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

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

• srcSet. Используйте Размеры устройств вместо этого.
• decoding. Оно всегда равно "async".

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

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

remotePatterns

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

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

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

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

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

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

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

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

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

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

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. Эти ширины конкатенируются с массивом размеров устройств, чтобы сформировать полный массив размеров, используемых для генерации srcset изображений.

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

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

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

formats

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

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

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

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

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

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

Важно знать:

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

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

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

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

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

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

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

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

minimumCacheTTL

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

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

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

Если вам необходимо изменить поведение кэширования для каждого изображения, вы можете настроить headers для установки заголовка Cache-Control на upstream-изображении (например, /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

Встроенный загрузчик по умолчанию не оптимизирует изображения 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, чтобы предотвратить выполнение скриптов, встроенных в изображение.

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

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

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

Реагирующие изображения

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

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

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

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

import Image from 'next/image'
import me from '../photos/me.jpg'
 
export default function Author() {
  return (
    <Image
      src={me}
      alt="Picture of the author"
      sizes="100vw"
      style={{
        width: '100%',
        height: 'auto',
      }}
    />
  )
}

Попробуйте:

• Демонстрация реагирования изображения на viewport

Реагирующее изображение с соотношением сторон

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

import Image from 'next/image'
 
export default function Page({ photoUrl }) {
  return (
    <Image
      src={photoUrl}
      alt="Picture of the author"
      sizes="100vw"
      style={{
        width: '100%',
        height: 'auto',
      }}
      width={500}
      height={300}
    />
  )
}

Попробуйте:

• Демонстрация реагирования изображения на viewport

Реагирующее изображение с 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="Picture of the author"
        sizes="300px"
        fill
        style={{
          objectFit: 'contain',
        }}
      />
    </div>
  )
}

Попробуйте:

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

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

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

.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} />
    </>
  )
}

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

Попробуйте:

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

getImageProps

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

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

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

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

import { getImageProps } from 'next/image'
 
export default function Page() {
  const common = { alt: 'Theme Example', 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: 'Art Direction Example', 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 использует собственный браузер для ленивой загрузки, который может перейти на загрузочную загрузку для старых браузеров до Safari 15.4. При использовании предзагрузки blur-up старые браузеры до Safari 12 будут переходить к пустому заполнителю. При использовании стилей с width/height auto, возможно, возникнет сдвиг макета в старых браузерах до 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

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