<Script>

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

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

Свойства

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

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

Обязательные свойства

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

src

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

Необязательные свойства

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

strategy

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

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

beforeInteractive

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

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

Скрипты со стратегией beforeInteractive должны размещаться внутри компонента Document (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:

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

afterInteractive

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

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

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

Вот некоторые примеры скриптов, которые подходят для стратегии afterInteractive:

Менеджеры тегов
Аналитика

lazyOnload

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

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

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:

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

onLoad

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

Некоторые сторонние скрипты требуют от пользователей выполнения JavaScript-кода после завершения загрузки скрипта для инициализации содержимого или вызова функции. Если вы загружаете скрипт со стратегией загрузки после interactive или 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]))
        }}
      />
    </>
  )
}

onReady

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

Некоторые сторонние скрипты требуют от пользователей выполнения JavaScript-кода после завершения загрузки скрипта и каждый раз при монтировании компонента (например, после навигации по маршрутам). Вы можете выполнить код после события загрузки скрипта при первой загрузке, а затем после каждого последующего повторного монтирования компонента, используя свойство 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('Script failed to load', e)
        }}
      />
    </>
  )
}

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

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