如何优化第三方库
使用 @next/third-parties 包优化应用中第三方库的性能。
@next/third-parties 是一个库,提供了一组组件和实用工具,用于改善在 Next.js 应用中加载流行第三方库的性能和开发者体验。
@next/third-parties 提供的所有第三方集成都针对性能和易用性进行了优化。
开始使用#
要开始使用,请安装 @next/third-parties 库:
pnpm add @next/third-parties@latest next@latestnpm install @next/third-parties@latest next@latestyarn add @next/third-parties@latest next@latestbun add @next/third-parties@latest next@latest@next/third-parties 目前是一个处于积极开发中的实验性库。在我们继续添加更多第三方集成期间,建议使用 latest 或 canary 标签安装它。
Google 第三方库#
所有受支持的 Google 第三方库都可以从 @next/third-parties/google 导入。
Google Tag Manager#
GoogleTagManager 组件可用于在你的页面中实例化一个 Google Tag Manager 容器。默认情况下,它会在页面发生 hydration 后获取原始内联脚本。
要为所有路由加载 Google Tag Manager,请直接在根布局中包含该组件,并传入你的 GTM 容器 ID:
import { GoogleTagManager } from '@next/third-parties/google'
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html lang="en">
<GoogleTagManager gtmId="GTM-XYZ" />
<body>{children}</body>
</html>
)
}import { GoogleTagManager } from '@next/third-parties/google'
export default function RootLayout({ children }) {
return (
<html lang="en">
<GoogleTagManager gtmId="GTM-XYZ" />
<body>{children}</body>
</html>
)
}要为所有路由加载 Google Tag Manager,请直接在自定义的 _app 中包含该组件,并传入你的 GTM 容器 ID:
import { GoogleTagManager } from '@next/third-parties/google'
export default function MyApp({ Component, pageProps }) {
return (
<>
<Component {...pageProps} />
<GoogleTagManager gtmId="GTM-XYZ" />
</>
)
}要为单个路由加载 Google Tag Manager,请在你页面文件中包含该组件:
import { GoogleTagManager } from '@next/third-parties/google'
export default function Page() {
return <GoogleTagManager gtmId="GTM-XYZ" />
}import { GoogleTagManager } from '@next/third-parties/google'
export default function Page() {
return <GoogleTagManager gtmId="GTM-XYZ" />
}发送事件#
sendGTMEvent 函数可用于通过使用 dataLayer 对象发送事件来跟踪页面上的用户交互。要使此函数正常工作,<GoogleTagManager /> 组件必须包含在父级布局、页面或组件中,或直接包含在同一个文件中。
'use client'
import { sendGTMEvent } from '@next/third-parties/google'
export function EventButton() {
return (
<div>
<button
onClick={() => sendGTMEvent({ event: 'buttonClicked', value: 'xyz' })}
>
Send Event
</button>
</div>
)
}import { sendGTMEvent } from '@next/third-parties/google'
export function EventButton() {
return (
<div>
<button
onClick={() => sendGTMEvent({ event: 'buttonClicked', value: 'xyz' })}
>
Send Event
</button>
</div>
)
}请参阅 Tag Manager 的开发者文档,了解可以传递给该函数的各种变量和事件。
服务端标记#
如果你使用服务端标记管理器并从标记服务器提供 gtm.js 脚本,可以使用 gtmScriptUrl 选项来指定脚本的 URL。
选项#
传递给 Google Tag Manager 的选项。有关选项的完整列表,请阅读 Google Tag Manager 文档。
| 名称 | 类型 | 描述 |
|---|---|---|
gtmId | 必需\* | 你的 GTM 容器 ID。通常以 GTM- 开头。 |
gtmScriptUrl | 可选\* | GTM 脚本 URL。默认为 https://www.googletagmanager.com/gtm.js。 |
dataLayer | 可选 | 用于实例化容器的数据层对象。 |
dataLayerName | 可选 | 数据层的名称。默认为 dataLayer。 |
auth | 可选 | 环境代码段的身份验证参数(gtm_auth)的值。 |
preview | 可选 | 环境代码段的预览参数(gtm_preview)的值。 |
\*当提供 gtmScriptUrl 时可以省略 gtmId,以支持面向广告客户的 Google 代码网关。
Google Analytics#
GoogleAnalytics 组件可用于通过 Google 代码(gtag.js)将 Google Analytics 4 包含到你的页面中。默认情况下,它会在页面发生 hydration 后获取原始脚本。
建议:如果你的应用中已经包含了 Google Tag Manager,你可以直接使用它来配置 Google Analytics,而不必将 Google Analytics 作为单独的组件包含进来。请参阅文档,了解 Tag Manager 与
gtag.js之间的区别。
要为所有路由加载 Google Analytics,请直接在根布局中包含该组件,并传入你的衡量 ID:
import { GoogleAnalytics } from '@next/third-parties/google'
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html lang="en">
<body>{children}</body>
<GoogleAnalytics gaId="G-XYZ" />
</html>
)
}import { GoogleAnalytics } from '@next/third-parties/google'
export default function RootLayout({ children }) {
return (
<html lang="en">
<body>{children}</body>
<GoogleAnalytics gaId="G-XYZ" />
</html>
)
}要为所有路由加载 Google Analytics,请直接在自定义的 _app 中包含该组件,并传入你的衡量 ID:
import { GoogleAnalytics } from '@next/third-parties/google'
export default function MyApp({ Component, pageProps }) {
return (
<>
<Component {...pageProps} />
<GoogleAnalytics gaId="G-XYZ" />
</>
)
}要为单个路由加载 Google Analytics,请在你页面文件中包含该组件:
import { GoogleAnalytics } from '@next/third-parties/google'
export default function Page() {
return <GoogleAnalytics gaId="G-XYZ" />
}import { GoogleAnalytics } from '@next/third-parties/google'
export default function Page() {
return <GoogleAnalytics gaId="G-XYZ" />
}发送事件#
sendGAEvent 函数可用于通过使用 dataLayer 对象发送事件来衡量页面上的用户交互。要使此函数正常工作,<GoogleAnalytics /> 组件必须包含在父级布局、页面或组件中,或直接包含在同一个文件中。
'use client'
import { sendGAEvent } from '@next/third-parties/google'
export function EventButton() {
return (
<div>
<button
onClick={() => sendGAEvent('event', 'buttonClicked', { value: 'xyz' })}
>
Send Event
</button>
</div>
)
}import { sendGAEvent } from '@next/third-parties/google'
export function EventButton() {
return (
<div>
<button
onClick={() => sendGAEvent('event', 'buttonClicked', { value: 'xyz' })}
>
Send Event
</button>
</div>
)
}请参阅 Google Analytics 的开发者文档,了解有关事件参数的更多信息。
跟踪页面浏览量#
当浏览器历史记录状态发生变化时,Google Analytics 会自动跟踪页面浏览量。这意味着 Next.js 路由之间的客户端导航无需任何配置即可发送页面浏览数据。
要确保正确衡量客户端导航,请确认你的管理面板中已启用“增强衡量”属性,并且已选中“基于浏览器历史记录事件的页面更改”复选框。
注意:如果你决定手动发送页面浏览事件,请务必禁用默认的页面浏览量衡量,以避免数据重复。请参阅 Google Analytics 的开发者文档了解更多信息。
选项#
传递给 <GoogleAnalytics> 组件的选项。
| 名称 | 类型 | 描述 |
|---|---|---|
gaId | 必需 | 你的衡量 ID。通常以 G- 开头。 |
dataLayerName | 可选 | 数据层的名称。默认为 dataLayer。 |
debugMode | 可选 | 启用 Google Analytics 调试模式。 |
nonce | 可选 | 一个 nonce。 |
Google Maps 嵌入#
GoogleMapsEmbed 组件可用于在你的页面中添加 Google Maps 嵌入。默认情况下,它使用 loading 属性对首屏之外的嵌入内容进行懒加载。
import { GoogleMapsEmbed } from '@next/third-parties/google'
export default function Page() {
return (
<GoogleMapsEmbed
apiKey="XYZ"
height={200}
width="100%"
mode="place"
q="Brooklyn+Bridge,New+York,NY"
/>
)
}import { GoogleMapsEmbed } from '@next/third-parties/google'
export default function Page() {
return (
<GoogleMapsEmbed
apiKey="XYZ"
height={200}
width="100%"
mode="place"
q="Brooklyn+Bridge,New+York,NY"
/>
)
}选项#
传递给 Google Maps Embed 的选项。有关选项的完整列表,请阅读 Google Map Embed 文档。
| 名称 | 类型 | 描述 |
|---|---|---|
apiKey | 必需 | 你的 api key。 |
mode | 必需 | 地图模式 |
height | 可选 | 嵌入内容的高度。默认为 auto。 |
width | 可选 | 嵌入内容的宽度。默认为 auto。 |
style | 可选 | 向 iframe 传递样式。 |
allowfullscreen | 可选 | 允许某些地图部分进入全屏的属性。 |
loading | 可选 | 默认为懒加载。如果你知道嵌入内容将在首屏内,请考虑更改此项。 |
q | 可选 | 定义地图标记的位置。根据地图模式,此项可能是必需的。 |
center | 可选 | 定义地图视图的中心。 |
zoom | 可选 | 设置地图的初始缩放级别。 |
maptype | 可选 | 定义要加载的地图瓦片类型。 |
language | 可选 | 定义用于 UI 元素和地图瓦片上标签显示的语言。 |
region | 可选 | 根据地缘政治敏感性,定义要显示的适当边界和标签。 |
YouTube 嵌入#
YouTubeEmbed 组件可用于加载和显示 YouTube 嵌入内容。该组件在底层使用 lite-youtube-embed,因此加载速度更快。
import { YouTubeEmbed } from '@next/third-parties/google'
export default function Page() {
return <YouTubeEmbed videoid="ogfYd705cRs" height={400} params="controls=0" />
}import { YouTubeEmbed } from '@next/third-parties/google'
export default function Page() {
return <YouTubeEmbed videoid="ogfYd705cRs" height={400} params="controls=0" />
}选项#
| 名称 | 类型 | 描述 |
|---|---|---|
videoid | 必需 | YouTube 视频 id。 |
width | 可选 | 视频容器的宽度。默认为 auto |
height | 可选 | 视频容器的高度。默认为 auto |
playlabel | 可选 | 为无障碍访问提供的播放按钮的视觉隐藏标签。 |
params | 可选 | 此处定义的视频播放器参数。 参数以查询参数字符串的形式传递。 例如: params="controls=0&start=10&end=30" |
style | 可选 | 用于向视频容器应用样式。 |