如何优化第三方库

@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 标签管理器，直接在自定义 _app 中包含该组件并传入您的 GTM 容器 ID：

pages/_app.js

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

export default function MyApp({ Component, pageProps }) {
  return (
    <>
      <Component {...pageProps} />
      <GoogleTagManager gtmId="GTM-XYZ" />
    </>
  )
}

要为单个路由加载 Google 标签管理器，在页面文件中包含该组件：

pages/index.js

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

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

发送事件

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

pages/index.js

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

export function EventButton() {
  return (
    <div>
      <button
        onClick={() => sendGTMEvent({ event: 'buttonClicked', value: 'xyz' })}
      >
        发送事件
      </button>
    </div>
  )
}

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

服务器端标签

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

选项

传递给 Google 标签管理器的选项。完整选项列表请参阅 Google 标签管理器文档。

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

Google 分析

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

推荐：如果您的应用中已经包含 Google 标签管理器，可以直接使用它配置 Google Analytics，而不需要单独包含 Google Analytics 组件。参考文档了解标签管理器和 gtag.js 之间的区别。

要为所有路由加载 Google Analytics，直接在自定义 _app 中包含该组件并传入您的测量 ID：

pages/_app.js

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

export default function MyApp({ Component, pageProps }) {
  return (
    <>
      <Component {...pageProps} />
      <GoogleAnalytics gaId="G-XYZ" />
    </>
  )
}

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

pages/index.js

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

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

发送事件

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

pages/index.js

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 地图嵌入

GoogleMapsEmbed 组件可用于在页面中添加 Google 地图嵌入。默认情况下，它使用 loading 属性在首屏下方延迟加载嵌入。

pages/index.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 实现更快的加载速度。

pages/index.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`	可选	用于为视频容器应用样式。

On this page