resume 将预渲染的 React 树流式传输到 Web 可读流。
const stream = await resume(reactNode, postponedState, options?)
此 API 依赖于 Web 流。对于 Node.js,请改用 resumeToNodeStream。
参考 {/reference/}
resume(node, postponedState, options?) {/resume/}
调用 resume,将预渲染的 React 树继续渲染为 HTML,并写入 Web 可读流。
async function handler(request, writable) {
const postponed = await getPostponedState(request);
const resumeStream = await resume(<App />, postponed);
return resumeStream.pipeTo(writable)
}
参数 {/parameters/}
reactNode:调用prerender时传入的 React 节点。例如,像<App />这样的 JSX 元素。它应表示整个文档,因此App组件应渲染<html>标签。postponedState:从 prerender API 返回的不透明postpone对象,从你存储它的位置加载(例如 Redis、文件或 S3)。- 可选
options:包含流式传输选项的对象。
返回值 {/returns/}
resume 返回一个 Promise:
- 如果
resume成功生成了 shell,该 Promise 将解析为一个 Web 可读流,可以将其通过管道传输到 Web 可写流。 - 如果 shell 中发生错误,Promise 将因该错误而被拒绝。
返回的流还有一个额外属性:
allReady:一个在所有渲染完成后解析的 Promise。你可以在返回响应之前await stream.allReady,以供 爬虫和静态生成 使用。这样做不会有任何渐进式加载,流中将包含最终的 HTML。
注意事项 {/caveats/}
resume不接受bootstrapScripts、bootstrapScriptContent或bootstrapModules选项。相反,你需要将这些选项传递给生成postponedState的prerender调用。你也可以手动将引导内容注入可写流。resume不接受identifierPrefix,因为该前缀在prerender和resume中必须保持一致。- 由于不能向
prerender提供nonce,只有在没有向prerender提供脚本时,才应向resume提供nonce。 resume会从根节点重新渲染,直到找到一个未完全预渲染的组件。只有完全预渲染的组件(组件及其子组件都已完成预渲染)才会被完全跳过。
用法 {/usage/}
恢复预渲染 {/resuming-a-prerender/}
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>文档</title>
</head>
<body>
<iframe id="container"></iframe>
</body>
</html>
flushReadableStreamToFrame,
getUser,
Postponed,
sleep,
} from "./demo-helpers";
function Header() {
return <header>我和我的后代都可以被预渲染</header>;
}
const { promise: cookies, resolve: resolveCookies } = Promise.withResolvers();
function Main() {
const { sessionID } = use(cookies);
const user = getUser(sessionID);
useEffect(() => {
console.log("已达到交互状态!");
}, []);
return (
<main>
你好,{user.name}!
<button onClick={() => console.log("已完成 hydration!")}>
点击此按钮需要先完成 hydration。
</button>
</main>
);
}
function Shell({ children }) {
// 在真实应用中,你应在此处放置 html 和 body。
// 这里只是为了演示,使用可以包含在现有 body 中的标签。
return (
<html>
<body>{children}</body>
</html>
);
}
function App() {
return (
<Shell>
<Suspense fallback="正在加载页眉">
<Header />
</Suspense>
<Suspense fallback="正在加载主体">
<Main />
</Suspense>
</Shell>
);
}
async function main(frame) {
// 第 1 层
const controller = new AbortController();
const prerenderedApp = prerender(<App />, {
signal: controller.signal,
onError(error) {
if (error instanceof Postponed) {
} else {
console.error(error);
}
},
});
// 我们会立即在宏任务中止该过程。
// 任何无法同步获取或无法在微任务中获取的数据,都不会完成加载。
setTimeout(() => {
controller.abort(new Postponed());
});
const { prelude, postponed } = await prerenderedApp;
await flushReadableStreamToFrame(prelude, frame);
// 第 2 层
// 这里只是为了演示而等待。
// 在真实应用中,prelude 和 postponed 状态会在第 1 层序列化,并在这一层反序列化。
// 在 React 从预渲染中断处继续渲染的同时,prelude 内容可以立即作为普通 HTML 刷新。
// React 将从预渲染停止的地方继续渲染。
await sleep(2000);
// 你会从传入的 HTTP 请求中获取 cookie
resolveCookies({ sessionID: "abc" });
const stream = await resume(<App />, postponed);
await flushReadableStreamToFrame(stream, frame);
// 第 3 层
// 这里只是为了演示而等待。
await sleep(2000);
hydrateRoot(frame.contentWindow.document, <App />);
}
main(document.getElementById("container"));
const document = frame.contentWindow.document;
const decoder = new TextDecoder();
for await (const chunk of readable) {
const partialHTML = decoder.decode(chunk);
document.write(partialHTML);
}
}
// 这不一定要是一个错误。
// 你可以使用其他任何方式来判断预渲染期间的错误
// 是由有意中止导致的,还是实际错误。
// 这里只是硬编码一个会话。
return {
name: "Alice",
};
}
return new Promise((resolve) => {
setTimeout(() => {
resolve();
}, timeoutMS);
});
}
延伸阅读 {/further-reading/}
恢复过程的行为类似于 renderToReadableStream。有关更多示例,请参阅 renderToReadableStream 的用法部分。
prerender 的用法部分 包含专门介绍如何使用 prerender 的示例。
本文来自 React 文档中文译者及贡献者,按 CC BY 4.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。
