renderToString

const html = renderToString(reactNode, options?)

• 参考
  • renderToString(reactNode, options?)
• 用法
  • 将 React 树作为 HTML 渲染为字符串
• 备选方案
  • 从 renderToString 迁移到服务器上的流式渲染
  • 从 renderToString 迁移到服务器上的静态预渲染
  • 从客户端代码中删除 renderToString
• 故障排除
  • 当一个组件挂起时，HTML 总是包含一个回退

参考

¥Reference

renderToString(reactNode, options?)

在服务器上，调用 renderToString 将你的应用渲染为 HTML。

¥On the server, call renderToString to render your app to HTML.

import { renderToString } from 'react-dom/server';

const html = renderToString(<App />);

在客户端，调用 hydrateRoot 使服务器生成的 HTML 具有交互性。

¥On the client, call hydrateRoot to make the server-generated HTML interactive.

请参阅下面的更多示例。

¥See more examples below.

参数

¥Parameters

• reactNode：要渲染为 HTML 的 React 节点。例如，像 <App /> 这样的 JSX 节点。

  ¥reactNode: A React node you want to render to HTML. For example, a JSX node like <App />.

• 可选 options：用于服务器渲染的对象。

  ¥optional options: An object for server render.

  • 可选 identifierPrefix：React 用于 useId。 生成的 ID 的字符串前缀 有助于避免在同一页面上使用多个根时发生冲突。必须与传递给 hydrateRoot。 的前缀相同

    ¥optional identifierPrefix: A string prefix React uses for IDs generated by useId. Useful to avoid conflicts when using multiple roots on the same page. Must be the same prefix as passed to hydrateRoot.

返回

¥Returns

一个 HTML 字符串。

¥An HTML string.

注意事项

¥Caveats

• renderToString 对 Suspense 的支持有限。如果组件挂起，renderToString 会立即以 HTML 格式发送其回退。

  ¥renderToString has limited Suspense support. If a component suspends, renderToString immediately sends its fallback as HTML.

• renderToString 在浏览器中有效，但在客户端代码中使用是 不建议。

  ¥renderToString works in the browser, but using it in the client code is not recommended.

用法

¥Usage

将 React 树作为 HTML 渲染为字符串

¥Rendering a React tree as HTML to a string

调用 renderToString 将你的应用渲染为 HTML 字符串，你可以将其与服务器响应一起发送：

¥Call renderToString to render your app to an HTML string which you can send with your server response:

import { renderToString } from 'react-dom/server';

// The route handler syntax depends on your backend framework
app.use('/', (request, response) => {
  const html = renderToString(<App />);
  response.send(html);
});

这将生成 React 组件的初始非交互式 HTML 输出。在客户端，你将需要调用 hydrateRoot 来混合服务器生成的 HTML 并使其具有交互性。

¥This will produce the initial non-interactive HTML output of your React components. On the client, you will need to call hydrateRoot to hydrate that server-generated HTML and make it interactive.

备选方案

¥Alternatives

从 renderToString 迁移到服务器上的流式渲染

¥Migrating from renderToString to a streaming render on the server

renderToString 立即返回一个字符串，因此它不支持在加载时流式传输内容。

¥renderToString returns a string immediately, so it does not support streaming content as it loads.

如果可能，我们建议使用这些功能齐全的替代方案：

¥When possible, we recommend using these fully-featured alternatives:

• 如果你使用 Node.js，请使用 renderToPipeableStream。

  ¥If you use Node.js, use renderToPipeableStream.

• 如果你将 Deno 或现代 Edge 运行时与 网络流 一起使用，请使用 renderToReadableStream。

  ¥If you use Deno or a modern edge runtime with Web Streams, use renderToReadableStream.

如果你的服务器环境不支持流，你可以继续使用 renderToString。

¥You can continue using renderToString if your server environment does not support streams.

从 renderToString 迁移到服务器上的静态预渲染

¥Migrating from renderToString to a static prerender on the server

renderToString 立即返回一个字符串，因此它不支持等待数据加载以生成静态 HTML。

¥renderToString returns a string immediately, so it does not support waiting for data to load for static HTML generation.

我们建议使用这些功能齐全的替代方案：

¥We recommend using these fully-featured alternatives:

• 如果你使用 Node.js，请使用 prerenderToNodeStream。

  ¥If you use Node.js, use prerenderToNodeStream.

• 如果你将 Deno 或现代 Edge 运行时与 网络流 一起使用，请使用 prerender。

  ¥If you use Deno or a modern edge runtime with Web Streams, use prerender.

如果你的静态站点生成环境不支持流，你可以继续使用 renderToString。

¥You can continue using renderToString if your static site generation environment does not support streams.

从客户端代码中删除 renderToString

¥Removing renderToString from the client code

有时，renderToString 用于在客户端将某些组件转换为 HTML。

¥Sometimes, renderToString is used on the client to convert some component to HTML.

// 🚩 Unnecessary: using renderToString on the client
import { renderToString } from 'react-dom/server';

const html = renderToString(<MyIcon />);
console.log(html); // For example, "<svg>...</svg>"

在客户端上导入 react-dom/server 会不必要地增加包的大小，应该避免。如果你需要在浏览器中将某些组件渲染为 HTML，请使用 createRoot 并从 DOM 中读取 HTML：

¥Importing react-dom/server on the client unnecessarily increases your bundle size and should be avoided. If you need to render some component to HTML in the browser, use createRoot and read HTML from the DOM:

import { createRoot } from 'react-dom/client';
import { flushSync } from 'react-dom';

const div = document.createElement('div');
const root = createRoot(div);
flushSync(() => {
  root.render(<MyIcon />);
});
console.log(div.innerHTML); // For example, "<svg>...</svg>"

flushSync 调用是必要的，以便在读取其 innerHTML 属性之前更新 DOM。

¥The flushSync call is necessary so that the DOM is updated before reading its innerHTML property.

故障排除

¥Troubleshooting

当一个组件挂起时，HTML 总是包含一个回退

¥When a component suspends, the HTML always contains a fallback

renderToString 不完全支持 Suspense。

¥renderToString does not fully support Suspense.

如果某些组件挂起（例如，因为它是用 lazy 定义的或获取数据），renderToString 将不会等待其内容解析。而是，renderToString 将在其上方找到最近的 <Suspense> 边界，并在 HTML 中渲染其 fallback 属性。在客户端代码加载之前，内容不会出现。

¥If some component suspends (for example, because it’s defined with lazy or fetches data), renderToString will not wait for its content to resolve. Instead, renderToString will find the closest <Suspense> boundary above it and render its fallback prop in the HTML. The content will not appear until the client code loads.

要解决这个问题，请使用 推荐的流式解决方案。 之一进行服务器端渲染，它们可以在服务器上解析内容时分块传输内容，以便用户在客户端代码加载之前看到页面逐渐填充。对于静态站点生成，他们可以等待所有内容解析后再生成静态 HTML。

¥To solve this, use one of the recommended streaming solutions. For server side rendering, they can stream content in chunks as it resolves on the server so that the user sees the page being progressively filled in before the client code loads. For static site generation, they can wait for all the content to resolve before generating the static HTML.