<Image>

Examples

Bu API referansı, Görüntü Bileşeni için mevcut olan sahne ve yapılandırma seçeneklerini nasıl kullanacağınızı anlamanıza yardımcı olacaktır. Özellikler ve kullanım için lütfen Görüntü Bileşeni sayfasına bakın.

app/page.js
import Image from 'next/image'
 
export default function Page() {
  return (
    <Image
      src="/profile.png"
      width={500}
      height={500}
      alt="Picture of the author"
    />
  )
}

Props

Görüntü Bileşeni için kullanılabilen aksesuarların bir özeti aşağıda verilmiştir:

PropExampleTypeStatus
srcsrc="/profile.png"StringRequired
widthwidth={500}Integer (px)Required
heightheight={500}Integer (px)Required
altalt="Picture of the author"StringRequired
loaderloader={imageLoader}Function-
fillfill={true}Boolean-
sizessizes="(max-width: 768px) 100vw, 33vw"String-
qualityquality={80}Integer (1-100)-
prioritypriority={true}Boolean-
placeholderplaceholder="blur"String-
stylestyle={{objectFit: "contain"}}Object-
onLoadingCompleteonLoadingComplete={img => done())}FunctionDeprecated
onLoadonLoad={event => done())}Function-
onErroronError(event => fail()}Function-
loadingloading="lazy"String-
blurDataURLblurDataURL="data:image/jpeg..."String-

Required Props

Görüntü Bileşeni aşağıdaki özellikleri gerektirir: src, width, height, ve alt.

app/page.js
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

Aşağıdakilerden biri olmalıdır:

Harici bir URL kullanırken, bunu next.config.js adresindeki remotePatterns 'e eklemeniz gerekir.

width

width özelliği piksel cinsinden işlenen genişliği temsil eder, bu nedenle görüntünün ne kadar büyük görüneceğini etkiler.

Statik olarak içe aktarılan resimler veya fill özelliğine sahip resimler dışında gereklidir.

height

height özelliği piksel cinsinden işlenen yüksekliği temsil eder, bu nedenle görüntünün ne kadar büyük görüneceğini etkiler.

Statik olarak içe aktarılan resimler veya fill özelliğine sahip resimler dışında gereklidir.

alt

alt özelliği, ekran okuyucular ve arama motorları için görüntüyü tanımlamak amacıyla kullanılır. Ayrıca görüntüler devre dışı bırakılmışsa veya görüntü yüklenirken bir hata oluşursa geri dönüş metnidir.

Sayfanın anlamını değiştirmeden resmin yerini alabilecek bir metin içermelidir . Görüntüyü tamamlama amacı taşımamalı ve görüntünün üstündeki veya altındaki başlıklarda zaten sağlanan bilgileri tekrar etmemelidir.

Görüntü tamamen dekoratifse veya kullanıcı için tasarlanmamışsa, alt özelliği boş bir dize olmalıdır (alt="").

Daha fazla bilgi edinin

Optional Props

<Image /> bileşeni, gerekli olanların ötesinde bir dizi ek özellik kabul eder. Bu bölümde Image bileşeninin en sık kullanılan özellikleri açıklanmaktadır. Daha nadir kullanılan özelliklerle ilgili ayrıntıları Gelişmiş Özellikler bölümünde bulabilirsiniz.

loader

Resim URL'lerini çözümlemek için kullanılan özel bir işlev.

loader, aşağıdaki parametreler verildiğinde görüntü için bir URL dizesi döndüren bir işlevdir:

İşte özel yükleyici kullanımına bir örnek:

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

Bilmekte fayda var: Bir işlevi kabul eden loader gibi prop'ların kullanılması, sağlanan işlevi serileştirmek için İstemci Bileşenlerinin kullanılmasını gerektirir.

Alternatif olarak, uygulamanızdaki her next/image örneğini yapılandırmak için next.config.js adresindeki loaderFile yapılandırmasını bir prop iletmeden kullanabilirsiniz.

fill 

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

