跳到内容
App Router（应用路由）指南第三方库

如何优化第三方库

@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 跟踪代码管理器

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 跟踪代码管理器的选项。有关完整选项列表，请阅读 Google 跟踪代码管理器文档。

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

Google Analytics（分析）

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

建议：如果您的应用程序中已经包含了 Google 跟踪代码管理器，您可以直接使用它配置 Google Analytics，而不是将 Google Analytics 作为单独的组件包含进来。请参阅 文档，了解有关跟踪代码管理器和 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可选用于将样式应用于视频容器。