跳到主要内容
目录

第三方库

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

@next/third-parties 是一个新的实验性库，仍在积极开发中。

我们目前正在努力添加更多的第三方集成。

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

入门​

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

# 终端
npm install @next/third-parties

Google 第三方库​

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

Google Tag Manager​

GoogleTagManager 组件可用于向您的页面实例化 Google Tag Manager 容器。 默认情况下，在页面上进行 hydration 后，它会获取原始的内联脚本。

要为所有路由加载 Google Tag Manager，请直接将该组件包含在根布局中：

app/layout.tsx

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

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

要为单个路由加载 Google Tag Manager，请在页面文件中包含该组件：

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

有关可以传递到该函数的不同变量和事件的详细信息， 请参阅 Tag Manager 开发者文档。

选项​

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

名称类型描述
gtmIdRequired您的 GTM 容器 ID。
dataLayerOptional用于实例化容器的数据层数组。默认为空数组。
dataLayerNameOptional数据层的名称。默认为 dataLayer。
authOptional用于环境片段的身份验证参数（gtm_auth）的值。
previewOptional用于环境片段的预览参数（gtm_preview）的值。

Google Analytics​

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

备注

如果您的应用程序中已经包含了 Google Tag Manager， 您可以直接使用它来配置 Google Analytics， 而不必将 Google Analytics 作为单独的组件包含。 有关 Tag Manager 和 gtag.js 之间差异的更多信息， 请参阅文档。

要为所有路由加载 Google Analytics，请直接将该组件包含在根布局中：

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="GA-XYZ" />
    </html>
  )
}

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

app/page.js
import { GoogleAnalytics } from '@next/third-parties/google'

export default function Page() {
  return <GoogleAnalytics gaId="GA-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 开发者文档。

选项​

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

名称类型描述
gaIdRequired您的 Google 标签 ID。
dataLayerNameOptional数据层的名称。默认为 dataLayer。

Google Maps Embed​

GoogleMapsEmbed 组件可用于向您的页面添加 Google Maps 嵌入。 默认情况下，它使用 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 Maps Embed 的选项。有关所有选项的完整列表，请阅读 Google 地图嵌入文档。

名称类型描述
apiKeyRequired您的 API 密钥。
modeRequired地图模式。
heightOptional嵌入的高度。默认为自动。
widthOptional嵌入的宽度。默认为自动。
styleOptional将样式传递给 iframe。
allowfullscreenOptional允许某些地图部分全屏显示的属性。
loadingOptional默认为 lazy。如果您知道您的嵌入将在视图之上，请考虑更改。
qOptional定义地图标记位置。具体取决于地图模式是否需要。
centerOptional定义地图视图的中心。
zoomOptional设置地图的初始缩放级别。
maptypeOptional定义要加载的地图瓦片的类型。
languageOptional定义用于 UI 元素和地图瓦片标签显示的语言。
regionOptional根据地缘政治的敏感性定义要显示的适当边界和标签。

YouTube Embed​

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

选项​

名称类型描述
videoidRequiredYouTube 视频 ID。
widthOptional视频容器的宽度。默认为自动。
heightOptional视频容器的高度。默认为自动。
playlabelOptional用于无障碍性的播放按钮的可见标签。
paramsOptional在此定义的视频播放器参数。参数作为查询参数字符串传递。例如：params="controls=0&start=10&end=30"。
styleOptional用于将样式应用于视频容器。