使用引用操作 DOM

获取节点的引用

🌐 Getting a ref to the node

要访问由 React 管理的 DOM 节点，首先导入 useRef Hook：

🌐 To access a DOM node managed by React, first, import the useRef Hook:

import { useRef } from 'react';

然后，使用它在你的组件内声明一个引用：

🌐 Then, use it to declare a ref inside your component:

const myRef = useRef(null);

最后，将你的 ref 作为 ref 属性传递给你想获取其 DOM 节点的 JSX 标签：

🌐 Finally, pass your ref as the ref attribute to the JSX tag for which you want to get the DOM node:

<div ref={myRef}>

useRef Hook 返回一个包含单个属性 current 的对象。最初，myRef.current 将是 null。当 React 为这个 <div> 创建一个 DOM 节点时，React 会将该节点的引用放入 myRef.current。然后，你可以从你的 事件处理程序 访问这个 DOM 节点，并使用定义在其上的内置 浏览器 API。

🌐 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 <div>, React will put a reference to this node into myRef.current. You can then access this DOM node from your event handlers and use the built-in browser APIs defined on it.

// You can use any browser APIs, for example:
myRef.current.scrollIntoView();

示例：聚焦文本输入

🌐 Example: Focusing a text input

在此示例中，单击按钮将聚焦输入：

🌐 In this example, clicking the button will focus the input:

要实现这一点：

🌐 To implement this:

1. 使用 useRef Hook 声明 inputRef。
2. 将其传递为 <input ref={inputRef}>。这告诉 React 将这个 <input> 的 DOM 节点放入 inputRef.current 中。
3. 在 handleClick 函数中，从 inputRef.current 读取输入 DOM 节点，并使用 inputRef.current.focus() 调用 focus()
4. 将 handleClick 事件处理程序与 onClick 一起传递给 <button>。

虽然 DOM 操作是使用 refs 最常见的场景，但 useRef Hook 可以用于在 React 外部存储其他内容，例如定时器 ID。与 state 类似，refs 在渲染之间保持不变。refs 就像不会在设置时触发重新渲染的状态变量。请阅读关于 refs 的信息：使用 Refs 引用值。

🌐 While DOM manipulation is the most common use case for refs, the useRef Hook can be used for storing other things outside React, like timer IDs. Similarly to state, refs remain between renders. Refs are like state variables that don’t trigger re-renders when you set them. Read about refs in Referencing Values with Refs.

示例：滚动到某个元素

🌐 Example: Scrolling to an element

在一个组件中，你可以拥有多个引用。在这个例子中，有一个包含三张图片的轮播。每个按钮通过在对应的 DOM 节点上调用浏览器的 scrollIntoView() 方法来将图片居中：

🌐 You can have more than a single ref in a component. In this example, there is a carousel of three images. Each button centers an image by calling the browser scrollIntoView() method on the corresponding DOM node:

<ul>
  {items.map((item) => {
    // Doesn't work!
    const ref = useRef(null);
    return <li ref={ref} />;
  })}
</ul>

import { useRef, useState } from "react";

export default function CatFriends() {
  const itemsRef = useRef(null);
  const [catList, setCatList] = useState(setupCatList);

  function scrollToCat(cat) {
    const map = getMap();
    const node = map.get(cat);
    node.scrollIntoView({
      behavior: "smooth",
      block: "nearest",
      inline: "center",
    });
  }

  function getMap() {
    if (!itemsRef.current) {
      // Initialize the Map on first usage.
      itemsRef.current = new Map();
    }
    return itemsRef.current;
  }

  return (
    <>
      <nav>
        <button onClick={() => scrollToCat(catList[0])}>Neo</button>
        <button onClick={() => scrollToCat(catList[5])}>Millie</button>
        <button onClick={() => scrollToCat(catList[8])}>Bella</button>
      </nav>
      <div>
        <ul>
          {catList.map((cat) => (
            <li
              key={cat.id}
              ref={(node) => {
                const map = getMap();
                map.set(cat, node);

                return () => {
                  map.delete(cat);
                };
              }}
            >
              <img src={cat.imageUrl} />
            </li>
          ))}
        </ul>
      </div>
    </>
  );
}