Görüntünün üst öğeyi doldurmasına neden olan bir boolean; bu, aşağıdaki durumlarda kullanışlıdır width ve height bilinmiyor.

Üst öğe position: "relative", position: "fixed" veya position: "absolute" stilini atamalıdır.

Varsayılan olarak, img öğesine otomatik olarak position: "absolute" stili atanacaktır.

Görüntüye herhangi bir stil uygulanmazsa, görüntü kapsayıcıya sığacak şekilde esneyecektir. Kabı sığdırmak ve en boy oranını korumak için harf kutulu bir görüntü için object-fit: "contain" adresini ayarlamayı tercih edebilirsiniz.

Alternatif olarak, object-fit: "cover" görüntünün tüm kabı doldurmasına ve en boy oranını korumak için kırpılmasına neden olur. Bunun doğru görünmesi için overflow: "hidden" stili üst öğeye atanmalıdır.

Daha fazla bilgi için ayrıca bkz:

sizes

Medya sorgusuna benzer bir dize, görüntünün farklı kesme noktalarında ne kadar geniş olacağı hakkında bilgi sağlar. sizes değeri, aşağıdakileri kullanan görüntüler için performansı büyük ölçüde etkileyecektir fill veya duyarlı bir boyuta sahip olacak şekilde şekillendirilmiş.

sizes özelliği görüntü performansıyla ilgili iki önemli amaca hizmet eder:

Örneğin, stilinizin bir görüntünün mobil cihazlarda tam genişlikte, tabletlerde 2 sütunlu bir düzende ve masaüstü ekranlarda 3 sütunlu bir düzende olmasına neden olacağını biliyorsanız, aşağıdaki gibi bir boyutlar özelliği eklemelisiniz:

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

Bu örnek sizes performans metrikleri üzerinde dramatik bir etkiye sahip olabilir. 33vw boyutları olmadan, sunucudan seçilen görüntü olması gerekenden 3 kat daha geniş olacaktır. Dosya boyutu genişliğin karesiyle orantılı olduğundan, sizes olmadan kullanıcı gerekenden 9 kat daha büyük bir görüntü indirecektir.

srcset ve sizes hakkında daha fazla bilgi edinin:

quality 

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

Optimize edilmiş görüntünün kalitesi, 1 ile 100 arasında bir tamsayıdır; burada 100 en iyi kalite ve dolayısıyla en büyük dosya boyutudur. Varsayılan değer 75.

priority 

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

true olduğunda, görüntü yüksek öncelikli olarak kabul edilir ve ön yüklemesi yapılır. Tembel yükleme, priority kullanan görüntüler için otomatik olarak devre dışı bırakılır.

Largest Contentful Paint (LCP) öğesi olarak algılanan herhangi bir görüntü üzerinde priority özelliğini kullanmalısınız. Farklı görüntü alanı boyutları için farklı görüntüler LCP öğesi olabileceğinden, birden fazla öncelikli görüntüye sahip olmak uygun olabilir.

Yalnızca görüntü katlamanın üstünde görünür olduğunda kullanılmalıdır. Varsayılan değer false.

placeholder 

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

Görüntü yüklenirken kullanılacak bir yer tutucu. Olası değerler blur, empty veya data:image/... şeklindedir. Varsayılan değer empty.

Ne zaman blur, the blurDataURL özelliği yer tutucu olarak kullanılacaktır. src statik bir içe aktarma nesnesiyse ve içe aktarılan görüntü .jpg, .png, .webp veya .avif ise, görüntünün animasyonlu olduğu tespit edilmediği sürece blurDataURL otomatik olarak doldurulacaktır.

Dinamik görüntüler için blurDataURL mülkiyet. Plaiceholder gibi çözümler base64 oluşturulmasına yardımcı olabilir.

data:image/... olduğunda, Veri URL' si görüntü yüklenirken yer tutucu olarak kullanılacaktır.

empty adresinde, görüntü yüklenirken yer tutucu olmayacak, sadece boş alan olacaktır.

