如何优化第三方库

@next/third-parties 是一个库，它提供了一系列组件和实用工具，旨在提升在 Next.js 应用程序中加载常用第三方库时的性能和开发者体验。

所有由 @next/third-parties 提供的第三方集成都经过了性能和易用性优化。

开始使用

要开始使用，请安装 @next/third-parties 库：

bash

npm install @next/third-parties@latest next@latest

@next/third-parties 目前是一个正在积极开发中的实验性库。在我们努力添加更多第三方集成时，我们建议您使用 latest 或 canary 标志进行安装。

Google 第三方集成

所有受支持的 Google 第三方库都可以从 @next/third-parties/google 导入。

Google 标签管理器

GoogleTagManager 组件可用于在您的页面中实例化一个 Google 标签管理器容器。默认情况下，它会在页面水合（hydration）后获取原始的内联脚本。

App Router Only

要为所有路由加载 Google 标签管理器，请将该组件直接包含在您的根布局中，并传入您的 GTM 容器 ID：

tsx

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

jsx

import { GoogleTagManager } from '@next/third-parties/google'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <GoogleTagManager gtmId="GTM-XYZ" />
      <body>{children}</body>
    </html>
  )
}

Pages Router Only

要为所有路由加载 Google 标签管理器，请将该组件直接包含在您的自定义 _app 中，并传入您的 GTM 容器 ID：

jsx

import { GoogleTagManager } from '@next/third-parties/google'

export default function MyApp({ Component, pageProps }) {
  return (
    <>
      <Component {...pageProps} />
      <GoogleTagManager gtmId="GTM-XYZ" />
    </>
  )
}

要为单个路由加载 Google 标签管理器，请将该组件包含在您的页面文件中：

App Router Only

jsx

import { GoogleTagManager } from '@next/third-parties/google'

export default function Page() {
  return <GoogleTagManager gtmId="GTM-XYZ" />
}

Pages Router Only

jsx

import { GoogleTagManager } from '@next/third-parties/google'

export default function Page() {
  return <GoogleTagManager gtmId="GTM-XYZ" />
}

发送事件

sendGTMEvent 函数可用于通过使用 dataLayer 对象发送事件来跟踪页面上的用户交互。为了使此函数正常工作，<GoogleTagManager /> 组件必须包含在父布局、页面或组件中，或直接包含在同一文件中。

App Router Only

jsx

'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>
  )
}

Pages Router Only

jsx

import { sendGTMEvent } from '@next/third-parties/google'

export function EventButton() {
  return (
    <div>
      <button
        onClick={() => sendGTMEvent({ event: 'buttonClicked', value: 'xyz' })}
      >
        Send Event
      </button>
    </div>
  )
}

请参阅标签管理器开发者文档，了解可以传递给该函数的不同变量和事件。

服务器端标签

如果您正在使用服务器端标签管理器并从您的标签服务器提供 gtm.js 脚本，您可以使用 gtmScriptUrl 选项来指定脚本的 URL。

选项

传递给 Google 标签管理器的选项。有关完整选项列表，请阅读 Google 标签管理器文档。

Name	Type	Description
`gtmId`	Required*	您的 GTM 容器 ID。通常以 `GTM-` 开头。
`gtmScriptUrl`	Optional*	GTM 脚本 URL。默认为 `https://www.googletagmanager.com/gtm.js`。
`dataLayer`	Optional	用于实例化容器的数据层对象。
`dataLayerName`	Optional	数据层的名称。默认为 `dataLayer`。
`auth`	Optional	环境代码段的身份验证参数 (`gtm_auth`) 值。
`preview`	Optional	环境代码段的预览参数 (`gtm_preview`) 值。

*当提供 gtmScriptUrl 以支持 Google 广告商标签网关时，可以省略 gtmId。

Google Analytics

GoogleAnalytics 组件可用于通过 Google 标签 (gtag.js) 将 Google Analytics 4 包含到您的页面中。默认情况下，它会在页面水合（hydration）后获取原始脚本。

建议：如果您的应用程序中已包含 Google 标签管理器，您可以直接使用它来配置 Google Analytics，而不是将 Google Analytics 作为单独的组件包含进来。请参阅文档，了解标签管理器与 gtag.js 之间的区别。

App Router Only

