diff --git a/src/content/reference/react-dom/server/renderToPipeableStream.md b/src/content/reference/react-dom/server/renderToPipeableStream.md index 8cfcda026c..9059427ed0 100644 --- a/src/content/reference/react-dom/server/renderToPipeableStream.md +++ b/src/content/reference/react-dom/server/renderToPipeableStream.md @@ -4,7 +4,7 @@ title: renderToPipeableStream -`renderToPipeableStream` renders a React tree to a pipeable [Node.js Stream.](https://nodejs.org/api/stream.html) +`renderToPipeableStream` 将一个 React 组件树渲染为管道化（pipeable）的 [Node.js 流](https://nodejs.org/api/stream.html)。 ```js const { pipe, abort } = renderToPipeableStream(reactNode, options?) @@ -16,17 +16,17 @@ const { pipe, abort } = renderToPipeableStream(reactNode, options?) -This API is specific to Node.js. Environments with [Web Streams,](https://developer.mozilla.org/zh-CN/docs/Web/API/Streams_API) like Deno and modern edge runtimes, should use [`renderToReadableStream`](/reference/react-dom/server/renderToReadableStream) instead. +这个 API 是专供 Node.js 使用的。像 Deno 这类可以支持 [Web 流](https://developer.mozilla.org/zh-CN/docs/Web/API/Streams_API) 的新式非主流运行时环境，应该使用另一个 API [`renderToReadableStream`](/reference/react-dom/server/renderToReadableStream)。 --- -## Reference {/*reference*/} +## 参考 {/*reference*/} ### `renderToPipeableStream(reactNode, options?)` {/*rendertopipeablestream*/} -Call `renderToPipeableStream` to render your React tree as HTML into a [Node.js Stream.](https://nodejs.org/api/stream.html#writable-streams) +调用 `renderToPipeableStream` 以 React 组件树渲染为 HTML 后注入 [Node.js 流](https://nodejs.org/api/stream.html#writable-streams)。 ```js import { renderToPipeableStream } from 'react-dom/server'; @@ -40,47 +40,47 @@ const { pipe } = renderToPipeableStream(, { }); ``` -On the client, call [`hydrateRoot`](/reference/react-dom/client/hydrateRoot) to make the server-generated HTML interactive. +在客户端，调用 [`hydrateRoot`](/reference/react-dom/client/hydrateRoot) 以让服务端生成的 HTML 中的绑定事件生效，进而让其变得可交互。 -[See more examples below.](#usage) +[参见下方更多示例](#usage)。 -#### Parameters {/*parameters*/} +#### 参数 {/*parameters*/} -* `reactNode`: A React node you want to render to HTML. For example, a JSX element like ``. It is expected to represent the entire document, so the `App` component should render the `` tag. +* `reactNode`：想要将其渲染为 HTML 的 React 节点，比如像 `` 这样的 JSX 元素。这样做意味着整个页面文档都将被渲染，所以这里提到的 `App` 组件将渲染 `` 标签. -* **optional** `options`: An object with streaming options. - * **optional** `bootstrapScriptContent`: If specified, this string will be placed in an inline ` ``` -On the client, your bootstrap script should [hydrate the entire `document` with a call to `hydrateRoot`:](/reference/react-dom/client/hydrateRoot#hydrating-an-entire-document) +在客户端，你的 script 将会 [通过调用 `hydrateRoot` 对整个 `页面文档` 进行 hydrate](/reference/react-dom/client/hydrateRoot#hydrating-an-entire-document)： ```js [[1, 4, ""]] import { hydrateRoot } from 'react-dom/client'; @@ -133,15 +133,15 @@ import App from './App.js'; hydrateRoot(document, ); ``` -This will attach event listeners to the server-generated HTML and make it interactive. +上述过程让客户端开始监听服务端生成的 HTML 中绑定的事件，然后这些事件才能真正在客户端生效。 -#### Reading CSS and JS asset paths from the build output {/*reading-css-and-js-asset-paths-from-the-build-output*/} +#### 从构建输出产物中读取 CSS 和 JS 资源路径 {/*reading-css-and-js-asset-paths-from-the-build-output*/} -The final asset URLs (like JavaScript and CSS files) are often hashed after the build. For example, instead of `styles.css` you might end up with `styles.123456.css`. Hashing static asset filenames guarantees that every distinct build of the same asset will have a different filename. This is useful because it lets you safely enable long-term caching for static assets: a file with a certain name would never change content. +在打包构建之后，最终的资源的 URL（比如 JavaScript 和 CSS 文件）总是被哈希映射处理过。举个例子，`styles.css` 最终可能会变成 `styles.123456.css`。被哈希处理过的资源文件名称能够保证同样的资源在每一次不同的构建后都有一个不一样的文件名。这是一个十分有用的机制，因为它让你能够安全地对静态资源进行长期缓存：如果名称固定不变，打包构建工具可能会认为这些资源没有改动，导致缓存的内容将不会发生相应的变化。 -However, if you don't know the asset URLs until after the build, there's no way for you to put them in the source code. For example, hardcoding `"/styles.css"` into JSX like earlier wouldn't work. To keep them out of your source code, your root component can read the real filenames from a map passed as a prop: +然而，如果在打包构建完成之前你都无法知晓资源最终的 URL 的话，那就无法将它们放进组件的代码之中。举个例子，像以前那样将 `"/styles.css"` 硬编码写入 JSX 的话，是不会有作用的。为了应对这种场景，可以向根组件传递一个映射文件名的 map 作为参数： ```js {1,6} export default function App({ assetMap }) { @@ -158,10 +158,10 @@ export default function App({ assetMap }) { } ``` -On the server, render `` and pass your `assetMap` with the asset URLs: +然后在服务端，像 `` 这样传递资源 URL： ```js {1-5,8,9} -// You'd need to get this JSON from your build tooling, e.g. read it from the build output. +// 你需要从你的打包构建工具中获取这个 JSON，比如从构建产物中获取 const assetMap = { 'styles.css': '/styles.123456.css', 'main.js': '/main.123456.js' @@ -178,10 +178,10 @@ app.use('/', (request, response) => { }); ``` -Since your server is now rendering ``, you need to render it with `assetMap` on the client too to avoid hydration errors. You can serialize and pass `assetMap` to the client like this: +因为你的服务端正在渲染 ``，所以你还需要在客户端将这个带有 `assetMap` 的组件再渲染一次进行同构，以此避免 hydrate 错误。你可以像下面这样序列化 `assetMap` 之后再传递： ```js {9-10} -// You'd need to get this JSON from your build tooling. +// 你需要从你的打包构建工具中获取这个 JSON。 const assetMap = { 'styles.css': '/styles.123456.css', 'main.js': '/main.123456.js' @@ -189,7 +189,7 @@ const assetMap = { app.use('/', (request, response) => { const { pipe } = renderToPipeableStream(, { - // Careful: It's safe to stringify() this because this data isn't user-generated. + // 注意: 由于这些数据并非用户生成，所以使用 stringify 是安全的。 bootstrapScriptContent: `window.assetMap = ${JSON.stringify(assetMap)};`, bootstrapScripts: [assetMap['main.js']], onShellReady() { @@ -200,7 +200,7 @@ app.use('/', (request, response) => { }); ``` -In the example above, the `bootstrapScriptContent` option adds an extra inline `