<Image> (Legacy)

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

Просмотреть новую next/image Справочную информацию по API

Сравнение

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

• Удален обертывающий <span> вокруг <img> в пользу встроенного вычисления соотношения сторон
• Добавлена поддержка свойства style с каноническим значением
  • Удалено свойство layout в пользу style или className
  • Удалено свойство objectFit в пользу style или className
  • Удалено свойство objectPosition в пользу style или className
• Удалена реализация IntersectionObserver в пользу встроенной ленивой загрузки
  • Удалено свойство lazyBoundary, так как нет встроенного аналога
  • Удалено свойство lazyRoot, так как нет встроенного аналога
• Удален конфигуратор loader в пользу свойства loader
• Свойство alt изменено с необязательного на обязательное
• Изменен обработчик 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 (по умолчанию)
  • Когда intrinsic, изображение будет уменьшать размеры для меньших окон, но сохранит исходные размеры для больших окон.
• Демонстрация макета fixed
  • Когда fixed, размеры изображения не будут изменяться при изменении области просмотра (отсутствие адаптивности), подобно встроенному элементу img.
• Демонстрация макета responsive
  • Когда responsive, изображение будет уменьшать размеры для меньших окон и увеличивать для больших окон.
  • Убедитесь, что родительский элемент использует display: block в своём стилистическом описании.
• Демонстрация макета fill
  • Когда fill, изображение будет растягиваться по ширине и высоте до размеров родительского элемента, при условии, что родительский элемент является относительным.
  • Это обычно используется в паре со свойством objectFit.
  • Убедитесь, что родительский элемент имеет position: relative в своём стилистическом описании.
• Демонстрация фонового изображения

loader

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

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

• src
• width
• quality

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

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 используется браузером для определения размера загружаемого изображения из автоматически сгенерированного набора источников. При выборе браузер ещё не знает размер изображения на странице, поэтому он выбирает изображение того же или большего размера, что и область просмотра. Свойство sizes позволяет сказать браузеру, что изображение будет фактически меньше, чем весь экран. Если не указать значение sizes, используется значение по умолчанию 100vw (полная ширина экрана).

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

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

Дополнительные сведения о srcset и sizes:

• web.dev
• mdn

quality

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

priority

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

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

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

местозаполнитель

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

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

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

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

Попробуйте:

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

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

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

стиль

Разрешает передачу стилей CSS подлежащему элементу изображения.

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

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

objectFit

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

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

objectPosition

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

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

onLoadingComplete

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

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

• naturalWidth
• naturalHeight

загрузка

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

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

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

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

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

Подробнее

blurDataURL

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

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

Попробуйте:

• Демонстрация свойства blurDataURL по умолчанию
• Демонстрация эффекта мерцания с свойством blurDataURL
• Демонстрация эффекта цвета с свойством blurDataURL

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

lazyBoundary

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

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

Подробнее

lazyRoot

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

Ссылка должна указывать на элемент DOM или React-компонент, который передает ссылку подлежащему элементу 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',
        port: '',
      },
    ],
  },
}

Важно знать: Приведенный выше пример гарантирует, что свойство src компонента next/legacy/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 в файле %%%CODE_BLOCK_203%%:

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

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

Если вы хотите использовать облачный провайдер для оптимизации изображений вместо встроенного API оптимизации изображений Next.js, вы можете настроить префикс loader и path в вашем файле %%%CODE_BLOCK_207%%. Это позволит вам использовать относительные 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 в вашей рабочей среде, настоятельно рекомендуется установить sharp, выполнив npm i sharp в каталоге вашего проекта. Это не требуется для развертываний на Vercel, так как sharp устанавливается автоматически.

data-docs-heading="" id="advanced">Продвинутые настройки

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

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