useServerInsertedHTML
useServerInsertedHTML hook 的 API 参考。
useServerInsertedHTML hook 允许 Client Component 从树中的任意位置向 Next.js 生成的 HTML 文档中注入标记。它仅在 App Router 中有效,如果在 Pages Router 中调用则不起作用。
你返回的节点会与页面分开渲染,并在 Next.js 生成 HTML 时插入其中。该 hook 是为 CSS-in-JS 样式注册表而设计的,这类注册表会收集渲染过程中产生的规则,并在使用这些规则的标记之前将它们刷新到文档中。
'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>
}'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 库。
参数#
useServerInsertedHTML(callback: () => React.ReactNode)| 参数 | 类型 | 描述 |
|---|---|---|
callback | () => React.ReactNode | 返回要插入到生成的 HTML 文档中的节点。 |
返回值#
该 hook 不返回值。
行为#
每次刷新时回调都会运行一次#
Next.js 会在你的树挂起和解析时分块刷新文档,每个已注册的回调都会在每次刷新时运行,而不是每次渲染只运行一次。因此,单个组件的回调可能会被调用多次,请保持它没有副作用。
每当 Next.js 生成 HTML 文档时,无论是在直接导航期间还是任何预渲染期间,回调都会运行。
在 <head> 发送之前插入的内容会进入 <head>。之后插入的内容会进入 <body>。在此示例中,Header 和 Feed 使用 CSS-in-JS 库设置样式,因此注册表会在它们渲染时收集其 CSS 规则。
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 策略下,浏览器会阻止该脚本。