Обработка DOM с помощью Refs

Получение ссылки на узел

Чтобы получить доступ к узлу DOM, управляемому React, сначала импортируйте хук useRef:

import { useRef } from 'react';

Затем используйте его для объявления ссылки внутри вашего компонента:

const myRef = useRef(null);

Наконец, передайте вашу ссылку в качестве атрибута ref тегу JSX, для которого вы хотите получить узел DOM:

<div ref={myRef}>

Хук useRef возвращает объект с единственным свойством, называемым current. Изначально myRef.current будет null. Когда React создает узел DOM для этого <div>, React поместит ссылку на этот узел в myRef.current. Затем вы можете получить доступ к этому узлу DOM из своих обработчиков событий и использовать встроенные обработчики событий и встроенные браузерные API, определенные на нём.

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

Пример: Фокусировка текстового поля

В этом примере нажатие на кнопку сфокусирует поле ввода:

import { useRef } from 'react';

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

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

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

Для реализации этого:

1. Объявите inputRef с помощью хука useRef.
2. Передайте его в качестве <input ref={inputRef}>. Это сообщает React, что нужно поместить узел DOM этого <input> в inputRef.current.
3. В функции handleClick, прочтите узел DOM элемента ввода из inputRef.current и вызовите focus() на нём с помощью inputRef.current.focus().
4. Передайте обработчик события handleClick элементу <button> с помощью onClick.

Хотя манипулирование DOM является наиболее распространенным случаем использования ссылок, хук useRef можно использовать для хранения других вещей вне React, например, идентификаторов таймеров. Аналогично состоянию, ссылки сохраняются между рендерами. Ссылки похожи на переменные состояния, которые не вызывают повторное рендеринг, когда вы их устанавливаете. Подробнее о ссылках читайте в Ссылках для присвоения значений.

Пример: Прокрутка к элементу

В компоненте может быть более одной ссылки. В этом примере есть карусель из трех изображений. Каждая кнопка центрирует изображение, вызывая браузерный метод scrollIntoView() на соответствующем узле DOM:

import { useRef } from 'react';

export default function CatFriends() {
  const firstCatRef = useRef(null);
  const secondCatRef = useRef(null);
  const thirdCatRef = useRef(null);

  function handleScrollToFirstCat() {
    firstCatRef.current.scrollIntoView({
      behavior: 'smooth',
      block: 'nearest',
      inline: 'center'
    });
  }

  function handleScrollToSecondCat() {
    secondCatRef.current.scrollIntoView({
      behavior: 'smooth',
      block: 'nearest',
      inline: 'center'
    });
  }

  function handleScrollToThirdCat() {
    thirdCatRef.current.scrollIntoView({
      behavior: 'smooth',
      block: 'nearest',
      inline: 'center'
    });
  }

  return (
    <>
      <nav>
        <button onClick={handleScrollToFirstCat}>
          Neo
        </button>
        <button onClick={handleScrollToSecondCat}>
          Millie
        </button>
        <button onClick={handleScrollToThirdCat}>
          Bella
        </button>
      </nav>
      <div>
        <ul>
          <li>
            <img
              src="https://placecats.com/neo/300/200"
              alt="Neo"
              ref={firstCatRef}
            />
          </li>
          <li>
            <img
              src="https://placecats.com/millie/200/200"
              alt="Millie"
              ref={secondCatRef}
            />
          </li>
          <li>
            <img
              src="https://placecats.com/bella/199/200"
              alt="Bella"
              ref={thirdCatRef}
            />
          </li>
        </ul>
      </div>
    </>
  );
}

