<Script>

Bu API referansı, Komut Dosyası Bileşeni için mevcut olan destekleri nasıl kullanacağınızı anlamanıza yardımcı olacaktır. Özellikler ve kullanım için lütfen Komut Dosyalarını Optimize Etme sayfasına bakın.

app/dashboard/page.tsx

import Script from 'next/script'
 
export default function Dashboard() {
  return (
    <>
      <Script src="https://example.com/script.js" />
    </>
  )
}

Props

İşte Komut Dosyası Bileşeni için mevcut olan aksesuarların bir özeti:

Prop	Example	Type	Required
`src`	`src="http://example.com/script"`	String	Required unless inline script is used
`strategy`	`strategy="lazyOnload"`	String	-
`onLoad`	`onLoad={onLoadFunc}`	Function	-
`onReady`	`onReady={onReadyFunc}`	Function	-
`onError`	`onError={onErrorFunc}`	Function	-

Required Props

<Script /> bileşeni aşağıdaki özellikleri gerektirir.

`src`

Harici bir komut dosyasının URL'sini belirten bir yol dizesi. Bu, mutlak bir harici URL veya dahili bir yol olabilir. Satır içi komut dosyası kullanılmadığı sürece src özelliği gereklidir.

Optional Props

<Script /> bileşeni, gerekli olanların ötesinde bir dizi ek özelliği kabul eder.

`strategy`

Kodun yükleme stratejisi. Kullanılabilecek dört farklı strateji vardır:

beforeInteractive: Herhangi bir Next.js kodundan önce ve herhangi bir sayfa hidrasyonu gerçekleşmeden önce yükleyin.
afterInteractive:(varsayılan) Erken yükleyin, ancak sayfada bir miktar hidrasyon gerçekleştikten sonra.
lazyOnload: Tarayıcı boşta kaldığı süre boyunca yükleyin.
worker: (deneysel) Bir web çalışanında yük.

`beforeInteractive`

beforeInteractive stratejisiyle yüklenen komut dosyaları sunucudan ilk HTML'ye enjekte edilir, herhangi bir Next.js modülünden önce indirilir ve sayfada herhangi bir hidrasyon gerçekleşmeden önce yerleştirildikleri sırada yürütülür.

Bu strateji ile belirtilen komut dosyaları önceden yüklenir ve birinci taraf kodlarından önce getirilir, ancak bunların yürütülmesi sayfa hidrasyonunun gerçekleşmesini engellemez.

beforeInteractive komut dosyaları kök düzeninin içine yerleştirilmelidir (app/layout.tsx) ve tüm site tarafından ihtiyaç duyulan komut dosyalarını yüklemek için tasarlanmıştır (yani, uygulamadaki herhangi bir sayfa sunucu tarafında yüklendiğinde komut dosyası yüklenecektir).

Bu strateji yalnızca sayfanın herhangi bir bölümü etkileşimli hale gelmeden önce getirilmesi gereken kritik komut dosyaları için kullanılmalıdır.

app/layout.tsx

import Script from 'next/script'
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>{children}</body>
      <Script
        src="https://example.com/script.js"
        strategy="beforeInteractive"
      />
    </html>
  )
}

Bilmekte fayda var: beforeInteractive içeren komut dosyaları, bileşenin neresine yerleştirildiğine bakılmaksızın her zaman HTML belgesinin head içine enjekte edilecektir.

beforeInteractive ile mümkün olan en kısa sürede yüklenmesi gereken bazı komut dosyası örnekleri şunlardır:

Bot dedektörleri
Çerez onayı yöneticileri

`afterInteractive`

afterInteractive stratejisini kullanan komut dosyaları HTML istemci tarafına enjekte edilir ve sayfada bazı (veya tüm) hidrasyon gerçekleştikten sonra yüklenir. Bu, Komut Dosyası bileşeninin varsayılan stratejisidir ve mümkün olan en kısa sürede yüklenmesi gereken ancak herhangi bir birinci taraf Next.js kodundan önce yüklenmemesi gereken tüm komut dosyaları için kullanılmalıdır.

afterInteractive Komut dosyaları herhangi bir sayfanın veya düzenin içine yerleştirilebilir ve yalnızca söz konusu sayfa (veya sayfa grubu) tarayıcıda açıldığında yüklenir ve yürütülür.

app/page.js

import Script from 'next/script'
 
export default function Page() {
  return (
    <>
      <Script src="https://example.com/script.js" strategy="afterInteractive" />
    </>
  )
}

afterInteractive için iyi aday olan bazı senaryo örnekleri şunlardır:

Etiket yöneticileri
Analitik

`lazyOnload`

lazyOnload stratejisini kullanan komut dosyaları, tarayıcının boşta kaldığı süre boyunca HTML istemci tarafına enjekte edilir ve sayfadaki tüm kaynaklar getirildikten sonra yüklenir. Bu strateji, erken yüklenmesi gerekmeyen arka plan veya düşük öncelikli komut dosyaları için kullanılmalıdır.

