立即迁移到 Netlify

Netlify 宣布 Gatsby Cloud 的下一次迭代。 了解更多

Gatsby 浏览器 API

简介

文件 gatsby-browser.jsx/gatsby-browser.tsx 允许你在浏览器中响应 Gatsby 特定的事件,并用额外的全局组件包装你的页面组件。Gatsby 浏览器 API 提供了许多与 Gatsby 的 客户端 交互的选项。

你可以使用 JavaScript 或 TypeScript 来编写文件。

用法

要使用浏览器 API,请在站点的根目录下创建一个名为 gatsby-browser.jsx/gatsby-browser.tsx 的文件。从该文件中导出你想要使用的每个 API。

注意:API wrapPageElementwrapRootElement 同时存在于浏览器端和 服务端渲染 (SSR) API 中。你通常应该在 gatsby-ssr.jsgatsby-browser.js 中实现相同的组件,以便通过 SSR 生成的页面在浏览器中 水合 后保持一致。

立即开始构建,在 Netlify!

API

disableCorePrefetching 函数

(_: emptyArg, pluginOptions: pluginOptions) => boolean

插件可以接管预取逻辑。如果它们这样做,应该调用此函数来禁用现在重复的核心预取逻辑。

参数

  • _ undefined

    此参数为空。这是为了保持一致性,以便 pluginOptions 始终是第二个参数。

  • pluginOptions object

    包含在 gatsby-config.js 中定义的选项的对象

返回值

boolean

应该禁用核心预取

示例

exports.disableCorePrefetching = () => true

onClientEntry Function
源码
12

(_: emptyArg, pluginOptions: pluginOptions) => undefined

当 Gatsby 浏览器运行时首次启动时调用。

参数

  • _ undefined

    此参数为空。这是为了保持一致性,以便 pluginOptions 始终是第二个参数。

  • pluginOptions object

    包含在 gatsby-config.js 中定义的选项的对象

示例

exports.onClientEntry = () => {
  console.log("We've started!")
  callAnalyticsAPI()
}

源码

(_: emptyArg, pluginOptions: pluginOptions) => undefined

当 Gatsby 应用的初始(但非后续)渲染在客户端完成时调用。

参数

  • _ undefined

    此参数为空。这是为了保持一致性,以便 pluginOptions 始终是第二个参数。

  • pluginOptions object

    包含在 gatsby-config.js 中定义的选项的对象

示例

exports.onInitialClientRender = () => {
  console.log("ReactDOM.render has executed")
}

(apiCallbackContext: object, pluginOptions: pluginOptions) => undefined

在某个路径名的预取成功后调用。允许具有自定义预取逻辑的插件。

参数

  • 解构对象
    • pathname string

      资源已被预取的路径名

  • pluginOptions object

    包含在 gatsby-config.js 中定义的选项的对象


源码

(apiCallbackContext: object, pluginOptions: pluginOptions) => undefined

在开始更改位置时调用。

参数

  • 解构对象
    • location object

      一个位置对象

    • prevLocation object | null

      前一个位置对象

  • pluginOptions object

    包含在 gatsby-config.js 中定义的选项的对象

示例

exports.onPreRouteUpdate = ({ location, prevLocation }) => {
  console.log("Gatsby started to change location to", location.pathname)
  console.log("Gatsby started to change location from", prevLocation ? prevLocation.pathname : null)
}

(apiCallbackContext: object, pluginOptions: pluginOptions) => undefined

在触发某个路径名的预取时调用。允许具有自定义预取逻辑的插件。

参数

  • 解构对象
    • pathname string

      应该预取其资源的路径名

    • loadPage function

      用于获取与路径名相关的资源的函数

  • pluginOptions object

    包含在 gatsby-config.js 中定义的选项的对象


onRouteUpdate Function
源码

(apiCallbackContext: object, pluginOptions: pluginOptions) => undefined

在用户更改路由时调用,包括应用程序的初始加载。

参数

  • 解构对象
    • location object

      一个位置对象

    • prevLocation object | null

      前一个位置对象

  • pluginOptions object

    包含在 gatsby-config.js 中定义的选项的对象

示例

exports.onRouteUpdate = ({ location, prevLocation }) => {
  console.log('new pathname', location.pathname)
  console.log('old pathname', prevLocation ? prevLocation.pathname : null)
}

源码

(apiCallbackContext: object, pluginOptions: pluginOptions) => undefined

当更改位置持续时间超过 1 秒时调用。

参数

  • 解构对象
    • location object

      一个位置对象

    • action object

      导致路由更改的“操作”

  • pluginOptions object

    包含在 gatsby-config.js 中定义的选项的对象

示例

exports.onRouteUpdateDelayed = () => {
  console.log("We can show loading indicator now")
}

源码

(apiCallbackContext: object, pluginOptions: pluginOptions) => undefined

当服务工作线程变为活动状态时通知插件。

参数

  • 解构对象
    • serviceWorker object

      服务工作线程实例。

  • pluginOptions object

    包含在 gatsby-config.js 中定义的选项的对象


源码

(apiCallbackContext: object, pluginOptions: pluginOptions) => undefined

在服务工作线程已安装时通知插件。

参数

  • 解构对象
    • serviceWorker object

      服务工作线程实例。

  • pluginOptions object

    包含在 gatsby-config.js 中定义的选项的对象


源码

(apiCallbackContext: object, pluginOptions: pluginOptions) => undefined

在服务工作线程冗余时通知插件。

