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

package.json

@@ -24,8 +24,8 @@
   },
   "dependencies": {
     "@codesandbox/sandpack-react": "2.13.5",
-    "@docsearch/css": "3.0.0-alpha.41",
-    "@docsearch/react": "3.0.0-alpha.41",
+    "@docsearch/css": "^3.6.1",
+    "@docsearch/react": "^3.6.1",
     "@headlessui/react": "^1.7.0",
     "@radix-ui/react-context-menu": "^2.1.5",
     "body-scroll-lock": "^3.1.3",

src/components/MDX/Sandpack/Preview.tsx

@@ -113,7 +113,7 @@ export function Preview({
           /**
            * The spinner component transition might be longer than
            * the bundler loading, so we only show the spinner if
-           * it takes more than 1s to load the bundler.
+           * it takes more than 500s to load the bundler.
            */
           timeout = setTimeout(() => {
             setShowLoading(true);

src/components/Search.tsx

@@ -94,7 +94,17 @@ export function Search({
   onOpen,
   onClose,
   searchParameters = {
-    hitsPerPage: 5,
+    hitsPerPage: 30,
+    attributesToHighlight: [
+      'hierarchy.lvl0',
+      'hierarchy.lvl1',
+      'hierarchy.lvl2',
+      'hierarchy.lvl3',
+      'hierarchy.lvl4',
+      'hierarchy.lvl5',
+      'hierarchy.lvl6',
+      'content',
+    ],
   },
 }: SearchProps) {
   useDocSearchKeyboardEvents({isOpen, onOpen, onClose});

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

@@ -353,7 +353,7 @@ npm install react-shallow-renderer --save-dev
 
 ##### Please reconsider shallow rendering {/*please-reconsider-shallow-rendering*/}
 
-Shallow rendering depends on React internals and can block you from future upgrades. We recommend migrating your tests to [@testing-library/react](https://testing-library.com/docs/react-testing-library/intro/) or [@testing-library/react-native](https://callstack.github.io/react-native-testing-library/docs/getting-started). 
+Shallow rendering depends on React internals and can block you from future upgrades. We recommend migrating your tests to [@testing-library/react](https://testing-library.com/docs/react-testing-library/intro/) or [@testing-library/react-native](https://testing-library.com/docs/react-native-testing-library/intro). 
 
 </Note>
 
@@ -524,7 +524,7 @@ We are deprecating `react-test-renderer` because it implements its own renderer
 
 The test renderer was created before there were more viable testing strategies available like [React Testing Library](https://testing-library.com), and we now recommend using a modern testing library instead.
 
-In React 19, `react-test-renderer` logs a deprecation warning, and has switched to concurrent rendering. We recommend migrating your tests to [@testing-library/react](https://testing-library.com/docs/react-testing-library/intro/) or [@testing-library/react-native](https://callstack.github.io/react-native-testing-library/docs/getting-started) for a modern and well supported testing experience.
+In React 19, `react-test-renderer` logs a deprecation warning, and has switched to concurrent rendering. We recommend migrating your tests to [@testing-library/react](https://testing-library.com/docs/react-testing-library/intro/) or [@testing-library/react-native](https://testing-library.com/docs/react-native-testing-library/intro) for a modern and well supported testing experience.
 
 ## Notable changes {/*notable-changes*/}
 

src/content/community/conferences.md

@@ -35,11 +35,21 @@ October 18, 2024. In-person in Brussels, Belgium (hybrid event)
 
 [Website](https://www.react.brussels/) - [Twitter](https://x.com/BrusselsReact)
 
+### reactjsday 2024 {/*reactjsday-2024*/}
+October 25, 2024. In-person in Verona, Italy + online (hybrid event)
+
+[Website](https://2024.reactjsday.it/) - [Twitter](https://x.com/reactjsday) - [Facebook](https://www.facebook.com/GrUSP/) - [YouTube](https://www.youtube.com/c/grusp)
+
 ### React Advanced London 2024 {/*react-advanced-london-2024*/}
 October 25 & 28, 2024. In-person in London, UK + online (hybrid event)
 
 [Website](https://reactadvanced.com/) - [Twitter](https://x.com/reactadvanced)
 
+### React Native London Conf 2024 {/*react-native-london-2024*/}
+November 14 & 15, 2024. In-person in London, UK
+
+[Website](https://reactnativelondon.co.uk/) - [Twitter](https://x.com/RNLConf)
+
 ### React Summit US 2024 {/*react-summit-us-2024*/}
 November 19 & 22, 2024. In-person in New York, USA + online (hybrid event)
 

src/content/community/meetups.md

@@ -117,6 +117,9 @@ Do you have a local React.js meetup? Add it here! (Please keep the list alphabet
 ## Italy {/*italy*/}
 * [Milan](https://www.meetup.com/React-JS-Milano/)
 
+## Japan {/*japan*/}
+* [Osaka](https://react-osaka.connpass.com/)
+
 ## Kenya {/*kenya*/}
 * [Nairobi - Reactdevske](https://kommunity.com/reactjs-developer-community-kenya-reactdevske)
 

src/content/learn/manipulating-the-dom-with-refs.md

@@ -126,35 +126,35 @@ export default function CatFriends() {
     <>
       <nav>
         <button onClick={handleScrollToFirstCat}>
-          Tom
+          Neo
         </button>
         <button onClick={handleScrollToSecondCat}>
-          Maru
+          Millie
         </button>
         <button onClick={handleScrollToThirdCat}>
-          Jellylorum
+          Bella
         </button>
       </nav>
       <div>
         <ul>
           <li>
             <img
-              src="https://placekitten.com/g/200/200"
-              alt="Tom"
+              src="https://placecats.com/neo/300/200"
+              alt="Neo"
               ref={firstCatRef}
             />
           </li>
           <li>
             <img
-              src="https://placekitten.com/g/300/200"
-              alt="Maru"
+              src="https://placecats.com/millie/200/200"
+              alt="Millie"
               ref={secondCatRef}
             />
           </li>
           <li>
             <img
-              src="https://placekitten.com/g/250/200"
-              alt="Jellylorum"
+              src="https://placecats.com/bella/199/200"
+              alt="Bella"
               ref={thirdCatRef}
             />
           </li>
@@ -247,9 +247,9 @@ export default function CatFriends() {
   return (
     <>
       <nav>
-        <button onClick={() => scrollToCat(catList[0])}>Tom</button>
-        <button onClick={() => scrollToCat(catList[5])}>Maru</button>
-        <button onClick={() => scrollToCat(catList[9])}>Jellylorum</button>
+        <button onClick={() => scrollToCat(catList[0])}>Neo</button>
+        <button onClick={() => scrollToCat(catList[5])}>Millie</button>
+        <button onClick={() => scrollToCat(catList[9])}>Bella</button>
       </nav>
       <div>
         <ul>
@@ -950,7 +950,7 @@ const catList = [];
 for (let i = 0; i < 10; i++) {
   catList.push({
     id: i,
-    imageUrl: 'https://placekitten.com/250/200?image=' + i
+    imageUrl: 'https://loremflickr.com/250/200/cat?lock=' + i
   });
 }
 
@@ -1067,7 +1067,7 @@ const catList = [];
 for (let i = 0; i < 10; i++) {
   catList.push({
     id: i,
-    imageUrl: 'https://placekitten.com/250/200?image=' + i
+    imageUrl: 'https://loremflickr.com/250/200/cat?lock=' + i
   });
 }
 

src/content/learn/thinking-in-react.md

@@ -274,7 +274,7 @@ props 和 state 是不同的，但它们可以共同工作。父组件将经常
     * `ProductTable` 需要基于 state (搜索文本和复选框值) 过滤产品列表。
     * `SearchBar` 需要展示 state (搜索文本和复选框值)。
 2. **寻找它们的父组件**：它们的第一个共同父组件为 `FilterableProductTable`。
-3. **决定 state 放置的地方**：我们将放置过滤文本和勾选 state 的值于 `FilterableProductTable`。
+3. **决定 state 放置的地方**：我们将过滤文本和勾选 state 的值放置于 `FilterableProductTable` 中。
 
 所以 state 将被放置在 `FilterableProductTable`。
 

src/content/learn/tutorial-tic-tac-toe.md

@@ -1133,7 +1133,7 @@ export default function Board() {
 
 <Note>
 
-JavaScript 支持闭包，这意味着内部函数（例如 `handleClick`）可以访问外部函数（例如 `Board`）中定义的变量和函数。`handleClick` 函数可以读取 `squares` state 并调用 `setSquares` 方法，因为它们都是在 `Board` 函数内部定义的。
+JavaScript 支持 [闭包](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Closures)，这意味着内部函数（例如 `handleClick`）可以访问外部函数（例如 `Board`）中定义的变量和函数。`handleClick` 函数可以读取 `squares` state 并调用 `setSquares` 方法，因为它们都是在 `Board` 函数内部定义的。
 
 </Note>
 

src/content/learn/updating-objects-in-state.md

@@ -61,6 +61,7 @@ position.x = 5;
 
 ```js
 import { useState } from 'react';
+
 export default function MovingDot() {
   const [position, setPosition] = useState({
     x: 0,
@@ -131,6 +132,7 @@ onPointerMove={e => {
 
 ```js
 import { useState } from 'react';
+
 export default function MovingDot() {
   const [position, setPosition] = useState({
     x: 0,

src/content/reference/react/act.md

@@ -90,7 +90,7 @@ To test the render output of a component, wrap the render inside `act()`:
 
 ```js  {10,12}
 import {act} from 'react';
-import ReactDOM from 'react-dom/client';
+import ReactDOMClient from 'react-dom/client';
 import Counter from './Counter';
 
 it('can render and update a counter', async () => {
@@ -99,7 +99,7 @@ it('can render and update a counter', async () => {
 
   // ✅ Render the component inside act().
   await act(() => {
-    ReactDOM.createRoot(container).render(<Counter />);
+    ReactDOMClient.createRoot(container).render(<Counter />);
   });
 
   const button = container.querySelector('button');
@@ -119,7 +119,7 @@ To test events, wrap the event dispatch inside `act()`:
 
 ```js {14,16}
 import {act} from 'react';
-import ReactDOM from 'react-dom/client';
+import ReactDOMClient from 'react-dom/client';
 import Counter from './Counter';
 
 it.only('can render and update a counter', async () => {
@@ -174,4 +174,4 @@ global.IS_REACT_ACT_ENVIRONMENT=true
 
 In testing frameworks like [React Testing Library](https://testing-library.com/docs/react-testing-library/intro), `IS_REACT_ACT_ENVIRONMENT` is already set for you.
 
-</Note>
+</Note>

src/content/reference/react/useCallback.md

@@ -711,7 +711,7 @@ function ChatRoom({ roomId }) {
 
   useEffect(() => {
     const options = createOptions();
-    const connection = createConnection();
+    const connection = createConnection(options);
     connection.connect();
     // ...
 ```
@@ -722,7 +722,7 @@ function ChatRoom({ roomId }) {
 ```js {6}
   useEffect(() => {
     const options = createOptions();
-    const connection = createConnection();
+    const connection = createConnection(options);
     connection.connect();
     return () => connection.disconnect();
   }, [createOptions]); // 🔴 问题：这个依赖在每一次渲染中都会发生改变
@@ -744,7 +744,7 @@ function ChatRoom({ roomId }) {
 
   useEffect(() => {
     const options = createOptions();
-    const connection = createConnection();
+    const connection = createConnection(options);
     connection.connect();
     return () => connection.disconnect();
   }, [createOptions]); // ✅ 仅当 createOptions 更改时更改
@@ -766,7 +766,7 @@ function ChatRoom({ roomId }) {
     }
 
     const options = createOptions();
-    const connection = createConnection();
+    const connection = createConnection(options);
     connection.connect();
     return () => connection.disconnect();
   }, [roomId]); // ✅ 仅当 roomId 更改时更改

src/content/reference/react/useMemo.md

@@ -1056,6 +1056,83 @@ label {
 
 ---
 
+### 防止过于频繁地触发 Effect {/*preventing-an-effect-from-firing-too-often*/}
+
+有时你可能会想要在 [Effect](/learn/synchronizing-with-effects) 中使用变量：
+
+```js {4-7,10}
+function ChatRoom({ roomId }) {
+  const [message, setMessage] = useState('');
+
+  const options = {
+    serverUrl: 'https://localhost:1234',
+    roomId: roomId
+  }
+
+  useEffect(() => {
+    const connection = createConnection(options);
+    connection.connect();
+    // ...
+```
+
+但是这样做会带来一些问题。因为 [Effect 中的每一个响应式值都应该声明为其依赖。](/learn/lifecycle-of-reactive-effects#react-verifies-that-you-specified-every-reactive-value-as-a-dependency) 然而如果你将 `options` 声明为依赖，会导致在 Effect 中不断地重新连接到聊天室：
+
+
+```js {5}
+  useEffect(() => {
+    const connection = createConnection(options);
+    connection.connect();
+    return () => connection.disconnect();
+  }, [options]); // 🔴 问题：每次渲染这个依赖项都会发生改变
+  // ...
+```
+
+为了解决这个场景，你可以使用 `useMemo` 将 Effect 中使用的对象包装起来：
+
+```js {4-9,16}
+function ChatRoom({ roomId }) {
+  const [message, setMessage] = useState('');
+
+  const options = useMemo(() => {
+    return {
+      serverUrl: 'https://localhost:1234',
+      roomId: roomId
+    };
+  }, [roomId]); // ✅ 只有当 roomId 改变时才会被改变
+
+  useEffect(() => {
+    const options = createOptions();
+    const connection = createConnection(options);
+    connection.connect();
+    return () => connection.disconnect();
+  }, [options]); // ✅ 只有当 createOptions 改变时才会被改变
+  // ...
+```
+
+因为 `useMemo` 返回了缓存的对象，所以这将确保 `options` 对象在重新渲染期间保持不变。
+
+然而，因为 `useMemo` 只是一个性能优化手段，而并不是语义上的保证，所以 React 在 [特定场景下](#caveats) 会丢弃缓存值。这也会导致重新触发 Effect，因此 **最好通过将对象移动到 Effect 内部来消除对函数的依赖**：
+
+```js {5-8,13}
+function ChatRoom({ roomId }) {
+  const [message, setMessage] = useState('');
+
+  useEffect(() => {
+    const options = { // ✅ 不需要将 useMemo 或对象作为依赖！
+      serverUrl: 'https://localhost:1234',
+      roomId: roomId
+    }
+
+    const connection = createConnection(options);
+    connection.connect();
+    return () => connection.disconnect();
+  }, [roomId]); // ✅ 只有当 roomId 改变时才会被改变
+  // ...
+```
+
+现在你的代码不需要使用 `useMemo` 并且更加简洁。[了解移除 Effect 依赖项的更多信息。](/learn/removing-effect-dependencies#move-dynamic-objects-and-functions-inside-your-effect)
+
+
 ### 记忆另一个 Hook 的依赖 {/*memoizing-a-dependency-of-another-hook*/}
 
 假设你有一个计算函数依赖于直接在组件主体中创建的对象：

src/content/reference/react/useReducer.md

@@ -52,6 +52,7 @@ function MyComponent() {
 #### 注意事项 {/*caveats*/}
 
 * `useReducer` 是一个 Hook，所以只能在 **组件的顶层作用域** 或自定义 Hook 中调用，而不能在循环或条件语句中调用。如果你有这种需求，可以创建一个新的组件，并把 state 移入其中。
+* `dispatch` 函数具有稳定的标识，所以你经常会看到 Effect 的依赖数组中会省略它，即使包含它也不会导致 Effect 重新触发。如果 linter 允许你省略依赖项并且没有报错，那么你就可以安全地省略它。[了解移除 Effect 依赖项的更多信息。](/learn/removing-effect-dependencies#move-dynamic-objects-and-functions-inside-your-effect)
 * 严格模式下 React 会 **调用两次 reducer 和初始化函数**，这可以 [帮助你发现意外的副作用](#my-reducer-or-initializer-function-runs-twice)。这只是开发模式下的行为，并不会影响生产环境。只要 reducer 和初始化函数是纯函数（理应如此）就不会改变你的逻辑。其中一个调用结果会被忽略。
 
 ---