Gatsby 浏览器 API
简介
文件 gatsby-browser.jsx/gatsby-browser.tsx 允许你在浏览器中响应 Gatsby 特定的事件,并用额外的全局组件包装你的页面组件。Gatsby 浏览器 API 提供了许多与 Gatsby 的 客户端 交互的选项。
你可以使用 JavaScript 或 TypeScript 来编写文件。
用法
要使用浏览器 API,请在站点的根目录下创建一个名为 gatsby-browser.jsx/gatsby-browser.tsx 的文件。从该文件中导出你想要使用的每个 API。
注意:API
wrapPageElement和wrapRootElement同时存在于浏览器端和 服务端渲染 (SSR) API 中。你通常应该在gatsby-ssr.js和gatsby-browser.js中实现相同的组件,以便通过 SSR 生成的页面在浏览器中 水合 后保持一致。
API
(_: emptyArg, pluginOptions: pluginOptions) => boolean
插件可以接管预取逻辑。如果它们这样做,应该调用此函数来禁用现在重复的核心预取逻辑。
参数
_undefined此参数为空。这是为了保持一致性,以便
pluginOptions始终是第二个参数。pluginOptionsobject包含在
gatsby-config.js中定义的选项的对象
返回值
boolean
应该禁用核心预取
示例
exports.disableCorePrefetching = () => trueonClientEntry Function
(_: emptyArg, pluginOptions: pluginOptions) => undefinedonClientEntry Function当 Gatsby 浏览器运行时首次启动时调用。
参数
_undefined此参数为空。这是为了保持一致性,以便
pluginOptions始终是第二个参数。pluginOptionsobject包含在
gatsby-config.js中定义的选项的对象
示例
exports.onClientEntry = () => {
console.log("We've started!")
callAnalyticsAPI()
}onInitialClientRender Function
(_: emptyArg, pluginOptions: pluginOptions) => undefinedonInitialClientRender Function当 Gatsby 应用的初始(但非后续)渲染在客户端完成时调用。
参数
_undefined此参数为空。这是为了保持一致性,以便
pluginOptions始终是第二个参数。pluginOptionsobject包含在
gatsby-config.js中定义的选项的对象
示例
exports.onInitialClientRender = () => {
console.log("ReactDOM.render has executed")
}onPostPrefetchPathname Function
(apiCallbackContext: object, pluginOptions: pluginOptions) => undefinedonPostPrefetchPathname Function在某个路径名的预取成功后调用。允许具有自定义预取逻辑的插件。
参数
- 解构对象
pathnamestring资源已被预取的路径名
pluginOptionsobject包含在
gatsby-config.js中定义的选项的对象
onPreRouteUpdate Function源码
(apiCallbackContext: object, pluginOptions: pluginOptions) => undefinedonPreRouteUpdate Function在开始更改位置时调用。
参数
- 解构对象
locationobject一个位置对象
prevLocationobject | null前一个位置对象
pluginOptionsobject包含在
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)
}onPrefetchPathname Function
(apiCallbackContext: object, pluginOptions: pluginOptions) => undefinedonPrefetchPathname Function在触发某个路径名的预取时调用。允许具有自定义预取逻辑的插件。
参数
- 解构对象
pathnamestring应该预取其资源的路径名
loadPagefunction用于获取与路径名相关的资源的函数
pluginOptionsobject包含在
gatsby-config.js中定义的选项的对象
onRouteUpdate Function源码
(apiCallbackContext: object, pluginOptions: pluginOptions) => undefinedonRouteUpdate Function在用户更改路由时调用,包括应用程序的初始加载。
参数
- 解构对象
locationobject一个位置对象
prevLocationobject | null前一个位置对象
pluginOptionsobject包含在
gatsby-config.js中定义的选项的对象
示例
exports.onRouteUpdate = ({ location, prevLocation }) => {
console.log('new pathname', location.pathname)
console.log('old pathname', prevLocation ? prevLocation.pathname : null)
}onRouteUpdateDelayed Function源码
(apiCallbackContext: object, pluginOptions: pluginOptions) => undefinedonRouteUpdateDelayed Function当更改位置持续时间超过 1 秒时调用。
参数
- 解构对象
locationobject一个位置对象
actionobject导致路由更改的“操作”
pluginOptionsobject包含在
gatsby-config.js中定义的选项的对象
示例
exports.onRouteUpdateDelayed = () => {
console.log("We can show loading indicator now")
}onServiceWorkerActive Function源码
(apiCallbackContext: object, pluginOptions: pluginOptions) => undefinedonServiceWorkerActive Function当服务工作线程变为活动状态时通知插件。
参数
- 解构对象
serviceWorkerobject服务工作线程实例。
pluginOptionsobject包含在
gatsby-config.js中定义的选项的对象
onServiceWorkerInstalled Function源码
(apiCallbackContext: object, pluginOptions: pluginOptions) => undefinedonServiceWorkerInstalled Function在服务工作线程已安装时通知插件。
参数
- 解构对象
serviceWorkerobject服务工作线程实例。
pluginOptionsobject包含在
gatsby-config.js中定义的选项的对象
onServiceWorkerRedundant Function源码
(apiCallbackContext: object, pluginOptions: pluginOptions) => undefinedonServiceWorkerRedundant Function在服务工作线程冗余时通知插件。
参数
- 解构对象
serviceWorkerobject服务工作线程实例。
pluginOptionsobject包含在
gatsby-config.js中定义的选项的对象
onServiceWorkerUpdateFound Function源码
(apiCallbackContext: object, pluginOptions: pluginOptions) => undefinedonServiceWorkerUpdateFound Function当服务工作线程有可用更新时通知插件。
参数
- 解构对象
serviceWorkerobject服务工作线程实例。
pluginOptionsobject包含在
gatsby-config.js中定义的选项的对象
onServiceWorkerUpdateReady Function源码
(apiCallbackContext: object, pluginOptions: pluginOptions) => undefinedonServiceWorkerUpdateReady Function当服务工作线程已在后台更新并且页面已准备好重新加载以应用更改时通知插件。
参数
- 解构对象
serviceWorkerobject服务工作线程实例。
pluginOptionsobject包含在
gatsby-config.js中定义的选项的对象
registerServiceWorker Function源码
(_: emptyArg, pluginOptions: pluginOptions) => booleanregisterServiceWorker Function允许插件注册服务工作线程。应该是一个返回 true 的函数。
参数
_undefined此参数为空。这是为了保持一致性,以便
pluginOptions始终是第二个参数。pluginOptionsobject包含在
gatsby-config.js中定义的选项的对象
返回值
boolean
Gatsby 是否应注册 /sw.js 服务工作线程
示例
exports.registerServiceWorker = () => truereplaceHydrateFunction Function
(_: emptyArg, pluginOptions: pluginOptions) => FunctionreplaceHydrateFunction Function允许插件用自定义渲染器替换 ReactDOM.createRoot/render 函数调用。
参数
_undefined此参数为空。这是为了保持一致性,以便
pluginOptions始终是第二个参数。pluginOptionsobject包含在
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)
}
}shouldUpdateScroll Function源码
(apiCallbackContext: object, pluginOptions: pluginOptions) => boolean | string | ArrayshouldUpdateScroll Function允许插件影响导航时的滚动行为。默认行为是持久化最后已知的滚动位置,并在导航时滚动回它们。插件也可以覆盖此行为并返回坐标数组或要滚动到的元素名称。
参数
- 解构对象
prevRouterPropsobject路由更改之前的路由器前一个状态。
routerPropsobject路由器的当前状态。
pathnamestring新的路径名(为了向 v1 向后兼容)。
getSavedScrollPositionfunction接受一个位置,并根据是否发生了滚动返回该位置的最后一个滚动位置的坐标,或者返回
null。Gatsby 将滚动位置保存在SessionStorage中,以便在页面重新加载后可用。
pluginOptionsobject包含在
gatsby-config.js中定义的选项的对象
返回值
boolean | string | Array
应该返回一个[x, y] 坐标数组以滚动到,要滚动到的元素的 id 或 name 字符串,false 表示不更新滚动位置,或者 true 表示默认行为。
示例
exports.shouldUpdateScroll = ({
routerProps: { location },
getSavedScrollPosition
}) => {
const currentPosition = getSavedScrollPosition(location)
const queriedPosition = getSavedScrollPosition({ pathname: `/random` })
window.scrollTo(...(currentPosition || [0, 0]))
return false
}wrapPageElement Function源码
(apiCallbackContext: object, pluginOptions: pluginOptions) => ReactNodewrapPageElement Function可用于包装每个页面元素。
这对于设置不会在页面更改时卸载的页面周围的包装器组件很有用。要设置上下文提供程序,请使用 wrapRootElement。
注意: Gatsby 的 SSR API 中有一个等效的钩子。建议将这两个 API 一起使用。例如,请参阅 使用 i18n。
参数
- 解构对象
elementReactNodeGatsby 构建的“页面”React 元素。
propsobject页面使用的 props 对象。
pluginOptionsobject包含在
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>
}wrapRootElement Function
(apiCallbackContext: object, pluginOptions: pluginOptions) => ReactNodewrapRootElement Function可用于包装根元素。
这对于设置将包装您应用程序的任何上下文提供程序很有用。要设置页面周围的持久化 UI 元素,请使用 wrapPageElement。
注意: Gatsby 的 SSR API 中有一个等效的钩子。建议将这两个 API 一起使用。例如,请参阅 使用 Redux。
参数
- 解构对象
elementReactNodeGatsby 构建的“根”React 元素。
pluginOptionsobject包含在
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>
)
}