Gatsby 服务器渲染 API

文件 gatsby-ssr.jsx/gatsby-ssr.tsx 允许您在 Gatsby 和 Node.js 进行服务器端渲染 (SSR) 时修改静态 HTML 文件的内容。要使用 Gatsby SSR API，请在您的站点根目录创建一个名为 gatsby-ssr.js 的文件。在此文件中导出您希望使用的任何 API。

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

API wrapPageElement 和 wrapRootElement 存在于 SSR 和浏览器 API 中。通常，您应该在 gatsby-ssr.js 和 gatsby-browser.js 中实现相同的组件，以便通过 Node.js SSR 生成的页面在浏览器中水合后保持一致。

用法

通过在项目根目录中创建一个名为 gatsby-ssr.jsx/gatsby-ssr.tsx 的文件来实施这些 API。

立即开始构建，在 Netlify!

API

`onPreRenderHTML` 函数
源码
1 2

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

在 Gatsby 服务器渲染 HTML 的每个页面之后调用，以便您可以替换在 html.js 中渲染的 head 组件。如果您需要重新排序其他插件添加的脚本或样式，这将非常有用。

参数

解构对象
- pathname string
  当前正在渲染的页面的路径名。
- getHeadComponents ReactNode[]
  返回当前的 headComponents 数组。
- replaceHeadComponents function
  将组件数组作为第一个参数，该数组将替换传递给 html.js 组件的 headComponents 数组。警告如果多个插件实现了此 API，最后一个插件将“获胜”。
- getPreBodyComponents ReactNode[]
  返回当前的 preBodyComponents 数组。
- replacePreBodyComponents function
  将组件数组作为第一个参数，该数组将替换传递给 html.js 组件的 preBodyComponents 数组。警告如果多个插件实现了此 API，最后一个插件将“获胜”。
- getPostBodyComponents ReactNode[]
  返回当前的 postBodyComponents 数组。
- replacePostBodyComponents function
  将组件数组作为第一个参数，该数组将替换传递给 html.js 组件的 postBodyComponents 数组。警告如果多个插件实现了此 API，最后一个插件将“获胜”。
pluginOptions object
包含在 gatsby-config.js 中定义的选项的对象。

示例

// Move Typography.js styles to the top of the head section so they're loaded first.
exports.onPreRenderHTML = ({ getHeadComponents, replaceHeadComponents }) => {
  const headComponents = getHeadComponents()
  headComponents.sort((x, y) => {
    if (x.key === 'TypographyStyle') {
      return -1
    } else if (y.key === 'TypographyStyle') {
      return 1
    }
    return 0
  })
  replaceHeadComponents(headComponents)
}

`onRenderBody` Function
源码
1 2

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

在 Gatsby 服务器渲染 HTML 的每个页面之后调用，以便您可以设置将在 html.js 中渲染的 head 和 body 组件。

Gatsby 对 HTML 进行两遍渲染。它首先遍历您的页面，仅渲染 body，然后将结果 body HTML 字符串作为 body 属性传递给您的 html.js 来完成渲染。

将自定义组件发送到您的 html.js 通常很有用。例如，支持服务器渲染的 React.js 库通常会将渲染期间生成的数据提取出来添加到您的 HTML 中，这是一种非常常见的模式。

使用此 API 而不是 replaceRenderer 是首选，因为多个插件可以实现此 API，而只有一个插件可以接管服务器渲染。但是，如果您的插件需要接管服务器渲染，那么就应该使用它。

参数

解构对象
- pathname string
  当前正在渲染的页面的路径名。
- setHeadComponents function
  将组件数组作为第一个参数，该数组将被添加到传递给 html.js 组件的 headComponents 数组中。
- setHtmlAttributes function
  接受一个属性对象，该对象将被扩展到 <html> 组件中。
- setBodyAttributes function
  接受一个属性对象，该对象将被扩展到 <body> 组件中。
- setPreBodyComponents function
  将组件数组作为第一个参数，该数组将被添加到传递给 html.js 组件的 preBodyComponents 数组中。
- setPostBodyComponents function
  将组件数组作为第一个参数，该数组将被添加到传递给 html.js 组件的 postBodyComponents 数组中。
- setBodyProps function
  接受一个数据对象，该对象将与其他 body 属性合并，并作为 bodyProps 传递给 html.js。
pluginOptions object
包含在 gatsby-config.js 中定义的选项的对象。

示例

// Import React so that you can use JSX in HeadComponents
const React = require("react")

const HtmlAttributes = {
  lang: "en"
}

const HeadComponents = [
  <script key="my-script" src="https://gatsby.dev/my-script" />
]

const BodyAttributes = {
  "data-theme": "dark"
}

exports.onRenderBody = ({
  setHeadComponents,
  setHtmlAttributes,
  setBodyAttributes
}, pluginOptions) => {
  setHtmlAttributes(HtmlAttributes)
  setHeadComponents(HeadComponents)
  setBodyAttributes(BodyAttributes)
}