Dene bakalım:

Advanced Props

Bazı durumlarda daha gelişmiş kullanıma ihtiyaç duyabilirsiniz. <Image /> bileşeni isteğe bağlı olarak aşağıdaki gelişmiş özellikleri kabul eder.

style

CSS stillerinin alttaki görüntü öğesine aktarılmasına izin verir.

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

Gerekli genişlik ve yükseklik değerlerinin stilinizle etkileşime girebileceğini unutmayın. Bir görüntünün genişliğini değiştirmek için stil kullanırsanız, görüntünün içsel en boy oranını korumak için yüksekliğini de auto olarak stillemelisiniz, aksi takdirde görüntünüz bozulur.

onLoadingComplete 

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

Uyarı: Next.js 14'ten beri kullanımdan kaldırılmıştır. onLoad.

Görüntü tamamen yüklendikten ve yer tutucu kaldırıldıktan sonra çağrılan bir geri arama işlevi.

Geri çağırma işlevi tek bir bağımsız değişkenle çağrılır, bu da temel <img> öğesine bir referanstır.

Bilmekte fayda var: Bir işlevi kabul eden onLoadingComplete gibi prop'ların kullanılması, sağlanan işlevi serileştirmek için İstemci Bileşenlerinin kullanılmasını gerektirir.

onLoad 

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

Görüntü tamamen yüklendikten ve yer tutucu kaldırıldıktan sonra çağrılan bir geri arama işlevi.

Geri arama işlevi tek bir argümanla çağrılacaktır; bu argüman, temel <img> öğesine referans veren bir target öğesine sahip olan Olaydır.

Bilmekte fayda var: Bir işlevi kabul eden onLoad gibi prop'ların kullanılması, sağlanan işlevi serileştirmek için İstemci Bileşenlerinin kullanılmasını gerektirir.

onError 

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

Görüntü yüklenemezse çağrılan bir geri çağırma işlevi.

Bilmekte fayda var: Bir işlevi kabul eden onError gibi prop'ların kullanılması, sağlanan işlevi serileştirmek için İstemci Bileşenlerinin kullanılmasını gerektirir.

loading

Öneri: Bu özellik yalnızca gelişmiş kullanım durumları içindir. Bir görüntüyü eager ile yüklenecek şekilde değiştirmek normalde performansa zarar verecektir. Kullanmanızı öneririz priority özelliği yerine, görüntüyü istekli bir şekilde önceden yükleyecektir.

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

Görüntünün yükleme davranışı. Varsayılan değer lazy.

lazy, görüntüyü görüntü alanından hesaplanan bir uzaklığa ulaşana kadar yüklemeyi erteleyin.

eager adresinde görüntüyü hemen yükleyin.

loading özniteliği hakkında daha fazla bilgi edinin .

blurDataURL

src görüntüsü başarıyla yüklenmeden önce yer tutucu görüntü olarak kullanılacak bir Veri URL' si . Yalnızca aşağıdakilerle birleştirildiğinde etkili olur placeholder="blur".

Base64 ile kodlanmış bir resim olmalıdır. Büyütülecek ve bulanıklaştırılacaktır, bu nedenle çok küçük bir görüntü (10 piksel veya daha az) önerilir. Yer tutucu olarak daha büyük resimler eklemek uygulama performansınıza zarar verebilir.

Dene bakalım:

Görüntüyle eşleşmesi için adresinde düz renkli bir Veri URL 'si de oluşturabilirsiniz.

unoptimized 

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

true olduğunda, kaynak görüntü kalite, boyut veya biçim değiştirmek yerine olduğu gibi sunulur. Varsayılan değer false.

import Image from 'next/image'
 
const UnoptimizedImage = (props) => {
  return <Image {...props} unoptimized />
}

Next.js 12.3.0'dan bu yana, next.config.js adresini aşağıdaki yapılandırmayla güncelleyerek bu prop tüm görüntülere atanabilir:

next.config.js
module.exports = {
  images: {
    unoptimized: true,
  },
}