function setupCatList() {
  const catCount = 10;
  const catList = new Array(catCount)
  for (let i = 0; i < catCount; i++) {
    let imageUrl = '';
    if (i < 5) {
      imageUrl = "https://placecats.com/neo/320/240";
    } else if (i < 8) {
      imageUrl = "https://placecats.com/millie/320/240";
    } else {
      imageUrl = "https://placecats.com/bella/320/240";
    }
    catList[i] = {
      id: i,
      imageUrl,
    };
  }
  return catList;
}

<li
  key={cat.id}
  ref={node => {
    const map = getMap();
    // Add to the Map
    map.set(cat, node);

    return () => {
      // Remove from the Map
      map.delete(cat);
    };
  }}
>

访问另一个组件的 DOM 节点

🌐 Accessing another component’s DOM nodes

你可以像传递其他属性一样将 refs 从父组件传递给子组件。

🌐 You can pass refs from parent component to child components just like any other prop.

import { useRef } from 'react';

function MyInput({ ref }) {
  return <input ref={ref} />;
}

function MyForm() {
  const inputRef = useRef(null);
  return <MyInput ref={inputRef} />
}

在上面的示例中，ref 在父组件 MyForm 中创建，并传递给子组件 MyInput。然后 MyInput 将 ref 传递给 <input>。因为 <input> 是一个 内置组件，所以 React 会将 ref 的 .current 属性设置为 <input> DOM 元素。

🌐 In the above example, a ref is created in the parent component, MyForm, and is passed to the child component, MyInput. MyInput then passes the ref to <input>. Because <input> is a built-in component React sets the .current property of the ref to the <input> DOM element.

在 MyForm 中创建的 inputRef 现在指向由 MyInput 返回的 <input> DOM 元素。在 MyForm 中创建的点击处理程序可以访问 inputRef 并调用 focus() 来将焦点设置到 <input>。

🌐 The inputRef created in MyForm now points to the <input> DOM element returned by MyInput. A click handler created in MyForm can access inputRef and call focus() to set the focus on <input>.

import { useRef, useImperativeHandle } from "react";

function MyInput({ ref }) {
  const realInputRef = useRef(null);
  useImperativeHandle(ref, () => ({
    // Only expose focus and nothing else
    focus() {
      realInputRef.current.focus();
    },
  }));
  return <input ref={realInputRef} />;
};

export default function Form() {
  const inputRef = useRef(null);

  function handleClick() {
    inputRef.current.focus();
  }

  return (
    <>
      <MyInput ref={inputRef} />
      <button onClick={handleClick}>Focus the input</button>
    </>
  );
}

当 React 附加引用时

🌐 When React attaches the refs

在 React 中，每次更新都分为 两个阶段：

🌐 In React, every update is split in two phases:

• 在渲染期间，React 会调用你的组件来确定屏幕上应该显示什么。
• 在 提交 阶段，React 会将更改应用到 DOM。

一般来说，你不想在渲染期间访问 refs。这同样适用于保存 DOM 节点的 refs。在第一次渲染时，DOM 节点还没有被创建，所以 ref.current 将会是 null。在更新渲染期间，DOM 节点还没有被更新。因此现在读取它们为时过早。

🌐 In general, you don’t want 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.

React 在提交期间设置 ref.current。在更新 DOM 之前，React 将受影响的 ref.current 值设置为 null。在更新 DOM 之后，React 会立即将它们设置为相应的 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.

通常，你会从事件处理程序中访问 refs。 如果你想对 ref 做一些操作，但没有特定的事件可以使用，你可能需要一个 Effect。我们将在接下来的页面中讨论 Effects。

import { useState, useRef } from 'react';