要为所有路由加载 Google Analytics，请将该组件直接包含在您的根布局中，并传入您的衡量 ID：

tsx

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

jsx

import { GoogleAnalytics } from '@next/third-parties/google'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>{children}</body>
      <GoogleAnalytics gaId="G-XYZ" />
    </html>
  )
}

Pages Router Only

要为所有路由加载 Google Analytics，请将该组件直接包含在您的自定义 _app 中，并传入您的衡量 ID：

jsx

import { GoogleAnalytics } from '@next/third-parties/google'

export default function MyApp({ Component, pageProps }) {
  return (
    <>
      <Component {...pageProps} />
      <GoogleAnalytics gaId="G-XYZ" />
    </>
  )
}

要为单个路由加载 Google Analytics，请将该组件包含在您的页面文件中：

App Router Only

jsx

import { GoogleAnalytics } from '@next/third-parties/google'

export default function Page() {
  return <GoogleAnalytics gaId="G-XYZ" />
}

Pages Router Only

jsx

import { GoogleAnalytics } from '@next/third-parties/google'

export default function Page() {
  return <GoogleAnalytics gaId="G-XYZ" />
}

发送事件

sendGAEvent 函数可用于通过使用 dataLayer 对象发送事件来衡量页面上的用户交互。为了使此函数正常工作，<GoogleAnalytics /> 组件必须包含在父布局、页面或组件中，或直接包含在同一文件中。

App Router Only

jsx

'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>
  )
}

Pages Router Only

jsx

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 路由之间的客户端导航将发送页面浏览数据，无需任何配置。

为确保正确衡量客户端导航，请验证您的管理面板中是否启用了 “Enhanced Measurement” 属性，并且是否选中了 “Page changes based on browser history events” 复选框。

注意：如果您决定手动发送页面浏览事件，请务必禁用默认的页面浏览衡量功能，以避免重复数据。请参阅 Google Analytics 开发者文档，了解更多信息。

选项

传递给 <GoogleAnalytics> 组件的选项。

Name	Type	Description
`gaId`	Required	您的衡量 ID。通常以 `G-` 开头。
`dataLayerName`	Optional	数据层的名称。默认为 `dataLayer`。
`nonce`	Optional	一个 nonce。

Google 地图嵌入

GoogleMapsEmbed 组件可用于将 Google 地图嵌入到您的页面中。默认情况下，它使用 loading 属性在首屏下方延迟加载嵌入内容。

App Router Only

jsx

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

Pages Router Only

jsx

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 地图嵌入的选项。有关完整选项列表，请阅读 Google 地图嵌入文档。

Name	Type	Description
`apiKey`	Required	您的 API 密钥。
`mode`	Required	地图模式
`height`	Optional	嵌入内容的高度。默认为 `auto`。
`width`	Optional	嵌入内容的宽度。默认为 `auto`。
`style`	Optional	将样式传递给 iframe。
`allowfullscreen`	Optional	允许特定地图部分全屏的属性。
`loading`	Optional	默认为 lazy。如果您知道嵌入内容会在首屏上方，请考虑更改。
`q`	Optional	定义地图标记位置。根据地图模式，这可能是必需的。
`center`	Optional	定义地图视图的中心。
`zoom`	Optional	设置地图的初始缩放级别。
`maptype`	Optional	定义要加载的地图图块类型。
`language`	Optional	定义用于 UI 元素和地图图块上标签显示的语言。
`region`	Optional	定义根据地缘政治敏感性要显示适当的边界和标签。

YouTube 嵌入

YouTubeEmbed 组件可用于加载和显示 YouTube 嵌入内容。该组件通过在底层使用 lite-youtube-embed 来实现更快加载。

App Router Only

jsx

import { YouTubeEmbed } from '@next/third-parties/google'

export default function Page() {
  return <YouTubeEmbed videoid="ogfYd705cRs" height={400} params="controls=0" />
}

Pages Router Only

jsx

import { YouTubeEmbed } from '@next/third-parties/google'

export default function Page() {
  return <YouTubeEmbed videoid="ogfYd705cRs" height={400} params="controls=0" />
}

选项