`replaceRenderer` Function
源码

(apiCallbackContext: object, pluginOptions: pluginOptions) => void | Promise<void>

替换默认的服务器渲染器。这对于与 Redux、css-in-js 库等需要自定义服务器渲染设置的集成非常有用。

参数

解构对象
- pathname string
  当前正在渲染的页面的路径名。
- bodyComponent ReactNode
  将被渲染为页面 body 的 React 元素。
- replaceBodyHTMLString function
  使用您渲染的 HTML 字符串调用此函数。警告如果多个插件实现了此 API，最后一个插件将“获胜”。TODO：实施自动警告。
- setHeadComponents function
  将组件数组作为第一个参数，该数组将被添加到传递给 html.js 组件的 headComponents 数组中。
- setHtmlAttributes function
  接受一个属性对象，该对象将被扩展到 <html> 组件中。
- setBodyAttributes function
  接受一个属性对象，该对象将被扩展到 <body> 组件中。
- setPreBodyComponents function
  将组件数组作为第一个参数，该数组将被添加到传递给 html.js 组件的 preBodyComponents 数组中。
- setPostBodyComponents function
  将组件数组作为第一个参数，该数组将被添加到传递给 html.js 组件的 postBodyComponents 数组中。
- setBodyProps function
  接受一个数据对象，该对象将与其他 body 属性合并，并作为 bodyProps 传递给 html.js。
pluginOptions object
包含在 gatsby-config.js 中定义的选项的对象。

返回值

void | Promise<void>

示例

// From gatsby-plugin-glamor
const { renderToString } = require("react-dom/server")
const inline = require("glamor-inline")

exports.replaceRenderer = ({ bodyComponent, replaceBodyHTMLString }) => {
  const bodyHTML = renderToString(bodyComponent)
  const inlinedHTML = inline(bodyHTML)

  replaceBodyHTMLString(inlinedHTML)
}

`wrapPageElement` Function
源码

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

允许插件包装页面元素。

这对于在页面之间不会被卸载的页面周围设置包装器组件很有用。要设置上下文提供者，请使用 wrapRootElement。

注意： Gatsby 的 Browser API 中有一个等效的 hook。建议同时使用这两个 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>
}

`wrapRootElement` Function
源码
1 2

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

允许插件包装根元素。

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

注意： Gatsby 的 Browser API 中有一个等效的 hook。建议同时使用这两个 API。有关示例用法，请参阅使用 redux。

参数

解构对象
- pathname string
  当前正在渲染的页面的路径名。
- 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 上编辑此页面

Gatsby 服务器渲染 API

用法

API

参数

解构对象

pathname string

getHeadComponents ReactNode[]

replaceHeadComponents function

getPreBodyComponents ReactNode[]

replacePreBodyComponents function

getPostBodyComponents ReactNode[]

replacePostBodyComponents function

pluginOptions object

示例

onRenderBody Function源码12

参数

解构对象

pathname string

setHeadComponents function

setHtmlAttributes function

setBodyAttributes function

setPreBodyComponents function

setPostBodyComponents function

setBodyProps function

pluginOptions object

示例

参数

解构对象

pathname string

bodyComponent ReactNode

replaceBodyHTMLString function

setHeadComponents function

setHtmlAttributes function

setBodyAttributes function

setPreBodyComponents function

setPostBodyComponents function

setBodyProps function

pluginOptions object

返回值

void | Promise<void>

示例

wrapPageElement Function源码

参数

解构对象

element ReactNode

props object

pluginOptions object

返回值

ReactNode

示例

wrapRootElement Function源码12

参数

解构对象

pathname string

element ReactNode

pluginOptions object

返回值

ReactNode

示例

`pathname` string

`getHeadComponents` ReactNode[]

`replaceHeadComponents` function

`getPreBodyComponents` ReactNode[]

`replacePreBodyComponents` function

`getPostBodyComponents` ReactNode[]

`replacePostBodyComponents` function

`pluginOptions` object

`onRenderBody` Function
源码
1 2

`pathname` string

`setHeadComponents` function

`setHtmlAttributes` function

`setBodyAttributes` function

`setPreBodyComponents` function

`setPostBodyComponents` function

`setBodyProps` function

`pluginOptions` object

`pathname` string

`bodyComponent` ReactNode

`replaceBodyHTMLString` function

`setHeadComponents` function

`setHtmlAttributes` function

`setBodyAttributes` function

`setPreBodyComponents` function

`setPostBodyComponents` function

`setBodyProps` function

`pluginOptions` object

`wrapPageElement` Function
源码

`element` ReactNode

`props` object

`pluginOptions` object

`wrapRootElement` Function
源码
1 2

`pathname` string

`element` ReactNode

`pluginOptions` object