From f2e968574d9d69caa35811b78c1f75b7ed03e5e9 Mon Sep 17 00:00:00 2001 From: Rune <93461506+newbie000652@users.noreply.github.com> Date: Sun, 17 Aug 2025 11:05:07 +0800 Subject: [PATCH 01/16] docs(cn): translate reference/react-dom/static/prerenderToNodeStream into Chinese --- .../react-dom/static/prerenderToNodeStream.md | 116 +++++++++--------- 1 file changed, 58 insertions(+), 58 deletions(-) diff --git a/src/content/reference/react-dom/static/prerenderToNodeStream.md b/src/content/reference/react-dom/static/prerenderToNodeStream.md index cc99c52d4e..564f786399 100644 --- a/src/content/reference/react-dom/static/prerenderToNodeStream.md +++ b/src/content/reference/react-dom/static/prerenderToNodeStream.md @@ -4,7 +4,7 @@ title: prerenderToNodeStream -`prerenderToNodeStream` renders a React tree to a static HTML string using a [Node.js Stream.](https://nodejs.org/api/stream.html). +`prerenderToNodeStream` 使用 [Node.js Stream.](https://nodejs.org/api/stream.html) 将 React 树渲染为静态 HTML 字符串。 ```js const {prelude} = await prerenderToNodeStream(reactNode, options?) @@ -16,17 +16,17 @@ const {prelude} = await prerenderToNodeStream(reactNode, options?) -This API is specific to Node.js. Environments with [Web Streams,](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API) like Deno and modern edge runtimes, should use [`prerender`](/reference/react-dom/static/prerender) instead. +此 API 针对 Node.js。具有 [Web Streams](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API) 的环境（例如 Deno 和现代 edge 运行时）应改用 [`prerender`](/reference/react-dom/static/prerender)。 --- -## Reference {/*reference*/} +## 参考 {/*reference*/} ### `prerenderToNodeStream(reactNode, options?)` {/*prerender*/} -Call `prerenderToNodeStream` to render your app to static HTML. +调用 `prerenderToNodeStream` 将应用渲染为静态 HTML。 ```js import { prerenderToNodeStream } from 'react-dom/static'; @@ -42,50 +42,50 @@ app.use('/', async (request, response) => { }); ``` -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*/} -* `reactNode`: A React node you want to render to HTML. For example, a JSX node 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 static generation 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) +在客户端，你的 bootstrap 脚本应通过调用 `hydrateRoot` 来[为整个 `document` 做 hydration：](/reference/react-dom/client/hydrateRoot#hydrating-an-entire-document) ```js [[1, 4, ""]] import { hydrateRoot } from 'react-dom/client'; @@ -142,15 +142,15 @@ import App from './App.js'; hydrateRoot(document, ); ``` -This will attach event listeners to the static 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. +构建后静态资源通常会被哈希，例如 `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: +如果你在构建后才能获取到最终资源名，就无法在源代码中硬编码这些路径。为此，根组件可以通过 prop 接收一个映射表来读取真实文件名： ```js {1,6} export default function App({ assetMap }) { @@ -166,7 +166,7 @@ export default function App({ assetMap }) { } ``` -On the server, render `` and pass your `assetMap` with the asset URLs: +在服务器端，渲染 `` 并传入 `assetMap`： ```js {1-5,8,9} // You'd need to get this JSON from your build tooling, e.g. read it from the build output. @@ -185,7 +185,7 @@ app.use('/', async (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` 渲染 ``，客户端也需要以相同方式渲染以避免 hydration 错误。你可以像下面这样将 `assetMap` 序列化并传给客户端： ```js {9-10} // You'd need to get this JSON from your build tooling. @@ -206,7 +206,7 @@ app.use('/', async (request, response) => { }); ``` -In the example above, the `bootstrapScriptContent` option adds an extra inline ` - - - - -``` - - - -部署时，你需要将 “development.js” 替换为 “production.min.js”！React 的 development 版本中内置了很多有用的错误信息，但同时也会降低你网站的访问速度。 - - - -### 步骤 3：创建一个 React 组件 {/*step-3-create-a-react-component*/} - -在 HTML 页面文件的同级目录下创建一个名为 **`like_button.js`** 的文件，并将如下代码片段添加到该文件中。这段代码定义了一个名为 LikeButton 的 React 组件。（在 [快速入门](/learn) 中，了解更多关于编写组件的信息。) - -```js -'use strict'; - -function LikeButton() { - const [liked, setLiked] = React.useState(false); - - if (liked) { - return 'You liked this!'; - } - - return React.createElement( - 'button', - { - onClick: () => setLiked(true), - }, - 'Like' - ); -} -``` - -### 步骤 4：把你的 React 组件添加到页面中 {/*step-4-add-your-react-component-to-the-page*/} - -最后，在 **`like_button.js`** 底部添加以下三行代码。这几行代码会找到我们在步骤 1 中添加到 HTML 里的 `
`，接着创建了一个React 的根，最后在其内部展示了我们的 React 组件 —— "Like" 按钮： - -```js -const rootNode = document.getElementById('like-button-root'); -const root = ReactDOM.createRoot(rootNode); -root.render(React.createElement(LikeButton)); -``` - -**恭喜！你刚刚已成功将第一个 React 组件添加到你的网站当中**！ - -- [查看完整的示例源码](https://gist.github.com/gaearon/0b535239e7f39c524f9c7dc77c44f09e) -- [下载完整示例（2KB 压缩包）](https://gist.github.com/gaearon/0b535239e7f39c524f9c7dc77c44f09e/archive/651935b26a48ac68b2de032d874526f2d0896848.zip) - -#### 复用你的组件 {/*you-can-reuse-components*/} - -你可能需要在同一 HTML 页面中的多个位置展示 React 组件。如果页面中由 React 驱动的部分相互独立，那复用就显得非常必要。你可以通过在你的 HTML 中放置多个根标签，然后用 `ReactDOM.createRoot()` 在每个根标签中渲染 React 组件来实现这一点。例如： - -1. 在 **`index.html`** 中，添加另外一个的容器元素 `
`。 -2. 在 **`like-button.js`** 文件最后，再添加以下三行代码： - -```js {6,7,8,9} -const anotherRootNode = document.getElementById('another-root'); -const anotherRoot = ReactDOM.createRoot(anotherRootNode); -anotherRoot.render(React.createElement(LikeButton)); -``` - -如果你需要在很多地方渲染同一个组件，你可以为每个根的指定一个 `class`，而不是 `id`，然后再把它们找出来。这是 [一个显示三个 "Like" 按钮，并向每个按钮内传递了数据的示例](https://gist.github.com/gaearon/779b12e05ffd5f51ffadd50b7ded5bc8)。 - -### 步骤 5：为生产环境压缩 JavaScript 代码 {/*step-5-minify-javascript-for-production*/} - -未经压缩的 JavaScript 可能会极大降低用户的访问速度。在将你的网站部署到生产环境之前，请务必对你的脚本文件进行压缩。 - -- **如果你不知道如何进行压缩**，[请参考该配置教程](https://gist.github.com/gaearon/ee0201910608f15df3f8cd66aa83f98e)。 -- 如果你已完成了 **对应用代码的压缩**，并且确保已部署的 HTML 加载的是以 `production.min.js` 结尾的 React 版本，那么你的网站就已完成生产部署（production-ready）： - -```html - - -``` - -## 尝试使用 JSX 编写 React {/*try-react-with-jsx*/} - -在上面的示例中，依靠的是浏览器原生就支持的特性。这也就是为什么我们在 **`like_button.js`** 中要调用 JavaScript 的函数，用以告知 React 要显示的内容： - -```js -return React.createElement('button', {onClick: () => setLiked(true)}, 'Like'); -``` - -然而，React 还提供了一种使用 [JSX](/learn/writing-markup-with-jsx) 编写界面的方式，一种类似 HTML 的 JavaScript 语法： - -```jsx -return ; -``` - -这两段代码是等价的。JSX 是一种在 JavaScript 中描述标签的语法。多数人觉得这样编写 UI 代码更方便 —— 无论是使用 React 还是其它库。 - -> 你可以通过 [在线转换器](https://babeljs.io/en/repl#?babili=false&browsers=&build=&builtIns=false&spec=false&loose=false&code_lz=DwIwrgLhD2B2AEcDCAbAlgYwNYF4DeAFAJTw4B88EAFmgM4B0tAphAMoQCGETBe86WJgBMAXJQBOYJvAC-RGWQBQ8FfAAyaQYuAB6cFDhkgA&debug=false&forceAllTransforms=false&shippedProposals=false&circleciRepo=&evaluate=false&fileSize=false&timeTravel=false&sourceType=module&lineWrap=true&presets=es2015%2Creact%2Cstage-2&prettier=false&targets=&version=7.17) 试用 JSX。 - -### 试用 JSX {/*try-jsx*/} - -试用 JSX 的最快方法是将 Babel 编译器作为 ` - - - - -``` - -现在你可以编辑 **`like-button.js`**，并将 - -```js -return React.createElement( - 'button', - { - onClick: () => setLiked(true), - }, - 'Like' -); -``` - -替换为等效的 JSX 代码： - -```jsx -return ( - -); -``` - -一开始，你可能会觉得将 JS 和标签混合在一起会有些奇怪，但后面你会慢慢爱上它的！欲了解更多，请参阅 [用 JSX 编写标签](/learn/writing-markup-with-jsx) 的介绍。这是 [一个使用了 JSX 的 HTML 文件示例](https://raw.githubusercontent.com/reactjs/reactjs.org/main/static/html/single-file-example.html)，你可以下载并尝试使用。 - - - -引入 Babel 的 `