Компонент <Image> (Legacy)

Начиная с Next.js 13, компонент next/image был переработан для улучшения производительности и удобства разработчиков. Для обеспечения обратной совместимости старый next/image был переименован в next/legacy/image.

См. новую справочную документацию по next/image

Сравнение

По сравнению с next/legacy/image, новый компонент next/image имеет следующие изменения:

• Удалена обёртка <span> вокруг <img> в пользу нативного вычисления соотношения сторон
• Добавлена поддержка стандартного пропа style
  • Удалён проп layout в пользу style или className
  • Удалён проп objectFit в пользу style или className
  • Удалён проп objectPosition в пользу style или className
• Удалена реализация IntersectionObserver в пользу нативной ленивой загрузки
  • Удалён проп lazyBoundary, так как нет нативного эквивалента
  • Удалён проп lazyRoot, так как нет нативного эквивалента
• Удалена конфигурация loader в пользу пропа loader
• Проп alt стал обязательным вместо опционального
• Изменён callback onLoadingComplete для получения ссылки на элемент <img>

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

Компонент <Image /> требует следующие свойства.

src

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

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

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

width

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

При использовании layout="intrinsic" или layout="fixed" свойство width представляет отображаемую ширину в пикселях, поэтому влияет на размер изображения.

При использовании layout="responsive" или layout="fill" свойство width представляет оригинальную ширину в пикселях, поэтому влияет только на соотношение сторон.

Свойство width обязательно, за исключением статически импортированных изображений или изображений с layout="fill".

height

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

При использовании layout="intrinsic" или layout="fixed" свойство height представляет отображаемую высоту в пикселях, поэтому влияет на размер изображения.

При использовании layout="responsive" или layout="fill" свойство height представляет оригинальную высоту в пикселях, поэтому влияет только на соотношение сторон.

Свойство height обязательно, за исключением статически импортированных изображений или изображений с layout="fill".

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

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

layout

Поведение изображения при изменении размера области просмотра.

• Демонстрация intrinsic layout (по умолчанию)
  • При intrinsic изображение будет уменьшаться для меньших областей просмотра, но сохранять оригинальные размеры для больших.
• Демонстрация fixed layout
  • При fixed размеры изображения не изменяются при изменении области просмотра (без адаптивности), аналогично нативному элементу img.
• Демонстрация responsive layout
  • При responsive изображение будет уменьшаться для меньших областей просмотра и увеличиваться для больших.
  • Убедитесь, что родительский элемент использует display: block в своих стилях.
• Демонстрация fill layout
  • При fill изображение растягивается по ширине и высоте до размеров родительского элемента, если он имеет относительное позиционирование.
  • Обычно используется в сочетании со свойством objectFit.
  • Убедитесь, что родительский элемент имеет position: relative в своих стилях.
• Демонстрация фонового изображения

loader

Пользовательская функция для разрешения URL. Установка loader как пропа компонента Image переопределяет стандартный loader, определённый в разделе images файла next.config.js.

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

• src
• width
• quality

Пример использования пользовательского loader:

import Image from 'next/legacy/image'

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

const MyImage = (props) => {
  return (
    <Image
      loader={myLoader}
      src="me.png"
      alt="Picture of the author"
      width={500}
      height={500}
    />
  )
}

sizes

Строка, предоставляющая информацию о ширине изображения на разных контрольных точках. Значение sizes значительно влияет на производительность для изображений с layout="responsive" или layout="fill". Игнорируется для изображений с layout="intrinsic" или layout="fixed".

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

Во-первых, значение sizes используется браузером для определения, какой размер изображения загружать из автоматически генерируемого набора источников next/legacy/image. Когда браузер делает выбор, он ещё не знает размер изображения на странице, поэтому выбирает изображение того же размера или больше, чем область просмотра. Свойство sizes позволяет сообщить браузеру, что изображение на самом деле будет меньше, чем полный экран. Если значение sizes не указано, используется значение по умолчанию 100vw (полная ширина экрана).

Во-вторых, значение sizes анализируется и используется для обрезки значений в автоматически созданном наборе источников. Если свойство sizes включает значения, такие как 50vw, которые представляют процент от ширины области просмотра, то набор источников обрезается, чтобы исключить значения, которые слишком малы для использования.

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

