NNext.js 中文网 GitHub

useServerInsertedHTML

useServerInsertedHTML hook 的 API 参考。

useServerInsertedHTML hook 允许 Client Component 从树中的任意位置向 Next.js 生成的 HTML 文档中注入标记。它仅在 App Router 中有效,如果在 Pages Router 中调用则不起作用。

你返回的节点会与页面分开渲染,并在 Next.js 生成 HTML 时插入其中。该 hook 是为 CSS-in-JS 样式注册表而设计的,这类注册表会收集渲染过程中产生的规则,并在使用这些规则的标记之前将它们刷新到文档中。

app/registry.tsx
'use client'

import { useState } from 'react'
import { useServerInsertedHTML } from 'next/navigation'
import { StyleRegistry, createStyleRegistry } from 'styled-jsx'

export default function StyledJsxRegistry({
  children,
}: {
  children: React.ReactNode
}) {
  const [registry] = useState(() => createStyleRegistry())

  useServerInsertedHTML(() => {
    const styles = registry.styles()
    registry.flush()
    return <>{styles}</>
  })

  return <StyleRegistry registry={registry}>{children}</StyleRegistry>
}
app/registry.js
'use client'

import { useState } from 'react'
import { useServerInsertedHTML } from 'next/navigation'
import { StyleRegistry, createStyleRegistry } from 'styled-jsx'

export default function StyledJsxRegistry({ children }) {
  const [registry] = useState(() => createStyleRegistry())

  useServerInsertedHTML(() => {
    const styles = registry.styles()
    registry.flush()
    return <>{styles}</>
  })

  return <StyleRegistry registry={registry}>{children}</StyleRegistry>
}

有关完整设置(包括 styled-components),请参阅如何使用 CSS-in-JS 库。

参数#

tsx
useServerInsertedHTML(callback: () => React.ReactNode)
参数类型描述
callback() => React.ReactNode返回要插入到生成的 HTML 文档中的节点。

返回值#

该 hook 不返回值。

行为#

每次刷新时回调都会运行一次#

Next.js 会在你的树挂起和解析时分块刷新文档,每个已注册的回调都会在每次刷新时运行,而不是每次渲染只运行一次。因此,单个组件的回调可能会被调用多次,请保持它没有副作用。

每当 Next.js 生成 HTML 文档时,无论是在直接导航期间还是任何预渲染期间,回调都会运行。

在 <head> 发送之前插入的内容会进入 <head>。之后插入的内容会进入 <body>。在此示例中,Header 和 Feed 使用 CSS-in-JS 库设置样式,因此注册表会在它们渲染时收集其 CSS 规则。

app/page.tsx
import { Suspense } from 'react'
import { Header } from './header'
import { Feed } from './feed'

export default function Page() {
  return (
    <>
      
      <Header />
      <Suspense fallback={<p>Loading feed</p>}>
        
        <Feed />
      </Suspense>
    </>
  )
}

这假设 Header 之上的内容没有挂起。如果有内容挂起,Header 会在 head 关闭之后渲染,其 CSS 规则也会进入 <body>。

在上述样式注册表模式中,styled-jsx 会在你的树渲染时收集它找到的 CSS 规则。每次刷新时,回调返回迄今为止收集到的规则并清空注册表,这样下一次只携带此后新发现的规则。如果改为每次都返回相同的节点,文档中最终会每次刷新都出现一份副本。

样式注册表之所以有效,是因为 <style> 标签无论最终位于何处,都会作用于整个文档。

在客户端导航时,该 hook 不起作用。你的 CSS-in-JS 库会在浏览器中自行注入规则,因此样式仍会应用于转场后渲染的组件。

内联脚本优先使用其他方式#

建议首选在 React Server Components 中声明内联脚本,如防止 hydration 前的闪烁中所示。该 hook 适用于支撑树渲染的节点,例如 CSS-in-JS 注册表在渲染时收集的 <style> 标签。

只有当脚本上方没有任何内容挂起时,它才会被包含在 <head> 中,因此对树的更改可能会将其移入 <body> 而不会报错。

如果你使用该 hook,请用 useRef 标志对回调进行保护,使脚本只插入一次,而不是每次刷新都插入。无论是从 hook 返回的脚本还是写在 JSX 中的内联脚本,都不会在客户端导航时运行,因此两者只适合防止无样式内容闪烁或其他一次性副作用。对于写在 JSX 中的脚本,React 会在开发环境中记录警告,而该 hook 会静默跳过它。

Next.js 不会为你返回的脚本添加 nonce。在要求 nonce 的 script-src 策略下,浏览器会阻止该脚本。

Next.js 中文网