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"СтрокаОбязателен, если не используется встроенный скрипт
strategystrategy="lazyOnload"Строка-
onLoadonLoad={onLoadFunc}Функция-
onReadyonReady={onReadyFunc}Функция-
onErroronError={onErrorFunc}Функция-

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

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

src

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

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

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

strategy

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

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

beforeInteractive

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

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

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

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

import Script from 'next/script'

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

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <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 Router. Используйте с осторожностью.

Скрипты, использующие стратегию 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) => {
          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.