Name	Type	Description
`videoid`	Required	YouTube 视频 ID。
`width`	Optional	视频容器的宽度。默认为 `auto`。
`height`	Optional	视频容器的高度。默认为 `auto`。
`playlabel`	Optional	播放按钮的视觉隐藏标签，用于可访问性。
`params`	Optional	此处定义的视频播放器参数。参数作为查询参数字符串传递。例如：`params="controls=0&start=10&end=30"`
`style`	Optional	用于将样式应用于视频容器。

@next/third-parties 是一个库，它提供了一系列组件和实用工具，旨在提升在 Next.js 应用程序中加载常用第三方库时的性能和开发者体验。

所有由 @next/third-parties 提供的第三方集成都经过了性能和易用性优化。

开始使用

要开始使用，请安装 @next/third-parties 库：

bash

npm install @next/third-parties@latest next@latest

@next/third-parties 目前是一个正在积极开发中的实验性库。在我们努力添加更多第三方集成时，我们建议您使用 latest 或 canary 标志进行安装。

Google 第三方集成

所有受支持的 Google 第三方库都可以从 @next/third-parties/google 导入。

Google 标签管理器

GoogleTagManager 组件可用于在您的页面中实例化一个 Google 标签管理器容器。默认情况下，它会在页面水合（hydration）后获取原始的内联脚本。

App Router Only

要为所有路由加载 Google 标签管理器，请将该组件直接包含在您的根布局中，并传入您的 GTM 容器 ID：

tsx

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

jsx

import { GoogleTagManager } from '@next/third-parties/google'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <GoogleTagManager gtmId="GTM-XYZ" />
      <body>{children}</body>
    </html>
  )
}

Pages Router Only

要为所有路由加载 Google 标签管理器，请将该组件直接包含在您的自定义 _app 中，并传入您的 GTM 容器 ID：

jsx

import { GoogleTagManager } from '@next/third-parties/google'

export default function MyApp({ Component, pageProps }) {
  return (
    <>
      <Component {...pageProps} />
      <GoogleTagManager gtmId="GTM-XYZ" />
    </>
  )
}

要为单个路由加载 Google 标签管理器，请将该组件包含在您的页面文件中：

App Router Only

jsx

import { GoogleTagManager } from '@next/third-parties/google'

export default function Page() {
  return <GoogleTagManager gtmId="GTM-XYZ" />
}

Pages Router Only

jsx

import { GoogleTagManager } from '@next/third-parties/google'

export default function Page() {
  return <GoogleTagManager gtmId="GTM-XYZ" />
}

发送事件

App Router Only

jsx

'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>
  )
}

Pages Router Only

jsx

import { sendGTMEvent } from '@next/third-parties/google'

export function EventButton() {
  return (
    <div>
      <button
        onClick={() => sendGTMEvent({ event: 'buttonClicked', value: 'xyz' })}
      >
        Send Event
      </button>
    </div>
  )
}

请参阅标签管理器开发者文档，了解可以传递给该函数的不同变量和事件。

服务器端标签

如果您正在使用服务器端标签管理器并从您的标签服务器提供 gtm.js 脚本，您可以使用 gtmScriptUrl 选项来指定脚本的 URL。

选项

传递给 Google 标签管理器的选项。有关完整选项列表，请阅读 Google 标签管理器文档。

Name	Type	Description
`gtmId`	Required*	您的 GTM 容器 ID。通常以 `GTM-` 开头。
`gtmScriptUrl`	Optional*	GTM 脚本 URL。默认为 `https://www.googletagmanager.com/gtm.js`。
`dataLayer`	Optional	用于实例化容器的数据层对象。
`dataLayerName`	Optional	数据层的名称。默认为 `dataLayer`。
`auth`	Optional	环境代码段的身份验证参数 (`gtm_auth`) 值。
`preview`	Optional	环境代码段的预览参数 (`gtm_preview`) 值。

*当提供 gtmScriptUrl 以支持 Google 广告商标签网关时，可以省略 gtmId。

Google Analytics

GoogleAnalytics 组件可用于通过 Google 标签 (gtag.js) 将 Google Analytics 4 包含到您的页面中。默认情况下，它会在页面水合（hydration）后获取原始脚本。

建议：如果您的应用程序中已包含 Google 标签管理器，您可以直接使用它来配置 Google Analytics，而不是将 Google Analytics 作为单独的组件包含进来。请参阅文档，了解标签管理器与 gtag.js 之间的区别。

App Router Only

