<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

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

'use client'
 
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}
    />
  )
}

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

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

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

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, изображение будет считаться высоким приоритетом и будет предварительно загружено preload. Лень загрузки автоматически отключена для изображений, использующих 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
• Демонстрация эффекта мерцания с свойством data URL placeholder
• Демонстрация цветового эффекта со свойством blurDataURL

Дополнительные свойства

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

Стиль

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

const imageStyle = {
  borderRadius: '50%',
  border: '1px solid #fff',
}
 
export default function ProfileImage() {
  return <Image src="..." style={imageStyle} />
}

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

onLoadingComplete

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

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

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

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

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

onLoad

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

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

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

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

onError

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

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

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

loading

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

Домены

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

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

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

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

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

Файл загрузчика

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

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

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

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

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

Примеры:

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

Важно знать: Настройка файла загрузчика изображений, принимающего функцию, требует использования Компонентов клиента для сериализации предоставленной функции.

Расширенные настройки

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

Размеры устройств

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

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

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

Размеры изображений

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

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

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

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

Форматы

Встроенный 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, либо заголовком изображения upstream Cache-Control, в зависимости от того, какой из них больше. В частности, используется значение max-age заголовка Cache-Control. Если и s-maxage, и max-age найдены, то s-maxage предпочтительнее. max-age также передаётся всем клиентам нижестоящего уровня, включая CDN и браузеры.

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

Минимальное время жизни кэша

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

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

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

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

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

Отключить статические изображения

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

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

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

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

Опасно разрешить SVG

Встроенный загрузчик не оптимизирует изображения SVG по нескольким причинам. Во-первых, SVG — это векторный формат, что означает, что его можно масштабировать без потерь. Во-вторых, SVG содержит многие из тех же функций, что и HTML/CSS, что может привести к уязвимостям без надлежащих заголовков политики безопасности контента (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 автоматически пропускает оптимизацию изображений для анимированных изображений и отображает изображение в исходном виде.

Автоматическое определение анимированных файлов происходит по возможности и поддерживает форматы 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="Picture of the author"
      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="Picture of the author"
      sizes="100vw"
      style={{
        width: '100%',
        height: 'auto',
      }}
      width={500}
      height={300}
    />
  )
}

Попробуйте:

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

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

Если вам не известно соотношение сторон, вам необходимо установить свойство 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, возможно, произойдёт сдвиг макета 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

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