lazyOnload Komut dosyaları herhangi bir sayfanın veya düzenin içine yerleştirilebilir ve yalnızca söz konusu sayfa (veya sayfa grubu) tarayıcıda açıldığında yüklenir ve yürütülür.

app/page.js

import Script from 'next/script'
 
export default function Page() {
  return (
    <>
      <Script src="https://example.com/script.js" strategy="lazyOnload" />
    </>
  )
}

Hemen yüklenmesi gerekmeyen ve lazyOnload ile getirilebilen komut dosyalarına örnek olarak şunlar verilebilir:

Sohbet destek eklentileri
Sosyal medya widget'ları

`worker`

Uyarı: worker stratejisi henüz kararlı değildir ve henüz app dizin. Dikkatli kullanın.

worker stratejisini kullanan komut dosyaları, ana iş parçacığını boşaltmak ve yalnızca kritik, birinci taraf kaynakların işlenmesini sağlamak için bir web çalışanına yüklenir. Bu strateji herhangi bir komut dosyası için kullanılabilse de, tüm üçüncü taraf komut dosyalarını desteklemesi garanti edilmeyen gelişmiş bir kullanım durumudur.

worker adresini bir strateji olarak kullanmak için next.config.js adresinde nextScriptWorkers bayrağı etkinleştirilmelidir:

next.config.js

module.exports = {
  experimental: {
    nextScriptWorkers: true,
  },
}

worker komut dosyaları şu anda yalnızca pages/ dizininde kullanılabilir:

pages/home.tsx

import Script from 'next/script'
 
export default function Home() {
  return (
    <>
      <Script src="https://example.com/script.js" strategy="worker" />
    </>
  )
}

`onLoad`

Uyarı: onLoad henüz Sunucu Bileşenleri ile çalışmamaktadır ve sadece İstemci Bileşenlerinde kullanılabilir. Ayrıca, onLoad, beforeInteractive ile birlikte kullanılamaz - bunun yerine onReady kullanmayı düşünün.

Bazı üçüncü taraf komut dosyaları, içeriği örneklendirmek veya bir işlevi çağırmak için kullanıcıların JavaScript kodunu komut dosyası yüklendikten sonra bir kez çalıştırmasını gerektirir. Bir komut dosyasını yükleme stratejisi olarak afterInteractive veya lazyOnload ile yüklüyorsanız, onLoad özelliğini kullanarak kod yüklendikten sonra çalıştırabilirsiniz.

İşte bir lodash yönteminin yalnızca kütüphane yüklendikten sonra çalıştırılmasına ilişkin bir örnek.

app/page.tsx

'use client'
 
import Script from 'next/script'
 
export default function Page() {
  return (
    <>
      <Script
        src="https://cdnjs.cloudflare.com/ajax/libs/lodash.js/4.17.20/lodash.min.js"
        onLoad={() => {
          console.log(_.sample([1, 2, 3, 4]))
        }}
      />
    </>
  )
}

`onReady`

Uyarı: onReady henüz Sunucu Bileşenleri ile çalışmaz ve yalnızca İstemci Bileşenlerinde kullanılabilir.

Bazı üçüncü taraf komut dosyaları, komut dosyası yüklemeyi tamamladıktan sonra ve bileşen her takıldığında (örneğin bir rota gezintisinden sonra) kullanıcıların JavaScript kodunu çalıştırmasını gerektirir. Kod ilk yüklendiğinde kodun load olayından sonra ve ardından onReady özelliğini kullanarak sonraki her bileşen yeniden takıldıktan sonra kodu çalıştırabilirsiniz.

Bileşen her yüklendiğinde bir Google Maps JS katıştırmasının nasıl yeniden oluşturulacağına dair bir örnek aşağıda verilmiştir:

app/page.tsx

'use client'
 
import { useRef } from 'react'
import Script from 'next/script'
 
export default function Page() {
  const mapRef = useRef()
 
  return (
    <>
      <div ref={mapRef}></div>
      <Script
        id="google-maps"
        src="https://maps.googleapis.com/maps/api/js"
        onReady={() => {
          new google.maps.Map(mapRef.current, {
            center: { lat: -34.397, lng: 150.644 },
            zoom: 8,
          })
        }}
      />
    </>
  )
}

`onError`

Uyarı: onError henüz Sunucu Bileşenleri ile çalışmaz ve yalnızca İstemci Bileşenlerinde kullanılabilir. onError, beforeInteractive yükleme stratejisi ile kullanılamaz.

Bazen bir kod yüklenemediğinde yakalamak yararlı olabilir. Bu hatalar onError özelliği ile ele alınabilir:

app/page.tsx

'use client'
 
import Script from 'next/script'
 
export default function Page() {
  return (
    <>
      <Script
        src="https://example.com/script.js"
        onError={(e: Error) => {
          console.error('Script failed to load', e)
        }}
      />
    </>
  )
}

Version History

Version	Changes
`v13.0.0`	`beforeInteractive` and `afterInteractive` is modified to support `app`.
`v12.2.4`	`onReady` prop added.
`v12.2.2`	Allow `next/script` with `beforeInteractive` to be placed in `_document`.
`v11.0.0`	`next/script` introduced.