<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[9])}>Bella</button>
      </nav>
      <div>
        <ul>
          {catList.map((cat) => (
            <li
              key={cat}
              ref={(node) => {
                const map = getMap();
                map.set(cat, node);

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

function setupCatList() {
  const catList = [];
  for (let i = 0; i < 10; i++) {
    catList.push("https://loremflickr.com/320/240/cat?lock=" + i);
  }

  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 другого компонента

Когда вы помещаете ссылку на встроенный компонент, который выводит браузерный элемент, как <input />, React установит свойство current этой ссылки на соответствующий узел DOM (например, фактический <input /> в браузере).

Однако, если вы попытаетесь поместить ссылку на ваш собственный компонент, как <MyInput />, по умолчанию вы получите null. Вот пример, демонстрирующий это. Обратите внимание, как нажатие на кнопку не фокусирует поле ввода:

import { useRef } from 'react';

function MyInput(props) {
  return <input {...props} />;
}

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

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

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

Чтобы помочь вам заметить проблему, React также выводит ошибку в консоль:

Это происходит потому, что по умолчанию React не позволяет компоненту получить доступ к узлам DOM других компонентов. Даже не для собственных дочерних элементов! Это сделано намеренно. Ссылки — это аварийный выход, который следует использовать с осторожностью. Ручное манипулирование узлами DOM другого компонента делает ваш код еще более хрупким.

Вместо этого компоненты, которые хотят экспонировать свои узлы DOM, должны заявить об этом. Компонент может указать, что он «передает» свою ссылку одному из своих дочерних элементов. Вот как MyInput может использовать API forwardRef:

const MyInput = forwardRef((props, ref) => {
  return <input {...props} ref={ref} />;
});

Вот как это работает:

1. <MyInput ref={inputRef} /> сообщает React поместить соответствующий узел DOM в inputRef.current. Однако, за этим стоит компонент MyInput, который должен заявить об этом — по умолчанию он этого не делает.
2. Компонент MyInput объявляется с помощью forwardRef. Это заставляет его принимать inputRef из выше как второй ref аргумент, который объявляется после props.
3. Сам MyInput передает полученное ref компоненту <input> внутри него.

Теперь нажатие на кнопку для фокусировки поля ввода работает:

import { forwardRef, useRef } from 'react';

const MyInput = forwardRef((props, ref) => {
  return <input {...props} ref={ref} />;
});

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

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

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

В системах проектирования распространённым шаблоном является передача ссылок для низкоуровневых компонентов, таких как кнопки, поля ввода и так далее. С другой стороны, высокоуровневые компоненты, такие как формы, списки или разделы страниц, обычно не экспонируют свои узлы DOM, чтобы избежать случайных зависимостей от структуры DOM.

import {
  forwardRef, 
  useRef, 
  useImperativeHandle
} from 'react';

const MyInput = forwardRef((props, ref) => {
  const realInputRef = useRef(null);
  useImperativeHandle(ref, () => ({
    // Only expose focus and nothing else
    focus() {
      realInputRef.current.focus();
    },
  }));
  return <input {...props} 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 прикрепляет ссылки

В React каждое обновление разделено на две фазы:

• Во время рендеринга React вызывает ваши компоненты, чтобы определить, что должно быть на экране.
• Во время коммита React применяет изменения к DOM.

В целом, вы не должны обращаться к ссылкам во время рендеринга. Это относится и к ссылкам, содержащим узлы DOM. Во время первого рендеринга узлы DOM ещё не созданы, поэтому ref.current будет null. А во время рендеринга обновлений узлы DOM ещё не обновлены. Поэтому слишком рано их читать.

React устанавливает ref.current во время коммита. Прежде чем обновить DOM, React устанавливает затронутые ref.current значения в null. После обновления DOM React немедленно устанавливает их на соответствующие узлы DOM.

Обычно вы будете получать доступ к ссылкам из обработчиков событий. Если вам нужно что-то сделать со ссылкой, но нет конкретного события, для этого может потребоваться эффект. Мы рассмотрим эффекты на следующих страницах.

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 с помощью refs

Refs — это возможность выйти за пределы React. Их следует использовать только тогда, когда нужно «выйти за пределы React». Общие примеры включают управление фокусом, положением прокрутки или вызов браузерных API, которые React не предоставляет.

Если вы ограничиваетесь ненаносящими изменений действиями, такими как фокусировка и прокрутка, проблем возникнуть не должно. Однако, если вы попытаетесь изменить DOM вручную, вы рискуете столкнуться с конфликтами с изменениями, которые вносит React.

Чтобы проиллюстрировать эту проблему, в данном примере представлено приветственное сообщение и две кнопки. Первая кнопка переключает своё отображение с помощью условного рендеринга и состояния, как обычно делается в React. Вторая кнопка использует remove() API DOM для принудительного удаления из DOM вне контроля React.

Попробуйте несколько раз нажать кнопку «Переключить с помощью setState». Сообщение должно исчезать и снова появляться. Затем нажмите «Удалить из DOM». Это принудительно удалит его. Наконец, нажмите «Переключить с помощью setState»:

import { useState, useRef } from 'react';

export default function Counter() {
  const [show, setShow] = useState(true);
  const ref = useRef(null);

  return (
    <div>
      <button
        onClick={() => {
          setShow(!show);
        }}>
        Toggle with setState
      </button>
      <button
        onClick={() => {
          ref.current.remove();
        }}>
        Remove from the DOM
      </button>
      {show && <p ref={ref}>Hello world</p>}
    </div>
  );
}

После того как вы вручную удалили элемент DOM, попытка использовать setState для его повторного отображения приведёт к сбою. Это происходит потому, что вы изменили DOM, и React не знает, как продолжать его правильное управление.

Избегайте изменения узлов DOM, управляемых React. Изменение, добавление или удаление дочерних элементов в элементах, управляемых React, может привести к несогласованным визуальным результатам или сбоям, как показано выше.

Однако это не означает, что вы не можете этого делать вообще. Это требует осторожности. Можно безопасно изменять части DOM, которые React не должен обновлять. Например, если какой-либо <div> всегда пуст в JSX, React не будет иметь причин затрагивать его список дочерних элементов. Поэтому безопасно добавлять или удалять элементы там вручную.

import { useState, useRef } from 'react';

export default function VideoPlayer() {
  const [isPlaying, setIsPlaying] = useState(false);

  function handleClick() {
    const nextIsPlaying = !isPlaying;
    setIsPlaying(nextIsPlaying);
  }

  return (
    <>
      <button onClick={handleClick}>
        {isPlaying ? 'Pause' : 'Play'}
      </button>
      <video width="250">
        <source
          src="https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4"
          type="video/mp4"
        />
      </video>
    </>
  )
}