diff --git a/beta/src/content/learn/manipulating-the-dom-with-refs.md b/beta/src/content/learn/manipulating-the-dom-with-refs.md index 2adee47ace..46f8260942 100644 --- a/beta/src/content/learn/manipulating-the-dom-with-refs.md +++ b/beta/src/content/learn/manipulating-the-dom-with-refs.md @@ -1,52 +1,54 @@ --- -title: 'Manipulating the DOM with Refs' +title: '使用 Refs 操作 DOM' +translators: + - SylviaZ89 --- -React automatically updates the [DOM](https://developer.mozilla.org/docs/Web/API/Document_Object_Model/Introduction) to match your render output, so your components won't often need to manipulate it. However, sometimes you might need access to the DOM elements managed by React--for example, to focus a node, scroll to it, or measure its size and position. There is no built-in way to do those things in React, so you will need a *ref* to the DOM node. +由于 React 会自动处理更新 [DOM](https://developer.mozilla.org/docs/Web/API/Document_Object_Model/Introduction) 以匹配你的渲染输出,因此你在组件中通常不需要操作 DOM。但是,有时你可能需要访问由 React 管理的 DOM 元素 —— 例如,让一个节点获得焦点、滚动到它或测量它的尺寸和位置。在 React 中没有内置的方法来做这些事情,所以你需要一个指向 DOM 节点的 *ref* 来实现。 -- How to access a DOM node managed by React with the `ref` attribute -- How the `ref` JSX attribute relates to the `useRef` Hook -- How to access another component's DOM node -- In which cases it's safe to modify the DOM managed by React +- 如何使用 `ref` 属性访问由 React 管理的 DOM 节点 +- `ref` JSX 属性如何与 `useRef` Hook 相关联 +- 如何访问另一个组件的 DOM 节点 +- 在哪些情况下修改 React 管理的 DOM 是安全的 -## Getting a ref to the node {/*getting-a-ref-to-the-node*/} +## 获取指向节点的 ref {/*getting-a-ref-to-the-node*/} -To access a DOM node managed by React, first, import the `useRef` Hook: +要访问由 React 管理的 DOM 节点,首先,引入 `useRef` Hook: ```js import { useRef } from 'react'; ``` -Then, use it to declare a ref inside your component: +然后,在你的组件中使用它声明一个 ref: ```js const myRef = useRef(null); ``` -Finally, pass it to the DOM node as the `ref` attribute: +最后,将其作为 `ref` 属性传给 DOM 节点: ```js
``` -The `useRef` Hook returns an object with a single property called `current`. Initially, `myRef.current` will be `null`. When React creates a DOM node for this `
`, React will put a reference to this node into `myRef.current`. You can then access this DOM node from your [event handlers](/learn/responding-to-events) and use the built-in [browser APIs](https://developer.mozilla.org/docs/Web/API/Element) defined on it. +`useRef` Hook 返回一个对象,该对象有一个名为 `current` 的属性。最初,`myRef.current` 是 `null`。当 React 为这个 `
` 创建一个 DOM 节点时,React 会把对该节点的引用放入 `myRef.current`。然后,你可以从 [事件处理器](/learn/responding-to-events) 访问此 DOM 节点,并使用在其上定义的内置[浏览器 API](https://developer.mozilla.org/docs/Web/API/Element)。 ```js -// You can use any browser APIs, for example: +// 你可以使用任意浏览器 API,例如: myRef.current.scrollIntoView(); ``` -### Example: Focusing a text input {/*example-focusing-a-text-input*/} +### 示例: 使文本输入框获得焦点 {/*example-focusing-a-text-input*/} -In this example, clicking the button will focus the input: +在本例中,单击按钮将使输入框获得焦点: @@ -64,7 +66,7 @@ export default function Form() { <> ); @@ -73,18 +75,18 @@ export default function Form() { -To implement this: +要实现这一点: -1. Declare `inputRef` with the `useRef` Hook. -2. Pass it as ``. This tells React to **put this ``'s DOM node into `inputRef.current`.** -3. In the `handleClick` function, read the input DOM node from `inputRef.current` and call [`focus()`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) on it with `inputRef.current.focus()`. -4. Pass the `handleClick` event handler to ` ); @@ -375,7 +377,7 @@ export default function MyForm() { -To help you notice the issue, React also prints an error to the console: +为了帮助您注意到这个问题,React 还会向控制台打印一条错误消息: @@ -383,9 +385,9 @@ Warning: Function components cannot be given refs. Attempts to access this ref w -This happens because by default React does not let a component access the DOM nodes of other components. Not even for its own children! This is intentional. Refs are an escape hatch that should be used sparingly. Manually manipulating _another_ component's DOM nodes makes your code even more fragile. +发生这种情况是因为默认情况下,React 不允许组件访问其他组件的 DOM 节点。甚至自己的子组件也不行!这是故意的。Refs 是一个应急方案,应该谨慎使用。手动操作 _另一个_ 组件的 DOM 节点会使你的代码更加脆弱。 -Instead, components that _want_ to expose their DOM nodes have to **opt in** to that behavior. A component can specify that it "forwards" its ref to one of its children. Here's how `MyInput` can use the `forwardRef` API: +相反,_想要_ 暴露其 DOM 节点的组件必须**选择**该行为。一个组件可以指定将它的 ref “转发”给一个子组件。下面是 `MyInput` 如何使用 `forwardRef` API: ```js const MyInput = forwardRef((props, ref) => { @@ -393,13 +395,13 @@ const MyInput = forwardRef((props, ref) => { }); ``` -This is how it works: +它是这样工作的: -1. `` tells React to put the corresponding DOM node into `inputRef.current`. However, it's up to the `MyInput` component to opt into that--by default, it doesn't. -2. The `MyInput` component is declared using `forwardRef`. **This opts it into receiving the `inputRef` from above as the second `ref` argument** which is declared after `props`. -3. `MyInput` itself passes the `ref` it received to the `` inside of it. +1. `` 告诉 React 将对应的 DOM 节点放入 `inputRef.current` 中。但是,这取决于 `MyInput` 组件是否允许这种行为, 默认情况下是不允许的。 +2. `MyInput` 组件是使用 `forwardRef` 声明的。 **这让从上面接收的 `inputRef` 作为第二个参数 `ref` 传入组件**,第一个参数是 `props` 。 +3. `MyInput` 组件将自己接收到的 `ref` 传递给它内部的 ``。 -Now clicking the button to focus the input works: +现在,单击按钮聚焦输入框起作用了: @@ -421,7 +423,7 @@ export default function Form() { <> ); @@ -430,13 +432,13 @@ export default function Form() { -In design systems, it is a common pattern for low-level components like buttons, inputs, and so on, to forward their refs to their DOM nodes. On the other hand, high-level components like forms, lists, or page sections usually won't expose their DOM nodes to avoid accidental dependencies on the DOM structure. +在设计系统中,将低级组件(如按钮、输入框等)的 ref 转发到它们的 DOM 节点是一种常见模式。另一方面,像表单、列表或页面段落这样的高级组件通常不会暴露它们的 DOM 节点,以避免对 DOM 结构的意外依赖。 -#### Exposing a subset of the API with an imperative handle {/*exposing-a-subset-of-the-api-with-an-imperative-handle*/} +#### 使用命令句柄暴露一部分 API {/*exposing-a-subset-of-the-api-with-an-imperative-handle*/} -In the above example, `MyInput` exposes the original DOM input element. This lets the parent component call `focus()` on it. However, this also lets the parent component do something else--for example, change its CSS styles. In uncommon cases, you may want to restrict the exposed functionality. You can do that with `useImperativeHandle`: +在上面的例子中,`MyInput` 暴露了原始的 DOM 元素 input。这让父组件可以对其调用`focus()`。然而,这也让父组件能够做其他事情 —— 例如,改变其 CSS 样式。在一些不常见的情况下,你可能希望限制暴露的功能。你可以用 `useImperativeHandle` 做到这一点: @@ -450,7 +452,7 @@ import { const MyInput = forwardRef((props, ref) => { const realInputRef = useRef(null); useImperativeHandle(ref, () => ({ - // Only expose focus and nothing else + // 只暴露 focus,没有别的 focus() { realInputRef.current.focus(); }, @@ -469,7 +471,7 @@ export default function Form() { <> ); @@ -478,28 +480,28 @@ export default function Form() { -Here, `realInputRef` inside `MyInput` holds the actual input DOM node. However, `useImperativeHandle` instructs React to provide your own special object as the value of a ref to the parent component. So `inputRef.current` inside the `Form` component will only have the `focus` method. In this case, the ref "handle" is not the DOM node, but the custom object you create inside `useImperativeHandle` call. +这里,`MyInput` 中的 `realInputRef` 保存了实际的 input DOM 节点。 但是,`useImperativeHandle` 指示 React 将你自己指定的对象作为父组件的 ref 值。 所以 `Form` 组件内的 `inputRef.current` 将只有 `focus` 方法。在这种情况下,ref “句柄”不是 DOM 节点,而是你在 `useImperativeHandle` 调用中创建的自定义对象。 -## When React attaches the refs {/*when-react-attaches-the-refs*/} +## React 何时添加 refs {/*when-react-attaches-the-refs*/} -In React, every update is split in [two phases](/learn/render-and-commit#step-3-react-commits-changes-to-the-dom): +在 React 中,每次更新都分为 [两个阶段](/learn/render-and-commit#step-3-react-commits-changes-to-the-dom): -* During **render,** React calls your components to figure out what should be on the screen. -* During **commit,** React applies changes to the DOM. +* 在 **渲染** 阶段, React 调用你的组件来确定屏幕上应该显示什么。 +* 在 **提交** 阶段, React 把变更应用于 DOM。 -In general, you [don't want](/learn/referencing-values-with-refs#best-practices-for-refs) to access refs during rendering. That goes for refs holding DOM nodes as well. During the first render, the DOM nodes have not yet been created, so `ref.current` will be `null`. And during the rendering of updates, the DOM nodes haven't been updated yet. So it's too early to read them. +通常,你 [不希望](/learn/referencing-values-with-refs#best-practices-for-refs) 在渲染期间访问 refs。这也适用于保存 DOM 节点的 refs。在第一次渲染期间,DOM 节点尚未创建,因此 `ref.current` 将为 `null`。在渲染更新的过程中,DOM 节点还没有更新。所以读取它们还为时过早。 -React sets `ref.current` during the commit. Before updating the DOM, React sets the affected `ref.current` values to `null`. After updating the DOM, React immediately sets them to the corresponding DOM nodes. +React 在提交阶段设置 `ref.current`。在更新 DOM 之前,React 将受影响的 `ref.current` 值设置为 `null`。更新 DOM 后,React 立即将它们设置到相应的 DOM 节点。 -**Usually, you will access refs from event handlers.** If you want to do something with a ref, but there is no particular event to do it in, you might need an Effect. We will discuss effects on the next pages. +**通常,你将从事件处理器访问 refs。** 如果你想使用 ref 执行某些操作,但没有特定的事件可以执行此操作,你可能需要一个 effect。我们将在下一页讨论 effect。 -#### Flushing state updates synchronously with flushSync {/*flushing-state-updates-synchronously-with-flush-sync*/} +#### 用 flushSync 同步更新 state {/*flushing-state-updates-synchronously-with-flush-sync*/} -Consider code like this, which adds a new todo and scrolls the screen down to the last child of the list. Notice how, for some reason, it always scrolls to the todo that was *just before* the last added one: +思考这样的代码,它添加一个新的待办事项,并将屏幕向下滚动到列表的最后一个子项。请注意,出于某种原因,它总是滚动到最后一个添加*之前* 的待办事项: @@ -526,7 +528,7 @@ export default function TodoList() { return ( <> -The issue is with these two lines: +问题出在这两行: ```js setTodos([ ...todos, newTodo]); listRef.current.lastChild.scrollIntoView(); ``` -In React, [state updates are queued.](/learn/queueing-a-series-of-state-updates) Usually, this is what you want. However, here it causes a problem because `setTodos` does not immediately update the DOM. So the time you scroll the list to its last element, the todo has not yet been added. This is why scrolling always "lags behind" by one item. +在 React 中,[state 更新是排队进行的](/learn/queueing-a-series-of-state-updates)。通常,这就是你想要的。但是,在这个示例中会导致问题,因为 `setTodos` 不会立即更新 DOM。因此,当你将列表滚动到最后一个元素时,尚未添加待办事项。这就是为什么滚动总是“落后”一项的原因。 -To fix this issue, you can force React to update ("flush") the DOM synchronously. To do this, import `flushSync` from `react-dom` and **wrap the state update** into a `flushSync` call: +要解决此问题,你可以强制 React 同步更新(“刷新”)DOM。 为此,从 `react-dom` 导入 `flushSync` 并**将 state 更新包裹** 到 `flushSync` 调用中: ```js flushSync(() => { @@ -571,7 +573,7 @@ flushSync(() => { listRef.current.lastChild.scrollIntoView(); ``` -This will instruct React to update the DOM synchronously right after the code wrapped in `flushSync` executes. As a result, the last todo will already be in the DOM by the time you try to scroll to it: +这将指示 React 当封装在 `flushSync` 中的代码执行后,立即同步更新 DOM。因此,当你尝试滚动到最后一个待办事项时,它已经在 DOM 中了: @@ -601,7 +603,7 @@ export default function TodoList() { return ( <> -## Best practices for DOM manipulation with refs {/*best-practices-for-dom-manipulation-with-refs*/} +## 使用 refs 操作 DOM 的最佳实践 {/*best-practices-for-dom-manipulation-with-refs*/} -Refs are an escape hatch. You should only use them when you have to "step outside React". Common examples of this include managing focus, scroll position, or calling browser APIs that React does not expose. +Refs 是一个应急方案。你应该只在你必须“跳出 React”时使用它们。这方面的常见示例包括管理焦点、滚动位置或调用 React 未暴露的浏览器 API。 -If you stick to non-destructive actions like focusing and scrolling, you shouldn't encounter any problems. However, if you try to **modify** the DOM manually, you can risk conflicting with the changes React is making. +如果你坚持聚焦和滚动等非破坏性操作,应该不会遇到任何问题。但是,如果你尝试手动**修改** DOM,则可能会与 React 所做的更改发生冲突。 -To illustrate this problem, this example includes a welcome message and two buttons. The first button toggles its presence using [conditional rendering](/learn/conditional-rendering) and [state](/learn/state-a-components-memory), as you would usually do in React. The second button uses the [`remove()` DOM API](https://developer.mozilla.org/en-US/docs/Web/API/Element/remove) to forcefully remove it from the DOM outside of React's control. +为了说明这个问题,这个例子包括一条欢迎消息和两个按钮。第一个按钮使用 [条件渲染](/learn/conditional-rendering) 和 [state](/learn/state-a-components-memory) 切换它的显示和隐藏,就像你通常在 React 中所做的那样。第二个按钮使用 [`remove()` DOM API](https://developer.mozilla.org/zh-CN/docs/Web/API/Element/remove) 将其从 React 控制之外的 DOM 中强行移除. -Try pressing "Toggle with setState" a few times. The message should disappear and appear again. Then press "Remove from the DOM". This will forcefully remove it. Finally, press "Toggle with setState": +尝试按几次“通过 setState 切换”。该消息会消失并再次出现。然后按 “从 DOM 中删除”。这将强行删除它。最后,按 “通过 setState 切换”: @@ -655,13 +657,13 @@ export default function Counter() { onClick={() => { setShow(!show); }}> - Toggle with setState + 通过 setState 切换 {show &&

Hello world

}
@@ -679,20 +681,20 @@ button { -After you've manually removed the DOM element, trying to use `setState` to show it again will lead to a crash. This is because you've changed the DOM, and React doesn't know how to continue managing it correctly. +在你手动删除 DOM 元素后,尝试使用 `setState` 再次显示它会导致崩溃。这是因为你更改了 DOM,而 React 不知道如何继续正确管理它。 -**Avoid changing DOM nodes managed by React.** Modifying, adding children to, or removing children from elements that are managed by React can lead to inconsistent visual results or crashes like above. +**避免更改由 React 管理的 DOM 节点。** 对 React 管理的元素进行修改、添加子元素、从中删除子元素会导致不一致的视觉结果,或与上述类似的崩溃。 -However, this doesn't mean that you can't do it at all. It requires caution. **You can safely modify parts of the DOM that React has _no reason_ to update.** For example, if some `
` is always empty in the JSX, React won't have a reason to touch its children list. Therefore, it is safe to manually add or remove elements there. +但是,这并不意味着你完全不能这样做。它需要谨慎。 **你可以安全地修改 React _没有理由_ 更新的部分 DOM。** 例如,如果某些 `
` 在 JSX 中始终为空,React 将没有理由去变动其子列表。 因此,在那里手动增删元素是安全的。 -- Refs are a generic concept, but most often you'll use them to hold DOM elements. -- You instruct React to put a DOM node into `myRef.current` by passing `
`. -- Usually, you will use refs for non-destructive actions like focusing, scrolling, or measuring DOM elements. -- A component doesn't expose its DOM nodes by default. You can opt into exposing a DOM node by using `forwardRef` and passing the second `ref` argument down to a specific node. -- Avoid changing DOM nodes managed by React. -- If you do modify DOM nodes managed by React, modify parts that React has no reason to update. +- Refs 是一个通用概念,但大多数情况下你会使用它们来保存 DOM 元素。 +- 你通过传递 `
` 指示 React 将 DOM 节点放入 `myRef.current`。 +- 通常,你会将 refs 用于非破坏性操作,例如聚焦、滚动或测量 DOM 元素。 +- 默认情况下,组件不暴露其 DOM 节点。 您可以通过使用 `forwardRef` 并将第二个 `ref` 参数传递给特定节点来暴露 DOM 节点。 +- 避免更改由 React 管理的 DOM 节点。 +- 如果你确实修改了 React 管理的 DOM 节点,请修改 React 没有理由更新的部分。 @@ -700,9 +702,9 @@ However, this doesn't mean that you can't do it at all. It requires caution. **Y -#### Play and pause the video {/*play-and-pause-the-video*/} +#### 播放和暂停视频 {/*play-and-pause-the-video*/} -In this example, the button toggles a state variable to switch between a playing and a paused state. However, in order to actually play or pause the video, toggling state is not enough. You also need to call [`play()`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/play) and [`pause()`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/pause) on the DOM element for the `