陷阱

renderToString 不支持流式传输或等待数据。 查看替代方案。

renderToString 将 React 树渲染为 HTML 字符串。

const html = renderToString(reactNode, options?)

参考

renderToString(reactNode, options?)

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

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

const html = renderToString(<App />);

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

请参见下面的更多示例。

参数

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

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

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

返回值

一个HTML字符串。

注意事项

  • renderToString 对Suspense的支持有限。如果组件挂起，renderToString 会立即发送其回退内容作为HTML。

  • renderToString 可以在浏览器中运行，但在客户端代码中使用它并不推荐。

用法

将React树渲染为HTML字符串

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

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，并使其具有交互性。

陷阱

renderToString 不支持流式传输或等待数据。 查看替代方案。

替代方案

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

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

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

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

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

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

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

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

从客户端代码中移除renderToString

有时，renderToString 用于客户端将某些组件转换为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。

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。

疑难解答

当组件挂起时，HTML 始终包含一个回退

renderToString 不完全支持 Suspense。

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

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

上一页renderToStaticMarkup
下一页静态API