Other Props

<Image /> bileşenindeki diğer özellikler, aşağıdakiler hariç olmak üzere, temelimg öğesine aktarılacaktır:

Configuration Options

Sahne donanımlarına ek olarak, Görüntü Bileşenini next.config.js adresinden yapılandırabilirsiniz. Aşağıdaki seçenekler mevcuttur:

remotePatterns

Uygulamanızı kötü niyetli kullanıcılardan korumak amacıyla, harici görüntüleri kullanmak için yapılandırma gereklidir. Bu, Next.js Görüntü Optimizasyon API'sinden yalnızca hesabınızdaki harici görüntülerin sunulabilmesini sağlar. Bu harici görüntüler, aşağıda gösterildiği gibi next.config.js dosyanızdaki remotePatterns özelliği ile yapılandırılabilir:

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

Bilmekte fayda var: Yukarıdaki örnek, next/image adresinin src özelliğinin https://example.com/account123/ ile başlamasını sağlayacaktır. Başka herhangi bir protokol, ana bilgisayar adı, bağlantı noktası veya eşleşmeyen yol 400 Bad Request ile yanıt verecektir.

Aşağıda next.config.js dosyasındaki remotePatterns özelliğinin bir başka örneği yer almaktadır:

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

Bilmekte fayda var: Yukarıdaki örnek, next/image adresinin src özelliğinin https://img1.example.com veya https://me.avatar.example.com veya herhangi bir sayıda alt alan adı ile başlamasını sağlayacaktır. Başka herhangi bir protokol, bağlantı noktası veya eşleşmeyen ana bilgisayar adı 400 Bad Request ile yanıt verecektir.

Joker karakter kalıpları hem pathname hem de hostname için kullanılabilir ve aşağıdaki sözdizimine sahiptir:

** sözdizimi kalıbın ortasında çalışmaz.

Bilmekte fayda var: protocol , port veya pathname atlandığında, ** joker karakteri ima edilir. Bu, kötü niyetli aktörlerin istemediğiniz URL'leri optimize etmesine izin verebileceğinden önerilmez.

domains

Uyarı: Next.js 14'ten beri strict lehine kullanımdan kaldırılmıştır remotePatterns uygulamanızı kötü niyetli kullanıcılardan korumak için. domains adresini yalnızca etki alanından sunulan tüm içeriğe sahipseniz kullanın.

Benzer şekilde remotePatternsdomains yapılandırması, harici görüntüler için izin verilen ana bilgisayar adlarının bir listesini sağlamak için kullanılabilir.

Ancak, domains yapılandırması joker karakter desen eşleştirmesini desteklemez ve protokol, bağlantı noktası veya yol adını kısıtlayamaz.

Aşağıda next.config.js dosyasındaki domains özelliğinin bir örneği yer almaktadır:

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

loaderFile

Görüntüleri optimize etmek için Next.js yerleşik Görüntü Optimizasyon API'sini kullanmak yerine bir bulut sağlayıcısı kullanmak istiyorsanız, loaderFile adresini next.config.js adresinizde aşağıdaki gibi yapılandırabilirsiniz:

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

Bu, Next.js uygulamanızın kök dizinine göre bir dosyayı işaret etmelidir. Dosya, örneğin bir dize döndüren varsayılan bir işlevi dışa aktarmalıdır:

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

Alternatif olarak, her next/image örneğini yapılandırmak için loader prop 'unu kullanabilirsiniz.

Örnekler:

Bilmekte fayda var: Bir işlevi kabul eden görüntü yükleyici dosyasının özelleştirilmesi, sağlanan işlevi serileştirmek için İstemci Bileşenlerinin kullanılmasını gerektirir.

Advanced

Aşağıdaki yapılandırma gelişmiş kullanım durumları içindir ve genellikle gerekli değildir. Aşağıdaki özellikleri yapılandırmayı seçerseniz, gelecekteki güncellemelerde Next.js varsayılanlarında yapılacak tüm değişiklikleri geçersiz kılacaksınız.

