第三方库

@next/third-parties 是一个库，提供了一系列组件和实用程序，可以提高在 Next.js 应用程序中加载流行第三方库的性能和开发人员体验。

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

入门

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

终端

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

@next/third-parties 目前是一个正在积极开发中的实验性库。我们建议在添加更多第三方集成时使用最新或canary标记安装它。

Google 第三方

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

Google 标记管理器

GoogleTagManager 组件可用于将Google 标记管理器容器实例化到您的页面。默认情况下，它会在页面上发生水合后获取原始内联脚本。

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

app/layout.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>
  )
}

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

app/page.js

import { GoogleTagManager } from '@next/third-parties/google'
 
export default function Page() {
  return <GoogleTagManager gtmId="GTM-XYZ" />
}

发送事件

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

app/page.js

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

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

服务器端标记

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

选项

传递给 Google Tag Manager 的选项。有关选项的完整列表，请阅读 Google Tag Manager 文档。

名称	类型	描述
`gtmId`	必需	您的 GTM 容器 ID。通常以 `GTM-` 开头。
`gtmScriptUrl`	可选	GTM 脚本 URL。默认为 `https://127.0.0.1/gtm.js`。
`dataLayer`	可选	用于实例化容器的数据层对象。
`dataLayerName`	可选	数据层的名称。默认为 `dataLayer`。
`auth`	可选	环境代码段中身份验证参数 (`gtm_auth`) 的值。
`preview`	可选	环境代码段中预览参数 (`gtm_preview`) 的值。

Google Analytics

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

建议：如果您的应用程序中已包含 Google Tag Manager，则可以直接使用它配置 Google Analytics，而不是将 Google Analytics 作为单独的组件包含在内。请参阅文档，详细了解 Tag Manager 和 gtag.js 之间的区别。

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

app/layout.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>
  )
}

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

app/page.js

import { GoogleAnalytics } from '@next/third-parties/google'
 
export default function Page() {
  return <GoogleAnalytics gaId="G-XYZ" />
}

发送事件

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

app/page.js

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

请参阅 Google Analytics 开发者文档，详细了解事件参数。

跟踪页面浏览量

浏览器历史记录状态发生变化时，Google Analytics 会自动跟踪页面浏览量。这意味着 Next.js 路由之间的客户端导航将发送页面浏览量数据，无需任何配置。

要确保客户端导航的正确测量，请验证您的管理面板中是否启用了 “增强型测量” 属性，并且已选中“基于浏览器历史记录事件的页面更改”复选框。

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

选项

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

名称	类型	描述
`gaId`	必需	您的衡量 ID。通常以 `G-` 开头。
`dataLayerName`	可选	数据层的名称。默认为 `dataLayer`。
`nonce`	可选	一个 nonce。

Google 地图嵌入

GoogleMapsEmbed 组件可用于将 Google 地图嵌入添加到您的页面中。默认情况下，它使用 loading 属性在折线以下延迟加载嵌入。

app/page.js

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 地图嵌入文档。

名称	类型	描述
`apiKey`	必需	您的 api 密钥。
`mode`	必需	地图模式
`height`	可选	嵌入的高度。默认为 `auto`。
`width`	可选	嵌入的宽度。默认为 `auto`。
`style`	可选	将样式传递给 iframe。
`allowfullscreen`	可选	允许某些地图部分全屏显示的属性。
`loading`	可选	默认为延迟加载。如果您知道嵌入将在折线以上，请考虑更改。
`q`	可选	定义地图标记位置。这可能根据地图模式而需要。
`center`	可选	定义地图视图的中心。
`zoom`	可选	设置地图的初始缩放级别。
`maptype`	可选	定义要加载的地图图块类型。
`language`	可选	定义用于 UI 元素以及地图图块上标签显示的语言。
`region`	可选	根据地缘政治敏感性定义要显示的适当边框和标签。

YouTube 嵌入

YouTubeEmbed 组件可用于加载和显示 YouTube 嵌入。此组件通过在后台使用 lite-youtube-embed 来更快地加载。

app/page.js

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`	可选	用于将样式应用于视频容器。