Script
此 API 参考将帮助你了解如何使用 Script 组件的props。 有关功能和用法,请参阅优化脚本页面。
import Script from 'next/script'
export default function Dashboard() {
return (
<>
<Script src="https://example.com/script.js" />
</>
)
}
Props
以下是 Script 组件可用 props 的摘要
Prop | 示例 | 类型 | 必需 |
---|---|---|---|
src | src="http://example.com/script" | String | 除非使用内联脚本,否则为必需 |
strategy | strategy="lazyOnload" | String | - |
onLoad | onLoad={onLoadFunc} | Function | - |
onReady | onReady={onReadyFunc} | Function | - |
onError | onError={onErrorFunc} | Function | - |
必需的 Props
<Script />
组件需要以下属性。
src
一个路径字符串,指定外部脚本的 URL。 这可以是绝对外部 URL 或内部路径。 除非使用内联脚本,否则 src
属性是必需的。
可选的 Props
<Script />
组件接受许多除必需属性之外的其他属性。
strategy
脚本的加载策略。 有四种不同的策略可以使用
beforeInteractive
:在任何 Next.js 代码之前以及任何页面 hydration 发生之前加载。afterInteractive
:(默认)尽早加载,但在页面上发生一些 hydration 之后加载。lazyOnload
:在浏览器空闲时间加载。worker
:(实验性)在 Web Worker 中加载。
beforeInteractive
使用 beforeInteractive
策略加载的脚本从服务器注入到初始 HTML 中,在任何 Next.js 模块之前下载,并按照它们在页面上任何 hydration 发生之前的放置顺序执行。
使用此策略表示的脚本会被预加载并在任何第一方代码之前获取,但它们的执行不会阻止页面 hydration 的发生。
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
的脚本将始终注入到 HTML 文档的head
中,无论它放置在组件中的哪个位置。
一些应该使用 beforeInteractive
尽快加载的脚本示例包括
- Bot 检测器
- Cookie 同意管理器
afterInteractive
使用 afterInteractive
策略的脚本注入到 HTML 客户端,并在页面上发生一些(或全部)hydration 后加载。 这是 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 Router。请谨慎使用。
使用 worker
策略的脚本会被卸载到 Web Worker 中,以释放主线程,并确保只有关键的第一方资源在其上处理。虽然此策略可用于任何脚本,但它是一种高级用例,不能保证支持所有第三方脚本。
要使用 worker
作为策略,必须在 next.config.js
中启用 nextScriptWorkers
标志。
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 代码,以便实例化内容或调用函数。如果您使用 afterInteractive
或 lazyOnload
作为加载策略加载脚本,则可以使用 onLoad
属性在脚本加载后执行代码。
这是一个仅在 lodash 库加载后执行 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 | 允许将带有 beforeInteractive 的 next/script 放置在 _document 中。 |
v11.0.0 | 引入了 next/script 。 |
这是否有帮助?