export default function TodoList() {
  const listRef = useRef(null);
  const [text, setText] = useState('');
  const [todos, setTodos] = useState(
    initialTodos
  );

  function handleAdd() {
    const newTodo = { id: nextId++, text: text };
    setText('');
    setTodos([ ...todos, newTodo]);
    listRef.current.lastChild.scrollIntoView({
      behavior: 'smooth',
      block: 'nearest'
    });
  }

  return (
    <>
      <button onClick={handleAdd}>
        Add
      </button>
      <input
        value={text}
        onChange={e => setText(e.target.value)}
      />
      <ul ref={listRef}>
        {todos.map(todo => (
          <li key={todo.id}>{todo.text}</li>
        ))}
      </ul>
    </>
  );
}

let nextId = 0;
let initialTodos = [];
for (let i = 0; i < 20; i++) {
  initialTodos.push({
    id: nextId++,
    text: 'Todo #' + (i + 1)
  });
}

setTodos([ ...todos, newTodo]);
listRef.current.lastChild.scrollIntoView();

flushSync(() => {
  setTodos([ ...todos, newTodo]);
});
listRef.current.lastChild.scrollIntoView();

import { useState, useRef } from 'react';
import { flushSync } from 'react-dom';

export default function TodoList() {
  const listRef = useRef(null);
  const [text, setText] = useState('');
  const [todos, setTodos] = useState(
    initialTodos
  );

  function handleAdd() {
    const newTodo = { id: nextId++, text: text };
    flushSync(() => {
      setText('');
      setTodos([ ...todos, newTodo]);
    });
    listRef.current.lastChild.scrollIntoView({
      behavior: 'smooth',
      block: 'nearest'
    });
  }

  return (
    <>
      <button onClick={handleAdd}>
        Add
      </button>
      <input
        value={text}
        onChange={e => setText(e.target.value)}
      />
      <ul ref={listRef}>
        {todos.map(todo => (
          <li key={todo.id}>{todo.text}</li>
        ))}
      </ul>
    </>
  );
}

let nextId = 0;
let initialTodos = [];
for (let i = 0; i < 20; i++) {
  initialTodos.push({
    id: nextId++,
    text: 'Todo #' + (i + 1)
  });
}

使用引用操作 DOM 的最佳实践

🌐 Best practices for DOM manipulation with refs

Refs 是一种逃生通道。你应该只在必须“跳出 React”时使用它们。常见的例子包括管理焦点、滚动位置，或调用 React 未暴露的浏览器 API。

🌐 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.

如果你坚持执行非破坏性的操作，比如聚焦和滚动，你不应该遇到任何问题。然而，如果你尝试手动修改DOM，你可能会与React正在进行的更改发生冲突。

🌐 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.

为了说明这个问题，这个示例包含一条欢迎消息和两个按钮。第一个按钮使用条件渲染和状态来切换它的显示，就像你在 React 中通常做的一样。第二个按钮使用remove() DOM API在 React 控制之外强制将其从 DOM 中移除。

🌐 To illustrate this problem, this example includes a welcome message and two buttons. The first button toggles its presence using conditional rendering and state, as you would usually do in React. The second button uses the remove() DOM API to forcefully remove it from the DOM outside of React’s control.

尝试点击“使用 setState 切换”几次。消息应该会消失然后再次出现。然后点击“从 DOM 中移除”。这会强制将其移除。最后，点击“使用 setState 切换”：

🌐 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”:

在你手动移除 DOM 元素之后，尝试使用 setState 再次显示它会导致崩溃。这是因为你已经更改了 DOM，而 React 不知道如何正确继续管理它。

🌐 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.

避免更改由 React 管理的 DOM 节点。 修改、添加子元素或从由 React 管理的元素中移除子元素，可能导致视觉结果不一致或像上文一样发生崩溃。

然而，这并不意味着你完全不能这样做。这需要谨慎。**你可以安全地修改 React 没有理由更新的 DOM 部分。**例如，如果某个 <div> 在 JSX 中总是为空，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 <div> 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.