import Image from 'next/legacy/image'
const Example = () => (
  <div className="grid-element">
    <Image
      src="/example.png"
      layout="fill"
      sizes="(max-width: 768px) 100vw,
              (max-width: 1200px) 50vw,
              33vw"
    />
  </div>
)

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

Подробнее о srcset и sizes:

• web.dev
• mdn

quality

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

priority

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

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

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

placeholder

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

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

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

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

Попробуйте:

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

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

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

style

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

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

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

objectFit

Определяет, как изображение будет заполнять родительский контейнер при использовании layout="fill".

Это значение передаётся в CSS свойство object-fit для изображения src.

objectPosition

Определяет позиционирование изображения внутри родительского элемента при использовании layout="fill".

Это значение передаётся в CSS свойство object-position, применяемое к изображению.

onLoadingComplete

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

Функция onLoadingComplete принимает один параметр — объект со следующими свойствами:

• naturalWidth
• naturalHeight

loading

Внимание: Это свойство предназначено только для расширенного использования. Установка изображения на загрузку с eager обычно ухудшает производительность.

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

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

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

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

Подробнее

blurDataURL

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

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

Попробуйте:

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

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

lazyBoundary

Строка (с синтаксисом, аналогичным свойству margin), которая действует как ограничивающая рамка для обнаружения пересечения изображения с областью просмотра и запуска ленивой загрузки. По умолчанию "200px".

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

Подробнее

lazyRoot

React Ref, указывающий на прокручиваемый родительский элемент. По умолчанию null (область просмотра документа).

Ref должен указывать на DOM элемент или React компонент, который передаёт Ref на базовый DOM элемент.

Пример указания на DOM элемент

import Image from 'next/legacy/image'
import React from 'react'

const Example = () => {
  const lazyRoot = React.useRef(null)

  return (
    <div ref={lazyRoot} style={{ overflowX: 'scroll', width: '500px' }}>
      <Image lazyRoot={lazyRoot} src="/one.jpg" width="500" height="500" />
      <Image lazyRoot={lazyRoot} src="/two.jpg" width="500" height="500" />
    </div>
  )
}

Пример указания на React компонент

import Image from 'next/legacy/image'
import React from 'react'

const Container = React.forwardRef((props, ref) => {
  return (
    <div ref={ref} style={{ overflowX: 'scroll', width: '500px' }}>
      {props.children}
    </div>
  )
})

const Example = () => {
  const lazyRoot = React.useRef(null)

  return (
    <Container ref={lazyRoot}>
      <Image lazyRoot={lazyRoot} src="/one.jpg" width="500" height="500" />
      <Image lazyRoot={lazyRoot} src="/two.jpg" width="500" height="500" />
    </Container>
  )
}

Подробнее

unoptimized

Когда установлено в 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,
  },
}

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

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

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

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

Шаблоны удалённых изображений

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

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

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

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

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

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

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

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

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

Домены

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

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

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

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

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

Настройка загрузчика

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

module.exports = {
  images: {
    loader: 'imgix',
    path: 'https://example.com/myaccount/',
  },
}

Встроенные загрузчики

Следующие облачные провайдеры оптимизации изображений включены:

• По умолчанию: Работает автоматически с next dev, next start или пользовательским сервером
• Vercel: Работает автоматически при развертывании на Vercel, не требует настройки. Подробнее
• Imgix: loader: 'imgix'
• Cloudinary: loader: 'cloudinary'
• Akamai: loader: 'akamai'
• Пользовательский: loader: 'custom' используйте собственного облачного провайдера, реализовав свойство loader в компоненте next/legacy/image

Если вам нужен другой провайдер, вы можете использовать свойство loader с next/legacy/image.

Изображения не могут быть оптимизированы во время сборки с использованием output: 'export', только по запросу. Чтобы использовать next/legacy/image с output: 'export', вам потребуется использовать загрузчик, отличный от стандартного. Подробнее в обсуждении.

Стандартный загрузчик компонента next/legacy/image использует squoosh, так как он быстро устанавливается и подходит для среды разработки. При использовании next start в production-среде настоятельно рекомендуется установить sharp, выполнив npm i sharp в директории проекта. Это не требуется для развертываний на Vercel, так как sharp устанавливается автоматически.

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

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

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

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

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

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

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

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

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

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

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

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

Вы можете настроить время жизни (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.

Отключение статического импорта

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

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

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

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

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

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

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

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

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

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

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

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

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