跳到主要内容

How to optimize third-party libraries

@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，请直接在自定义 _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 Tag Manager，请在页面文件中包含组件：

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

参考 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，请直接在自定义 _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 Maps Embed

GoogleMapsEmbed 组件可用于在页面中添加 Google Maps Embed。默认情况下，它使用 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 Maps Embed 的选项。有关完整选项列表，请阅读 Google Map Embed 文档。

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

YouTube Embed

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 | 可选 | 用于将样式应用到视频容器。 |

最后于 更新