要为所有路由加载 Google Analytics，请将该组件直接包含在您的根布局中，并传入您的衡量 ID：

tsx

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

jsx

import { GoogleAnalytics } from '@next/third-parties/google'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>{children}</body>
      <GoogleAnalytics gaId="G-XYZ" />
    </html>
  )
}

Pages Router Only

要为所有路由加载 Google Analytics，请将该组件直接包含在您的自定义 _app 中，并传入您的衡量 ID：

jsx

import { GoogleAnalytics } from '@next/third-parties/google'

export default function MyApp({ Component, pageProps }) {
  return (
    <>
      <Component {...pageProps} />
      <GoogleAnalytics gaId="G-XYZ" />
    </>
  )
}

要为单个路由加载 Google Analytics，请将该组件包含在您的页面文件中：

App Router Only

jsx

import { GoogleAnalytics } from '@next/third-parties/google'

export default function Page() {
  return <GoogleAnalytics gaId="G-XYZ" />
}

Pages Router Only

jsx

import { GoogleAnalytics } from '@next/third-parties/google'

export default function Page() {
  return <GoogleAnalytics gaId="G-XYZ" />
}

发送事件

App Router Only

jsx

'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>
  )
}

Pages Router Only

jsx

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> 组件的选项。

Name	Type	Description
`gaId`	Required	您的衡量 ID。通常以 `G-` 开头。
`dataLayerName`	Optional	数据层的名称。默认为 `dataLayer`。
`nonce`	Optional	一个 nonce。

Google 地图嵌入

GoogleMapsEmbed 组件可用于将 Google 地图嵌入到您的页面中。默认情况下，它使用 loading 属性在首屏下方延迟加载嵌入内容。

App Router Only

jsx

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

Pages Router Only

jsx

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 地图嵌入的选项。有关完整选项列表，请阅读 Google 地图嵌入文档。

Name	Type	Description
`apiKey`	Required	您的 API 密钥。
`mode`	Required	地图模式
`height`	Optional	嵌入内容的高度。默认为 `auto`。
`width`	Optional	嵌入内容的宽度。默认为 `auto`。
`style`	Optional	将样式传递给 iframe。
`allowfullscreen`	Optional	允许特定地图部分全屏的属性。
`loading`	Optional	默认为 lazy。如果您知道嵌入内容会在首屏上方，请考虑更改。
`q`	Optional	定义地图标记位置。根据地图模式，这可能是必需的。
`center`	Optional	定义地图视图的中心。
`zoom`	Optional	设置地图的初始缩放级别。
`maptype`	Optional	定义要加载的地图图块类型。
`language`	Optional	定义用于 UI 元素和地图图块上标签显示的语言。
`region`	Optional	定义根据地缘政治敏感性要显示适当的边界和标签。

YouTube 嵌入

YouTubeEmbed 组件可用于加载和显示 YouTube 嵌入内容。该组件通过在底层使用 lite-youtube-embed 来实现更快加载。

App Router Only

jsx

import { YouTubeEmbed } from '@next/third-parties/google'

export default function Page() {
  return <YouTubeEmbed videoid="ogfYd705cRs" height={400} params="controls=0" />
}

Pages Router Only

jsx

import { YouTubeEmbed } from '@next/third-parties/google'

export default function Page() {
  return <YouTubeEmbed videoid="ogfYd705cRs" height={400} params="controls=0" />
}

选项

Name	Type	Description
`videoid`	Required	YouTube 视频 ID。
`width`	Optional	视频容器的宽度。默认为 `auto`。
`height`	Optional	视频容器的高度。默认为 `auto`。
`playlabel`	Optional	播放按钮的视觉隐藏标签，用于可访问性。
`params`	Optional	此处定义的视频播放器参数。参数作为查询参数字符串传递。例如：`params="controls=0&start=10&end=30"`
`style`	Optional	用于将样式应用于视频容器。

文档导航

开始使用

Google 第三方集成

Google 标签管理器

发送事件

服务器端标签

选项

Google Analytics

发送事件

跟踪页面浏览量

选项

Google 地图嵌入

选项

YouTube 嵌入

选项

开始使用

Google 第三方集成

Google 标签管理器

发送事件

服务器端标签

选项

Google Analytics

发送事件

跟踪页面浏览量

选项

Google 地图嵌入

选项

YouTube 嵌入

选项