deviceSizes

Kullanıcılarınızın beklenen cihaz genişliklerini biliyorsanız, next.config.js adresindeki deviceSizes özelliğini kullanarak cihaz genişliği kesme noktalarının bir listesini belirtebilirsiniz. Bu genişlikler, next/image bileşeni aşağıdakileri kullandığında kullanılır sizes kullanıcının cihazı için doğru görüntünün sunulduğundan emin olmak için prop.

Herhangi bir yapılandırma sağlanmamışsa, aşağıdaki varsayılan kullanılır.

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

imageSizes

next.config.js dosyanızdaki images.imageSizes özelliğini kullanarak görüntü genişliklerinin bir listesini belirtebilirsiniz. Bu genişlikler, s görüntü srcset'ini oluşturmak için kullanılan tam boyut dizisini oluşturmak üzere cihaz boyutları dizisiyle birleştirilir.

İki ayrı liste olmasının nedeni, imageSizes'ın yalnızca sizes prop, görüntünün ekranın tam genişliğinden daha az olduğunu gösterir. Bu nedenle, imageSizes içindeki boyutların tümü deviceSizes içindeki en küçük boyuttan daha küçük olmalıdır.

Herhangi bir yapılandırma sağlanmamışsa, aşağıdaki varsayılan kullanılır.

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

formats

Varsayılan Görüntü Optimizasyon API 'si, isteğin Accept başlığı aracılığıyla tarayıcının desteklenen görüntü biçimlerini otomatik olarak algılar.

Accept başlığı yapılandırılmış biçimlerden birden fazlasıyla eşleşirse, dizideki ilk eşleşme kullanılır. Bu nedenle, dizi sırası önemlidir. Eşleşme yoksa (veya kaynak görüntü animasyonlu ise), Görüntü Optimizasyon API'si orijinal görüntünün formatına geri döner.

Herhangi bir yapılandırma sağlanmamışsa, aşağıdaki varsayılan kullanılır.

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

AVIF desteğini aşağıdaki yapılandırma ile etkinleştirebilirsiniz.

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

Bildiğim iyi oldu:

  • AVIF'in kodlanması genellikle %20 daha uzun sürer ancak WebP'ye kıyasla %20 daha küçük sıkıştırma yapar. Bu, bir görüntü ilk kez istendiğinde genellikle daha yavaş olacağı ve daha sonra önbelleğe alınan sonraki isteklerin daha hızlı olacağı anlamına gelir.
  • Next.js'nin önünde bir Proxy/CDN ile kendiniz barındırıyorsanız, Proxy'yi Accept başlığını iletecek şekilde yapılandırmanız gerekir.

Caching Behavior

Aşağıda varsayılan yükleyici için önbelleğe alma algoritması açıklanmaktadır. Diğer tüm yükleyiciler için lütfen bulut sağlayıcınızın belgelerine bakın.

Görüntüler istek üzerine dinamik olarak optimize edilir ve <distDir>/cache/images dizininde saklanır. Optimize edilmiş görüntü dosyası, son kullanma tarihine ulaşılana kadar sonraki talepler için sunulacaktır. Önbelleğe alınmış ancak süresi dolmuş bir dosyayla eşleşen bir istek yapıldığında, süresi dolmuş görüntü hemen bayat olarak sunulur. Ardından görüntü arka planda yeniden optimize edilir (yeniden doğrulama olarak da adlandırılır) ve yeni son kullanma tarihi ile önbelleğe kaydedilir.

Bir görüntünün önbellek durumu x-nextjs-cache yanıt başlığının değeri okunarak belirlenebilir. Olası değerler aşağıdaki gibidir:

Son kullanma tarihi (ya da daha doğrusu Maksimum Yaş) minimumCacheTTL yapılandırması veya yukarı akış görüntüsü Cache-Control başlığından hangisi daha büyükse. Özellikle, Cache-Control başlığının max-age değeri kullanılır. Hem s-maxage hem de max-age bulunursa, s-maxage tercih edilir. max-age ayrıca CDN'ler ve tarayıcılar dahil olmak üzere tüm aşağı akış istemcilerine aktarılır.

