Компонент <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:

Пропс	Пример	Тип	Обязательность
`src`	`src="http://example.com/script"`	String	Обязателен, если не используется встроенный скрипт
`strategy`	`strategy="lazyOnload"`	String	-
`onLoad`	`onLoad={onLoadFunc}`	Function	-
`onReady`	`onReady={onReadyFunc}`	Function	-
`onError`	`onError={onErrorFunc}`	Function	-

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

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

`src`

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

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

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

`strategy`

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

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

`beforeInteractive`

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

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

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

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

pages/_document.js

import { Html, Head, Main, NextScript } from 'next/document'
import Script from 'next/script'

export default function Document() {
  return (
    <Html>
      <Head />
      <body>
        <Main />
        <NextScript />
        <Script
          src="https://example.com/script.js"
          strategy="beforeInteractive"
        />
      </body>
    </Html>
  )
}

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

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

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

`afterInteractive`

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

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

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 могут размещаться на любой странице или в лейауте и будут загружаться и выполняться только при открытии этой страницы (или группы страниц) в браузере.

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 пока не работает с серверными компонентами и может использоваться только в клиентских компонентах. Кроме того, 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 пока не работает с серверными компонентами и может использоваться только в клиентских компонентах.

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

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

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 пока не работает с серверными компонентами и может использоваться только в клиентских компонентах. onError нельзя использовать со стратегией загрузки beforeInteractive.

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

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.0`	`beforeInteractive` и `afterInteractive` изменены для поддержки `app`.
`v12.2.4`	Добавлен пропс `onReady`.
`v12.2.2`	Разрешено размещение `next/script` с `beforeInteractive` в `_document`.
`v11.0.0`	Введён `next/script`.

On this page