docs(en): merge reactjs.org/main into zh-hans.reactjs.org/main @ 69edd84

 (#1634)

src/components/Icon/IconRocket.tsx

@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ */
+
+import {memo} from 'react';
+
+export const IconRocket = memo<
+  JSX.IntrinsicElements['svg'] & {title?: string; size?: 's' | 'md'}
+>(function IconRocket({className, size = 'md'}) {
+  return (
+    <svg
+      className={className}
+      aria-hidden="true"
+      width={size === 's' ? '1.2em' : '1.5em'}
+      height={size === 's' ? '1.2em' : '1.5em'}
+      fill="currentColor"
+      version="1.1"
+      viewBox="0 0 1200 1200"
+      xmlns="http://www.w3.org/2000/svg">
+      <g fillRule="evenodd">
+        <path d="m911.8 288.2c65.051 65.051 65.051 170.6 0 235.65-65.051 65.051-170.6 65.051-235.65 0-65.051-65.051-65.051-170.6 0-235.65 65.051-65.051 170.6-65.051 235.65 0zm-53.051 53.051c-35.75-35.801-93.801-35.801-129.55 0-35.801 35.75-35.801 93.801 0 129.55 35.75 35.801 93.801 35.801 129.55 0 35.801-35.75 35.801-93.801 0-129.55z" />
+        <path d="m1122.2 103.4s96.648 328.1-194.4 619.1c-130.75 130.75-303.25 226.75-440.75 250.5-12.102 2.0508-24.449-1.8984-33.102-10.648l-231.55-234.8c-8.6484-8.8008-12.449-21.301-10.102-33.398 26.102-135.4 135.45-292.2 265.2-421.95 291-291.05 619.1-194.4 619.1-194.4 12.352 3.6016 22 13.25 25.602 25.602zm-67.5 41.898c-70.898-12.898-308.6-35.602-524.15 179.9-112.35 112.35-210.4 245.4-240.4 364.25 0 0 203.05 205.9 203.1 205.9 121.75-26.852 268.4-112.75 381.55-225.9 215.5-215.55 192.8-453.25 179.9-524.15z" />
+        <path d="m151.55 543.85 124 20.648c20.398 3.3984 34.25 22.75 30.801 43.148-3.3984 20.449-22.699 34.25-43.148 30.852l-144.35-24.051c-22.148-3.6992-40.699-18.949-48.602-40-7.9492-21.051-4.0508-44.699 10.199-62.148l122.85-150.15c15.051-18.398 36.898-30 60.551-32.148l179.55-16.301c20.602-1.8984 38.852 13.352 40.75 33.949 1.8516 20.602-13.352 38.852-33.949 40.75l-179.55 16.301c-3.6484 0.35156-7 2.1016-9.3008 4.9492z" />
+        <path d="m656.15 1048.4 134.2-109.8c2.8516-2.3008 4.6016-5.6484 4.9492-9.3008l16.301-179.55c1.8984-20.602 20.148-35.801 40.75-33.949 20.602 1.8984 35.852 20.148 33.949 40.75l-16.301 179.55c-2.1484 23.648-13.75 45.5-32.148 60.551l-150.15 122.85c-17.449 14.25-41.102 18.148-62.148 10.199-21.051-7.8984-36.301-26.449-40-48.602l-29.25-175.7c-3.3984-20.398 10.398-39.75 30.801-43.148 20.449-3.3984 39.75 10.449 43.148 30.852l25.898 155.3z" />
+        <path d="m310.9 560.4c-14.648-14.648-14.648-38.398 0-53.051 14.648-14.648 38.398-14.648 53.051 0l328.7 328.7c14.648 14.648 14.648 38.398 0 53.051-14.648 14.648-38.398 14.648-53.051 0z" />
+        <path d="m383.95 982.15c14.648-14.602 38.398-14.602 53.051 0 14.602 14.648 14.602 38.398 0 53.051l-91.352 91.301c-14.602 14.648-38.398 14.648-53 0-14.648-14.602-14.648-38.398 0-53z" />
+        <path d="m237.85 909.1c14.648-14.602 38.398-14.602 53.051 0 14.602 14.648 14.602 38.398 0 53.051l-127.85 127.85c-14.648 14.648-38.398 14.648-53.051 0-14.648-14.648-14.648-38.398 0-53.051z" />
+        <path d="m164.8 763c14.648-14.602 38.398-14.602 53.051 0 14.602 14.648 14.602 38.398 0 53.051l-91.352 91.301c-14.602 14.648-38.398 14.648-53 0-14.648-14.602-14.648-38.398 0-53z" />
+      </g>
+    </svg>
+  );
+});

src/components/Layout/Sidebar/SidebarLink.tsx

@@ -16,7 +16,7 @@ interface SidebarLinkProps {
   selected?: boolean;
   title: string;
   level: number;
-  canary?: boolean;
+  version?: 'canary' | 'major';
   icon?: React.ReactNode;
   isExpanded?: boolean;
   hideArrow?: boolean;
@@ -27,7 +27,7 @@ export function SidebarLink({
   href,
   selected = false,
   title,
-  canary,
+  version,
   level,
   isExpanded,
   hideArrow,
@@ -75,10 +75,17 @@ export function SidebarLink({
       {/* This here needs to be refactored ofc */}
       <div>
         {title}{' '}
-        {canary && (
+        {version === 'major' && (
+          <span
+            title="- This feature is available in React 19 beta and the React canary channel"
+            className={`text-xs px-1 ms-1 rounded bg-gray-10 dark:bg-gray-40 dark:bg-opacity-20 text-gray-40 dark:text-gray-40`}>
+            React 19
+          </span>
+        )}
+        {version === 'canary' && (
           <IconCanary
             title=" - This feature is available in the latest Canary"
-            className="ms-2 text-gray-30 dark:text-gray-60 inline-block w-4 h-4 align-[-3px]"
+            className="ms-1 text-gray-30 dark:text-gray-60 inline-block w-3.5 h-3.5 align-[-3px]"
           />
         )}
       </div>

src/components/Layout/Sidebar/SidebarRouteTree.tsx

@@ -87,7 +87,7 @@ export function SidebarRouteTree({
             path,
             title,
             routes,
-            canary,
+            version,
             heading,
             hasSectionHeader,
             sectionHeader,
@@ -121,7 +121,7 @@ export function SidebarRouteTree({
                   selected={selected}
                   level={level}
                   title={title}
-                  canary={canary}
+                  version={version}
                   isExpanded={isExpanded}
                   hideArrow={isForceExpanded}
                 />
@@ -145,7 +145,7 @@ export function SidebarRouteTree({
                   selected={selected}
                   level={level}
                   title={title}
-                  canary={canary}
+                  version={version}
                 />
               </li>
             );

src/components/Layout/getRouteMeta.tsx

@@ -19,8 +19,8 @@ export type RouteTag =
 export interface RouteItem {
   /** Page title (for the sidebar) */
   title: string;
-  /** Optional canary flag for heading */
-  canary?: boolean;
+  /** Optional version flag for heading */
+  version?: 'canary' | 'major';
   /** Optional page description for heading */
   description?: string;
   /* Additional meta info for page tagging */

src/components/MDX/ExpandableCallout.tsx

@@ -8,8 +8,16 @@ import {IconNote} from '../Icon/IconNote';
 import {IconWarning} from '../Icon/IconWarning';
 import {IconPitfall} from '../Icon/IconPitfall';
 import {IconCanary} from '../Icon/IconCanary';
+import {IconRocket} from '../Icon/IconRocket';
 
-type CalloutVariants = 'deprecated' | 'pitfall' | 'note' | 'wip' | 'canary';
+type CalloutVariants =
+  | 'deprecated'
+  | 'pitfall'
+  | 'note'
+  | 'wip'
+  | 'canary'
+  | 'major'
+  | 'rsc';
 
 interface ExpandableCalloutProps {
   children: React.ReactNode;
@@ -59,6 +67,22 @@ const variantMap = {
     overlayGradient:
       'linear-gradient(rgba(249, 247, 243, 0), rgba(249, 247, 243, 1)',
   },
+  major: {
+    title: 'React 19',
+    Icon: IconRocket,
+    containerClasses: 'bg-blue-10 dark:bg-blue-60 dark:bg-opacity-20',
+    textColor: 'text-blue-50 dark:text-blue-40',
+    overlayGradient:
+      'linear-gradient(rgba(249, 247, 243, 0), rgba(249, 247, 243, 1)',
+  },
+  rsc: {
+    title: 'React Server Components',
+    Icon: null,
+    containerClasses: 'bg-blue-10 dark:bg-blue-60 dark:bg-opacity-20',
+    textColor: 'text-blue-50 dark:text-blue-40',
+    overlayGradient:
+      'linear-gradient(rgba(249, 247, 243, 0), rgba(249, 247, 243, 1)',
+  },
 };
 
 function ExpandableCallout({children, type = 'note'}: ExpandableCalloutProps) {
@@ -72,9 +96,11 @@ function ExpandableCallout({children, type = 'note'}: ExpandableCalloutProps) {
         variant.containerClasses
       )}>
       <h3 className={cn('text-2xl font-display font-bold', variant.textColor)}>
-        <variant.Icon
-          className={cn('inline me-3 mb-1 text-lg', variant.textColor)}
-        />
+        {variant.Icon && (
+          <variant.Icon
+            className={cn('inline me-2 mb-1 text-lg', variant.textColor)}
+          />
+        )}
         {variant.title}
       </h3>
       <div className="relative">

src/components/MDX/MDXComponents.tsx

@@ -97,6 +97,14 @@ const Canary = ({children}: {children: React.ReactNode}) => (
   <ExpandableCallout type="canary">{children}</ExpandableCallout>
 );
 
+const NextMajor = ({children}: {children: React.ReactNode}) => (
+  <ExpandableCallout type="major">{children}</ExpandableCallout>
+);
+
+const RSC = ({children}: {children: React.ReactNode}) => (
+  <ExpandableCallout type="rsc">{children}</ExpandableCallout>
+);
+
 const CanaryBadge = ({title}: {title: string}) => (
   <span
     title={title}
@@ -111,6 +119,26 @@ const CanaryBadge = ({title}: {title: string}) => (
   </span>
 );
 
+const NextMajorBadge = ({title}: {title: string}) => (
+  <span
+    title={title}
+    className={
+      'text-base font-display px-2 py-0.5 font-bold bg-blue-10 dark:bg-blue-60 text-gray-60 dark:text-gray-10 rounded'
+    }>
+    React 19
+  </span>
+);
+
+const RSCBadge = ({title}: {title: string}) => (
+  <span
+    title={title}
+    className={
+      'text-base font-display px-2 py-0.5 font-bold bg-blue-10 dark:bg-blue-50 text-gray-60 dark:text-gray-10 rounded'
+    }>
+    RSC
+  </span>
+);
+
 const Blockquote = ({
   children,
   ...props
@@ -483,6 +511,10 @@ export const MDXComponents = {
   Note,
   Canary,
   CanaryBadge,
+  NextMajor,
+  NextMajorBadge,
+  RSC,
+  RSCBadge,
   PackageImport,
   ReadBlogPost,
   Recap,

src/components/MDX/Sandpack/template.ts

@@ -28,8 +28,8 @@ root.render(
           eject: 'react-scripts eject',
         },
         dependencies: {
-          react: '^18.0.0',
-          'react-dom': '^18.0.0',
+          react: '19.0.0-rc-3edc000d-20240926',
+          'react-dom': '19.0.0-rc-3edc000d-20240926',
           'react-scripts': '^5.0.0',
         },
       },

src/content/blog/2024/04/25/react-19-upgrade-guide.md

@@ -1,5 +1,5 @@
 ---
-title: "React 19 RC Upgrade Guide"
+title: "React 19 Upgrade Guide"
 author: Ricky Hanlon
 date: 2024/04/25
 description: The improvements added to React 19 require some breaking changes, but we've worked to make the upgrade as smooth as possible and we don't expect the changes to impact most apps. In this post, we will guide you through the steps for upgrading apps and libraries to React 19.
@@ -12,7 +12,7 @@ April 25, 2024 by [Ricky Hanlon](https://twitter.com/rickhanlonii)
 
 <Intro>
 
-The improvements added to React 19 RC require some breaking changes, but we've worked to make the upgrade as smooth as possible, and we don't expect the changes to impact most apps.
+The improvements added to React 19 require some breaking changes, but we've worked to make the upgrade as smooth as possible, and we don't expect the changes to impact most apps.
 
 </Intro>
 
@@ -38,7 +38,7 @@ In this post, we will guide you through the steps for upgrading to React 19:
 - [TypeScript changes](#typescript-changes)
 - [Changelog](#changelog)
 
-If you'd like to help us test React 19, follow the steps in this upgrade guide and [report any issues](https://github.com/facebook/react/issues/new?assignees=&labels=React+19&projects=&template=19.md&title=%5BReact+19%5D) you encounter. For a list of new features added to React 19, see the [React 19 release post](/blog/2024/04/25/react-19).
+If you'd like to help us test React 19, follow the steps in this upgrade guide and [report any issues](https://github.com/facebook/react/issues/new?assignees=&labels=React+19&projects=&template=19.md&title=%5BReact+19%5D) you encounter. For a list of new features added to React 19, see the [React 19 release post](/blog/2024/12/05/react-19).
 
 ---
 ## Installing {/*installing*/}
@@ -70,28 +70,23 @@ We expect most apps will not be affected since the transform is enabled in most
 To install the latest version of React and React DOM:
 
 ```bash
-npm install --save-exact react@rc react-dom@rc
+npm install --save-exact react@^19.0.0 react-dom@^19.0.0
 ```
 
 Or, if you're using Yarn:
 
 ```bash
-yarn add --exact react@rc react-dom@rc
+yarn add --exact react@^19.0.0 react-dom@^19.0.0
 ```
 
-If you're using TypeScript, you also need to update the types. Once React 19 is released as stable, you can install the types as usual from `@types/react` and `@types/react-dom`.  Until the stable release, the types are available in different packages which need to be enforced in your `package.json`:
+If you're using TypeScript, you also need to update the types.
+```bash
+npm install --save-exact @types/react@^19.0.0 @types/react-dom@^19.0.0
+```
 
-```json
-{
-  "dependencies": {
-    "@types/react": "npm:types-react@rc",
-    "@types/react-dom": "npm:types-react-dom@rc"
-  },
-  "overrides": {
-    "@types/react": "npm:types-react@rc",
-    "@types/react-dom": "npm:types-react-dom@rc"
-  }
-}
+Or, if you're using Yarn:
+```bash
+yarn add --exact @types/react@^19.0.0 @types/react-dom@^19.0.0
 ```
 
 We're also including a codemod for the most common replacements. See [TypeScript changes](#typescript-changes) below.
@@ -752,7 +747,7 @@ const reducer = (state: State, action: Action) => state;
 - **react-dom**: Remove layout effect warning during SSR [#26395](https://github.com/facebook/react/pull/26395)
 - **react-dom**: Warn and don’t set empty string for src/href (except anchor tags) [#28124](https://github.com/facebook/react/pull/28124)
 
-We'll publish the full changelog with the stable release of React 19.
+For a full list of changes, please see the [Changelog](https://github.com/facebook/react/blob/main/CHANGELOG.md#1900-december-5-2024).
 
 ---
 

src/content/blog/2024/05/22/react-conf-2024-recap.md

@@ -17,7 +17,7 @@ description: 上周我们在内华达州亨德森举办了为期两天的 React
 
 ---
 
-在 React Conf 2024 上，我们宣布了 [React 19 RC](/blog/2024/04/25/react-19)、[React Native 新架构 Beta 版](https://github.com/reactwg/react-native-new-architecture/discussions/189)，以及 [React Compiler](/learn/react-compiler) 的实验版本。社区同时登台宣布了 [React Router v7](https://remix.run/blog/merging-remix-and-react-router)、Expo Router 中的 [通用服务器组件](https://www.youtube.com/watch?v=T8TZQ6k4SLE&t=20765s)、[RedwoodJS](https://redwoodjs.com/blog/rsc-now-in-redwoodjs) 中的 React 服务器组件等等。
+在 React Conf 2024 上，我们宣布了 [React 19 RC](/blog/2024/12/05/react-19)、[React Native 新架构 Beta 版](https://github.com/reactwg/react-native-new-architecture/discussions/189)，以及 [React Compiler](/learn/react-compiler) 的实验版本。社区同时登台宣布了 [React Router v7](https://remix.run/blog/merging-remix-and-react-router)、Expo Router 中的 [通用服务器组件](https://www.youtube.com/watch?v=T8TZQ6k4SLE&t=20765s)、[RedwoodJS](https://redwoodjs.com/blog/rsc-now-in-redwoodjs) 中的 React 服务器组件等等。
 
 完整的 [第一天](https://www.youtube.com/watch?v=T8TZQ6k4SLE) 和 [第二天](https://www.youtube.com/watch?v=0ckOUBiuxVY) 的直播已经可以在线观看了。在这篇文章中，我们将总结活动中的演讲和公告。
 
@@ -36,7 +36,7 @@ _[点击这里观看第一天完整直播。](https://www.youtube.com/watch?v=T8
 - [RedwoodJS 现已支持 React 服务器组件](https://www.youtube.com/watch?v=T8TZQ6k4SLE&t=26815s)，来自 [Amy Dutton](https://twitter.com/selfteachme)
 - [介绍 Expo Router 中的通用 React 服务器组件](https://www.youtube.com/watch?v=T8TZQ6k4SLE&t=20765s)，来自 [Evan Bacon](https://twitter.com/Baconbrix)
 
-接下来的主题演讲中，[Josh Story](https://twitter.com/joshcstory) 和 [Andrew Clark](https://twitter.com/acdlite) 分享了 React 19 即将推出的新功能，并宣布了 React 19 RC，该版本已准备好用于生产环境测试。你可以在 [React 19 RC](/blog/2024/04/25/react-19) 这篇文章中查看 React 19 的全部功能，也可以查看以下关于新功能深入分析的演讲：
+接下来的主题演讲中，[Josh Story](https://twitter.com/joshcstory) 和 [Andrew Clark](https://twitter.com/acdlite) 分享了 React 19 即将推出的新功能，并宣布了 React 19 RC，该版本已准备好用于生产环境测试。你可以在 [React 19 RC](/blog/2024/12/05/react-19) 这篇文章中查看 React 19 的全部功能，也可以查看以下关于新功能深入分析的演讲：
 
 - [React 19 有哪些更新](https://www.youtube.com/watch?v=T8TZQ6k4SLE&t=8880s)，来自 [Lydia Hallie](https://twitter.com/lydiahallie)
 - [React 解读：React 19 路线图](https://www.youtube.com/watch?v=T8TZQ6k4SLE&t=10112s)，来自 [Sam Selikoff](https://twitter.com/samselikoff)

src/content/blog/2024/04/25/react-19.md → src/content/blog/2024/12/05/react-19.md

@@ -1,21 +1,33 @@
 ---
-title: "React 19 RC"
+title: "React v19"
 author: The React Team
-date: 2024/04/25
-description: React 19 RC 版现在可以在 npm 上使用了! 在这篇文章中，我们将概述 React 19 的新特性，以及如何使用它们。
+date: 2024/12/05
+description: React 19 版现在可以在 npm 上使用了! 在这篇文章中，我们将概述 React 19 的新特性，以及如何使用它们。
 ---
 
-2024 年 4 月 25 日 [The React Team](/community/team)
+2024 年 12 月 25 日 [The React Team](/community/team)
 
 ---
+<Note>
+
+### React 19 现已稳定！ {/*react-19-is-now-stable*/}
+
+从 4 月份发布这篇介绍 React 19 RC 的博客以来有以下新增内容：
+
+- **预热 suspend 树**：阅读 [改善 Suspense](/blog/2024/04/25/react-19-upgrade-guide#improvements-to-suspense) 来了解更多。
+- **React DOM 静态 API**：阅读 [新的 React DOM 静态 API](#new-react-dom-static-apis) 来了解更多。
+
+__本文的日期已更新，以反映稳定版的发布日期。__
+
+</Note>
 
 <Intro>
 
-React 19 RC 版本现在可以在 npm 上使用了!
+React 19 版本现在可以在 npm 上使用了!
 
 </Intro>
 
-在我们的 [React 19 RC 升级指南](/blog/2024/04/25/react-19-upgrade-guide) 中, 我们分享了将应用程序升级到 React 19 的分步说明。在这篇文章中，我们将概述 React 19 的新特性，以及如何使用它们。
+在我们的 [React 19 升级指南](/blog/2024/04/25/react-19-upgrade-guide) 中, 我们分享了将应用程序升级到 React 19 的分步说明。在这篇文章中，我们将概述 React 19 的新特性，以及如何使用它们。
 
 - [React 19 中的新功能](#whats-new-in-react-19)
 - [React 19 中的改进](#improvements-in-react-19)
@@ -312,6 +324,30 @@ function Heading({children}) {
 
 有关更多信息，请参阅 [`use`](/reference/react/use) 文档。
 
+## New React DOM Static APIs {/*new-react-dom-static-apis*/}
+
+We've added two new APIs to `react-dom/static` for static site generation:
+- [`prerender`](/reference/react-dom/static/prerender)
+- [`prerenderToNodeStream`](/reference/react-dom/static/prerenderToNodeStream)
+
+These new APIs improve on `renderToString` by waiting for data to load for static HTML generation. They are designed to work with streaming environments like Node.js Streams and Web Streams. For example, in a Web Stream environment, you can prerender a React tree to static HTML with `prerender`: 
+
+```js
+import { prerender } from 'react-dom/static';
+
+async function handler(request) {
+  const {prelude} = await prerender(<App />, {
+    bootstrapScripts: ['/main.js']
+  });
+  return new Response(prelude, {
+    headers: { 'content-type': 'text/html' },
+  });
+}
+```
+
+Prerender APIs will wait for all data to load before returning the static HTML stream. Streams can be converted to strings, or sent with a streaming response. They do not support streaming content as it loads, which is supported by the existing [React DOM server rendering APIs](/reference/react-dom/server).
+
+For more information, see [React DOM Static APIs](/reference/react-dom/static).
 
 ## React 服务器组件 {/*react-server-components*/}
 
@@ -771,5 +807,4 @@ React 19 添加了对自定义元素的全面支持，并通过了 [Custom Eleme
 
 请查看 [React 19 升级指南](/blog/2024/04/25/react-19-upgrade-guide) 以获取逐步指导和完整的破坏性和显著变化列表。
 
-
-
+__注意：这篇文章最初发布于 2024 年 4 月 25 日，并已将内容更新至 2024 年 12 月 5 日发布的稳定版本。__