第三方库

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

¥**@next/third-parties** is a library that provides a collection of components and utilities that improve the performance and developer experience of loading popular third-party libraries in your Next.js application.

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

¥All third-party integrations provided by @next/third-parties have been optimized for performance and ease of use.

入门

¥Getting Started

首先，安装 @next/third-parties 库：

¥To get started, install the @next/third-parties library:

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

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

¥@next/third-parties is currently an experimental library under active development. We recommend installing it with the latest or canary flags while we work on adding more third-party integrations.

谷歌第三方

¥Google Third-Parties

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

¥All supported third-party libraries from Google can be imported from @next/third-parties/google.

谷歌标签管理器

¥Google Tag Manager

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

¥The GoogleTagManager component can be used to instantiate a Google Tag Manager container to your page. By default, it fetches the original inline script after hydration occurs on the page.

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

¥To load Google Tag Manager for all routes, include the component directly in your root layout and pass in your GTM container 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 跟踪代码管理器，请将该组件包含在你的页面文件中：

¥To load Google Tag Manager for a single route, include the component in your page file:

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

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

发送事件

¥Sending Events

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

¥The sendGTMEvent function can be used to track user interactions on your page by sending events using the dataLayer object. For this function to work, the <GoogleTagManager /> component must be included in either a parent layout, page, or component, or directly in the same file.

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

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

¥Refer to the Tag Manager developer documentation to learn about the different variables and events that can be passed into the function.

选项

¥Options

传递到 Google 跟踪代码管理器的选项。有关选项的完整列表，请阅读 Google 跟踪代码管理器文档。

¥Options to pass to the Google Tag Manager. For a full list of options, read the Google Tag Manager docs.

名称	类型	描述
`gtmId`	必需的	你的 GTM 容器 ID。通常以 `GTM-` 开头。
`dataLayer`	可选的	用于实例化容器的数据层数组。默认为空数组。
`dataLayerName`	可选的	数据层的名称。默认为 `dataLayer`。
`auth`	可选的	环境片段的身份验证参数 (`gtm_auth`) 的值。
`preview`	可选的	环境片段的预览参数 (`gtm_preview`) 的值。

谷歌分析

¥Google Analytics

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

¥The GoogleAnalytics component can be used to include Google Analytics 4 to your page via the Google tag (gtag.js). By default, it fetches the original scripts after hydration occurs on the page.

推荐：如果你的应用中已包含 Google 跟踪代码管理器，你可以直接使用它配置 Google Analytics，而不是将 Google Analytics 作为单独的组件包含在内。请参阅 documentation，了解有关跟踪代码管理器和 gtag.js 之间差异的更多信息。

¥Recommendation: If Google Tag Manager is already included in your application, you can configure Google Analytics directly using it, rather than including Google Analytics as a separate component. Refer to the documentation to learn more about the differences between Tag Manager and gtag.js.

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

¥To load Google Analytics for all routes, include the component directly in your root layout and pass in your measurement 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（分析），请将该组件包含在你的页面文件中：

¥To load Google Analytics for a single route, include the component in your page file:

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

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

发送事件

¥Sending Events

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

¥The sendGAEvent function can be used to measure user interactions on your page by sending events using the dataLayer object. For this function to work, the <GoogleAnalytics /> component must be included in either a parent layout, page, or component, or directly in the same file.

'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 开发者文档了解有关事件参数的更多信息。

¥Refer to the Google Analytics developer documentation to learn more about event parameters.

跟踪浏览量

¥Tracking Pageviews

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

¥Google Analytics automatically tracks pageviews when the browser history state changes. This means that client-side navigations between Next.js routes will send pageview data without any configuration.

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

¥To ensure that client-side navigations are being measured correctly, verify that the “Enhanced Measurement” property is enabled in your Admin panel and the “Page changes based on browser history events” checkbox is selected.

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

¥Note: If you decide to manually send pageview events, make sure to disable the default pageview measurement to avoid having duplicate data. Refer to the Google Analytics developer documentation to learn more.

选项

¥Options

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

¥Options to pass to the <GoogleAnalytics> component.

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

谷歌地图嵌入

¥Google Maps Embed

GoogleMapsEmbed 组件可用于将谷歌地图嵌入添加到你的页面。默认情况下，它使用 loading 属性来延迟加载首屏下的嵌入内容。

¥The GoogleMapsEmbed component can be used to add a Google Maps Embed to your page. By default, it uses the loading attribute to lazy-load the embed below the fold.

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

选项

¥Options

传递到 Google 地图嵌入的选项。有关选项的完整列表，请阅读 Google 地图嵌入文档。

¥Options to pass to the Google Maps Embed. For a full list of options, read the Google Map Embed docs.

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

YouTube 嵌入

¥YouTube Embed

YouTubeEmbed 组件可用于加载和显示 YouTube 嵌入内容。通过在后台使用 lite-youtube-embed，该组件加载速度更快。

¥The YouTubeEmbed component can be used to load and display a YouTube embed. This component loads faster by using lite-youtube-embed under the hood.

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

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

选项

¥Options

名称	类型	描述
`videoid`	必需的	YouTube 视频 ID。
`width`	可选的	视频容器的宽度。默认为 `auto`
`height`	可选的	视频容器的高度。默认为 `auto`
`playlabel`	可选的	播放按钮的视觉隐藏标签以方便访问。
`params`	可选的	视频播放器参数定义为此处。参数作为查询参数字符串传递。例如：`params="controls=0&start=10&end=30"`
`style`	可选的	用于将样式应用到视频容器。

入门​

谷歌第三方​

谷歌标签管理器​

发送事件​

选项​

谷歌分析​

发送事件​

跟踪浏览量​

选项​

谷歌地图嵌入​

选项​

YouTube 嵌入​

选项​

入门

谷歌第三方

谷歌标签管理器

发送事件

选项

谷歌分析

发送事件

跟踪浏览量

选项

谷歌地图嵌入

选项

YouTube 嵌入

选项