minimumCacheTTL

Önbelleğe alınan optimize edilmiş görüntüler için Yaşama Süresini (TTL) saniye cinsinden yapılandırabilirsiniz. Çoğu durumda, dosya içeriğini otomatik olarak hashleyecek ve görüntüyü immutable Cache-Control başlığıyla sonsuza kadar önbelleğe alacak bir Statik Görüntü İçe Aktarma kullanmak daha iyidir.

next.config.js
module.exports = {
  images: {
    minimumCacheTTL: 60,
  },
}

Optimize edilmiş görüntünün sona erme süresi (veya daha doğrusu Maksimum Yaş), hangisi daha büyükse, minimumCacheTTL veya yukarı akış görüntüsü Cache-Control başlığı tarafından tanımlanır.

Görüntü başına önbelleğe alma davranışını değiştirmeniz gerekiyorsa headers yukarı akış görüntüsündeki Cache-Control başlığını ayarlamak için (örneğin /some-asset.jpg, /_next/image 'nin kendisi değil).

Şu anda önbelleği geçersiz kılacak bir mekanizma yoktur, bu nedenle minimumCacheTTL adresini düşük tutmak en iyisidir. Aksi takdirde önbelleği elle değiştirmeniz gerekebilir. src prop veya <distDir>/cache/images adresini silin.

disableStaticImages

Varsayılan davranış, import icon from './icon.png' gibi statik dosyaları içe aktarmanıza ve ardından bunu src özelliğine geçirmenize olanak tanır.

Bazı durumlarda, içe aktarmanın farklı davranmasını bekleyen diğer eklentilerle çakışması halinde bu özelliği devre dışı bırakmak isteyebilirsiniz.

Statik görüntü içe aktarımlarını next.config.js adresinizde devre dışı bırakabilirsiniz:

next.config.js
module.exports = {
  images: {
    disableStaticImages: true,
  },
}

dangerouslyAllowSVG

Varsayılan yükleyici birkaç nedenden dolayı SVG görüntülerini optimize etmez. İlk olarak, SVG bir vektör formatıdır, yani kayıpsız olarak yeniden boyutlandırılabilir. İkincisi, SVG, HTML/CSS ile aynı özelliklere sahiptir ve bu da uygun bir İçerik Güvenliği Politikası olmadan güvenlik açıklarına yol açabilir.

SVG görüntülerini varsayılan Görüntü Optimizasyon API'si ile sunmanız gerekiyorsa, dangerouslyAllowSVG adresini next.config.js adresinizin içinde ayarlayabilirsiniz:

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

Buna ek olarak, tarayıcıyı görüntüyü indirmeye zorlamak için contentDispositionType ve görüntüye gömülü komut dosyalarının yürütülmesini önlemek için contentSecurityPolicy ayarlarının da yapılması şiddetle tavsiye edilir.

Animated Images

Varsayılan yükleyici, animasyonlu görüntüler için Görüntü Optimizasyonunu otomatik olarak atlar ve görüntüyü olduğu gibi sunar.

Animasyonlu dosyalar için otomatik algılama en iyi çabadır ve GIF, APNG ve WebP'yi destekler. Belirli bir animasyonlu görüntü için Görüntü Optimizasyonunu açıkça atlamak istiyorsanız, optimize edilmemiş prop kullanın.

Responsive Images

Varsayılan olarak oluşturulan srcset, farklı cihaz piksel oranlarını desteklemek için 1x ve 2x görüntülerini içerir. Ancak, görüntü alanıyla birlikte uzayan duyarlı bir görüntü oluşturmak isteyebilirsiniz. Bu durumda, şunları ayarlamanız gerekir sizes yanı sıra style (veya className).

Aşağıdaki yöntemlerden birini kullanarak duyarlı bir görüntü oluşturabilirsiniz.

Responsive image using a static import

Kaynak görüntü dinamik değilse, duyarlı bir görüntü oluşturmak için statik olarak içe aktarabilirsiniz:

components/author.js
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',
      }}
    />
  )
}