参数

  • 解构对象
    • serviceWorker object

      服务工作线程实例。

  • pluginOptions object

    包含在 gatsby-config.js 中定义的选项的对象


源码

(apiCallbackContext: object, pluginOptions: pluginOptions) => undefined

当服务工作线程有可用更新时通知插件。

参数

  • 解构对象
    • serviceWorker object

      服务工作线程实例。

  • pluginOptions object

    包含在 gatsby-config.js 中定义的选项的对象


源码

(apiCallbackContext: object, pluginOptions: pluginOptions) => undefined

当服务工作线程已在后台更新并且页面已准备好重新加载以应用更改时通知插件。

参数

  • 解构对象
    • serviceWorker object

      服务工作线程实例。

  • pluginOptions object

    包含在 gatsby-config.js 中定义的选项的对象


源码

(_: emptyArg, pluginOptions: pluginOptions) => boolean

允许插件注册服务工作线程。应该是一个返回 true 的函数。

参数

  • _ undefined

    此参数为空。这是为了保持一致性,以便 pluginOptions 始终是第二个参数。

  • pluginOptions object

    包含在 gatsby-config.js 中定义的选项的对象

返回值

boolean

Gatsby 是否应注册 /sw.js 服务工作线程

示例

exports.registerServiceWorker = () => true

源码

(_: emptyArg, pluginOptions: pluginOptions) => Function

允许插件用自定义渲染器替换 ReactDOM.createRoot/render 函数调用。

参数

  • _ undefined

    此参数为空。这是为了保持一致性,以便 pluginOptions 始终是第二个参数。

  • pluginOptions object

    包含在 gatsby-config.js 中定义的选项的对象

返回值

函数

此方法应返回一个与 ReactDOM.createRoot/render 签名相同的函数。

注意: 有关更多信息,请参阅 React 的 ReactDOM.createRoot/render 文档。请注意,ReactDOM.createRoot/render 仅在 React 18 或更高版本中可用,早期版本应使用 ReactDOM.render

示例

exports.replaceHydrateFunction = () => {
  return (element, container) => {
    const root = ReactDOM.createRoot(container)
    root.render(element)
  }
}

源码

(apiCallbackContext: object, pluginOptions: pluginOptions) => boolean | string | Array

允许插件影响导航时的滚动行为。默认行为是持久化最后已知的滚动位置,并在导航时滚动回它们。插件也可以覆盖此行为并返回坐标数组或要滚动到的元素名称。

参数

  • 解构对象
    • prevRouterProps object

      路由更改之前的路由器前一个状态。

    • routerProps object

      路由器的当前状态。

    • pathname string

      新的路径名(为了向 v1 向后兼容)。

    • getSavedScrollPosition function

      接受一个位置,并根据是否发生了滚动返回该位置的最后一个滚动位置的坐标,或者返回 null。Gatsby 将滚动位置保存在 SessionStorage 中,以便在页面重新加载后可用。

  • pluginOptions object

    包含在 gatsby-config.js 中定义的选项的对象

返回值

boolean | string | Array

应该返回一个[x, y] 坐标数组以滚动到,要滚动到的元素的 idname 字符串,false 表示不更新滚动位置,或者 true 表示默认行为。

示例

exports.shouldUpdateScroll = ({
  routerProps: { location },
  getSavedScrollPosition
}) => {
  const currentPosition = getSavedScrollPosition(location)
  const queriedPosition = getSavedScrollPosition({ pathname: `/random` })

  window.scrollTo(...(currentPosition || [0, 0]))

  return false
}

源码

(apiCallbackContext: object, pluginOptions: pluginOptions) => ReactNode

可用于包装每个页面元素。

这对于设置不会在页面更改时卸载的页面周围的包装器组件很有用。要设置上下文提供程序,请使用 wrapRootElement

注意: Gatsby 的 SSR API 中有一个等效的钩子。建议将这两个 API 一起使用。例如,请参阅 使用 i18n

参数

  • 解构对象
    • element ReactNode

      Gatsby 构建的“页面”React 元素。

    • props object

      页面使用的 props 对象。

  • pluginOptions object

    包含在 gatsby-config.js 中定义的选项的对象

返回值

ReactNode

包装后的元素

示例

const React = require("react")
const Layout = require("./src/components/layout").default

exports.wrapPageElement = ({ element, props }) => {
  // props provide same data to Layout as Page element will get
  // including location, data, etc - you don't need to pass it
  return <Layout {...props}>{element}</Layout>
}

源码

(apiCallbackContext: object, pluginOptions: pluginOptions) => ReactNode

可用于包装根元素。

这对于设置将包装您应用程序的任何上下文提供程序很有用。要设置页面周围的持久化 UI 元素,请使用 wrapPageElement

注意: Gatsby 的 SSR API 中有一个等效的钩子。建议将这两个 API 一起使用。例如,请参阅 使用 Redux

参数

  • 解构对象
    • element ReactNode

      Gatsby 构建的“根”React 元素。

  • pluginOptions object

    包含在 gatsby-config.js 中定义的选项的对象

返回值

ReactNode

包装后的元素

示例

const React = require("react")
const { Provider } = require("react-redux")

const createStore = require("./src/state/createStore")
const store = createStore()

exports.wrapRootElement = ({ element }) => {
  return (
    <Provider store={store}>
      {element}
    </Provider>
  )
}
在 GitHub 上编辑此页面
©2025Gatsby, Inc.