logoNext.js Русский
ДокументацияБлогИзучение
Введение/Справочник API/Компоненты/Компонент <Script>

Компонент <Script>

Это справочник API поможет вам разобраться, как использовать пропсы, доступные для компонента Script. Для информации о возможностях и использовании см. страницу Оптимизация скриптов.

import Script from 'next/script'

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

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

Пропсы

Вот сводка доступных пропсов для компонента Script:

ПропсПримерТипОбязательность
srcsrc="http://example.com/script"StringОбязателен, если не используется встроенный скрипт
strategystrategy="lazyOnload"String-
onLoadonLoad={onLoadFunc}Function-
onReadyonReady={onReadyFunc}Function-
onErroronError={onErrorFunc}Function-

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

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

src

Строка, указывающая URL внешнего скрипта. Может быть абсолютным внешним URL или внутренним путём. Свойство src обязательно, если не используется встроенный скрипт.

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

Компонент <Script /> принимает ряд дополнительных свойств помимо обязательных.

strategy

Стратегия загрузки скрипта. Доступны четыре стратегии:

  • beforeInteractive: Загружается до любого кода Next.js и до гидратации страницы.
  • afterInteractive: (по умолчанию) Загружается рано, но после частичной гидратации страницы.
  • lazyOnload: Загружается в период простоя браузера.
  • worker: (экспериментальная) Загружается в веб-воркере.

beforeInteractive

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

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

Скрипты beforeInteractive должны размещаться в корневом layout (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>
  )
}
import Script from 'next/script'

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

Полезно знать: Скрипты с beforeInteractive всегда встраиваются в head HTML-документа, независимо от их расположения в компоненте.

Примеры скриптов, которые следует загружать как можно раньше с beforeInteractive:

  • Детекторы ботов
  • Менеджеры согласия на использование cookies

afterInteractive

Скрипты с стратегией afterInteractive встраиваются в HTML на стороне клиента и загружаются после частичной (или полной) гидратации страницы. Это стратегия по умолчанию для компонента Script и должна использоваться для скриптов, которые нужно загрузить как можно скорее, но не раньше кода Next.js.

Скрипты afterInteractive можно размещать на любой странице или в layout, и они загружаются только при открытии этой страницы (или группы страниц) в браузере.

app/page.js
import Script from 'next/script'

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

Примеры скриптов, для которых подходит afterInteractive:

  • Менеджеры тегов
  • Системы аналитики

lazyOnload

Скрипты с стратегией lazyOnload встраиваются в HTML на стороне клиента в период простоя браузера и загружаются после загрузки всех ресурсов страницы. Эта стратегия подходит для фоновых или низкоприоритетных скриптов, которые не требуют ранней загрузки.

Скрипты lazyOnload можно размещать на любой странице или в layout, и они загружаются только при открытии этой страницы (или группы страниц) в браузере.

app/page.js
import Script from 'next/script'

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

Примеры скриптов, которые не требуют немедленной загрузки и могут использовать lazyOnload:

  • Плагины поддержки чата
  • Виджеты социальных сетей

worker

Предупреждение: Стратегия worker ещё не стабильна и не работает с app директорией. Используйте с осторожностью.

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

Для использования стратегии worker необходимо включить флаг nextScriptWorkers в next.config.js:

next.config.js
module.exports = {
  experimental: {
    nextScriptWorkers: true,
  },
}

Скрипты worker пока можно использовать только в директории pages/:

import Script from 'next/script'

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

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

onLoad

Предупреждение: onLoad пока не работает с Server Components и может использоваться только в Client Components. Кроме того, onLoad нельзя использовать с beforeInteractive — вместо этого рассмотрите onReady.

Некоторые сторонние скрипты требуют выполнения JavaScript кода после загрузки скрипта для инициализации контента или вызова функции. Если вы загружаете скрипт со стратегией afterInteractive или lazyOnload, вы можете выполнить код после его загрузки с помощью свойства onLoad.

Пример выполнения метода lodash только после загрузки библиотеки:

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

Предупреждение: onReady пока не работает с Server Components и может использоваться только в Client Components.

Некоторые сторонние скрипты требуют выполнения JavaScript кода после загрузки скрипта и при каждом монтировании компонента (например, после навигации по маршруту). Вы можете выполнить код после события загрузки скрипта и при каждом последующем монтировании компонента с помощью свойства onReady.

Пример повторной инициализации Google Maps JS при каждом монтировании компонента:

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

Предупреждение: onError пока не работает с Server Components и может использоваться только в Client Components. onError нельзя использовать со стратегией beforeInteractive.

Иногда полезно отслеживать ошибки загрузки скриптов. Эти ошибки можно обрабатывать с помощью свойства onError:

'use client'

import Script from 'next/script'

export default function Page() {
  return (
    <>
      <Script
        src="https://example.com/script.js"
        onError={(e: Error) => {
          console.error('Ошибка загрузки скрипта', e)
        }}
      />
    </>
  )
}
'use client'

import Script from 'next/script'

export default function Page() {
  return (
    <>
      <Script
        src="https://example.com/script.js"
        onError={(e: Error) => {
          console.error('Ошибка загрузки скрипта', e)
        }}
      />
    </>
  )
}

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

ВерсияИзменения
v13.0.0beforeInteractive и afterInteractive модифицированы для поддержки app.
v12.2.4Добавлен пропс onReady.
v12.2.2Разрешено размещение next/script с beforeInteractive в _document.
v11.0.0Введён next/script.

<Link>

Обеспечьте быструю клиентскую навигацию с помощью встроенного компонента `next/link`.

Соглашения по именованию файлов

Справочник API для специальных файлов Next.js.