Dene bakalım:

Responsive image with aspect ratio

Kaynak görüntü dinamik veya uzak bir url ise, duyarlı görüntünün doğru en boy oranını ayarlamak için width ve height adreslerini de sağlamanız gerekecektir:

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

Dene bakalım:

Responsive image with fill

En boy oranını bilmiyorsanız, en boy oranını ayarlamanız gerekecektir. fill prop öğesini seçin ve üst öğede position: relative öğesini ayarlayın. İsteğe bağlı olarak, istenen uzatma ve kırpma davranışına bağlı olarak object-fit stilini ayarlayabilirsiniz:

app/page.js
import Image from 'next/image'
 
export default function Page({ photoUrl }) {
  return (
    <div style={{ position: 'relative', width: '500px', height: '300px' }}>
      <Image
        src={photoUrl}
        alt="Picture of the author"
        sizes="500px"
        fill
        style={{
          objectFit: 'contain',
        }}
      />
    </div>
  )
}

Dene bakalım:

Theme Detection

Açık ve koyu mod için farklı bir görüntü görüntülemek istiyorsanız, iki <Image> bileşenini saran ve bir CSS medya sorgusuna dayalı olarak doğru olanı gösteren yeni bir bileşen oluşturabilirsiniz.

components/theme-image.module.css
.imgDark {
  display: none;
}
 
@media (prefers-color-scheme: dark) {
  .imgLight {
    display: none;
  }
  .imgDark {
    display: unset;
  }
}
components/theme-image.tsx
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} />
    </>
  )
}

Bilmekte fayda var: loading="lazy" adresinin varsayılan davranışı yalnızca doğru resmin yüklenmesini sağlar. Her iki resmin de yüklenmesine neden olacağından priority veya loading="eager" kullanamazsınız. Bunun yerine şunları kullanabilirsiniz fetchPriority="high".

Dene bakalım:

Known Browser Bugs

Bu next/image bileşeni, Safari 15.4'ten önceki eski tarayıcılar için istekli yüklemeye geri dönebilen tarayıcıya özgü tembel yükleme kullanır. Bulanıklaştırma yer tutucusunu kullanırken, Safari 12'den önceki eski tarayıcılar boş yer tutucusuna geri dönecektir. width /height of auto içeren stiller kullanıldığında, en boy oranını korumayan Safari 15 öncesi eski tarayıcılarda Düzen Kaydırma sorununa neden olabilir. Daha fazla ayrıntı için bu MDN videosuna bakın.

Version History

VersionChanges
v14.0.0onLoadingComplete prop and domains config deprecated.
v13.4.14placeholder prop support for data:/image...
v13.2.0contentDispositionType configuration added.
v13.0.6ref prop added.
v13.0.0The next/image import was renamed to next/legacy/image. The next/future/image import was renamed to next/image. A codemod is available to safely and automatically rename your imports. <span> wrapper removed. layout, objectFit, objectPosition, lazyBoundary, lazyRoot props removed. alt is required. onLoadingComplete receives reference to img element. Built-in loader config removed.
v12.3.0remotePatterns and unoptimized configuration is stable.
v12.2.0Experimental remotePatterns and experimental unoptimized configuration added. layout="raw" removed.
v12.1.1style prop added. Experimental support for layout="raw" added.
v12.1.0dangerouslyAllowSVG and contentSecurityPolicy configuration added.
v12.0.9lazyRoot prop added.
v12.0.0formats configuration added.
AVIF support added.
Wrapper <div> changed to <span>.
v11.1.0onLoadingComplete and lazyBoundary props added.
v11.0.0src prop support for static import.
placeholder prop added.
blurDataURL prop added.
v10.0.5loader prop added.
v10.0.1layout prop added.
v10.0.0next/image introduced.