第三方库

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

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

开始

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

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

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

Google 第三方

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

Google Tag Manager

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

要为所有路由加载 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，请在页面文件中包含该组件：

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

请参阅 Tag Manager开发者文档以了解可以传递给该函数的不同变量和事件。

选项

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

Name	Type	Description
`gtmId`	Required	Your GTM container ID. Usually starts with `GTM-`.
`dataLayer`	Optional	Data layer object to instantiate the container with.
`dataLayerName`	Optional	Name of the data layer. Defaults to `dataLayer`.
`auth`	Optional	Value of authentication parameter (`gtm_auth`) for environment snippets.
`preview`	Optional	Value of preview parameter (`gtm_preview`) for environment snippets.

谷歌分析

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

建议: 如果您的应用程序中已经包含了 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，请在页面文件中包含该组件：

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

请参阅 Google Analytics开发者文档以了解更多关于事件参数的信息。

跟踪页面访问量

Google Analytics 会在浏览器历史状态更改时自动跟踪页面浏览量。这意味着在 Next.js 路由之间进行客户端导航时，无需任何配置即可发送页面浏览数据。

要确保正确测量客户端导航，请在管理面板中验证 “Enhanced Measurement”性已启用，并选中 “Page changes based on browser history events” 复选框。

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

选项

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

Name	Type	Description
`gaId`	Required	Your measurement ID. Usually starts with `G-`.
`dataLayerName`	Optional	Name of the data layer. Defaults to `dataLayer`.

嵌入谷歌地图

GoogleMapsEmbed组件可用于将Google Maps Embed添加到您的页面中。默认情况下，它使用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"
    />
  );
}

选项

传递给 Google Maps Embed 的选项。有关选项的完整列表，请阅读Google Map Embed docs.

Name	Type	Description
`apiKey`	Required	Your api key.
`mode`	Required	Map mode
`height`	Optional	Height of the embed. Defaults to `auto`.
`width`	Optional	Width of the embed. Defaults to `auto`.
`style`	Optional	Pass styles to the iframe.
`allowfullscreen`	Optional	Property to allow certain map parts to go full screen.
`loading`	Optional	Defaults to lazy. Consider changing if you know your embed will be above the fold.
`q`	Optional	Defines map marker location. This may be required depending on the map mode.
`center`	Optional	Defines the center of the map view.
`zoom`	Optional	Sets initial zoom level of the map.
`maptype`	Optional	Defines type of map tiles to load.
`language`	Optional	Defines the language to use for UI elements and for the display of labels on map tiles.
`region`	Optional	Defines the appropriate borders and labels to display, based on geo-political sensitivities.

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

Options

Name	Type	Description
`videoid`	Required	YouTube video id.
`width`	Optional	Width of the video container. Defaults to `auto`
`height`	Optional	Height of the video container. Defaults to `auto`
`playlabel`	Optional	A visually hidden label for the play button for accessibility.
`params`	Optional	The video player params defined here. Params are passed as a query param string. Eg: `params="controls=0&start=10&end=30"`
`style`	Optional	Used to apply styles to the video container.

开始​

Google 第三方​

Google Tag Manager​

发送时间​

选项​

谷歌分析​

发送事件​

跟踪页面访问量​

选项​

嵌入谷歌地图​

选项​

YouTube 嵌入​

Options​

开始