Menu

第三方库

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

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

入门

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

Terminal
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：

app/layout.tsx
TypeScript
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 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" })}
      >
        发送事件
      </button>
    </div>
  );
}

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

服务器端标记

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

选项

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

名称类型描述
gtmId必填你的 GTM 容器 ID。通常以 GTM- 开头。
gtmScriptUrl可选GTM 脚本 URL。默认为 https://www.googletagmanager.com/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
TypeScript
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" })}
      >
        发送事件
      </button>
    </div>
  );
}

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

跟踪页面浏览量

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

要确保客户端导航被正确测量，请在你的管理面板中验证 "增强型测量" 属性已启用，并且选中了 "基于浏览器历史事件的页面变化" 复选框。

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

选项

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

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

Google Maps 嵌入

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

名称类型描述
apiKey必填你的 API 密钥。
mode必填地图模式
height可选嵌入的高度。默认为 auto。
width可选嵌入的宽度。默认为 auto。
style可选传递给 iframe 的样式。
allowfullscreen可选允许某些地图部分全屏显示的属性。
loading可选默认为 lazy。如果你知道嵌入将在折叠上方，请考虑更改。
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可选用于应用到视频容器的样式。