Работа с DOM с помощью Refs

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

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

import { useRef } from 'react';

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

const myRef = useRef(null);

Наконец, передайте свой ref в качестве атрибута 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 является наиболее распространённым случаем использования ref, хук useRef может использоваться для хранения других вещей вне React, например, идентификаторов таймеров. Подобно состоянию, ref сохраняется между рендерами. Refs — это переменные состояния, которые не вызывают перерендеринг при их установке. Подробнее о ref в Ссылка на значения с помощью Refs.

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

В компоненте может быть больше одного ref. В этом примере есть карусель из трёх изображений. Каждая кнопка центрирует изображение, вызывая браузерный метод 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();
                if (node) {
                  map.set(cat, node);
                } else {
                  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();
    if (node) {
      // Add to the Map
      map.set(cat, node);
    } else {
      // Remove from the Map
      map.delete(cat);
    }
  }}
>

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

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

Однако, если вы попытаетесь установить ref на свой компонент, например, <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 других компонентов. Даже не к собственным дочерним! Это сделано намеренно. Refs — это аварийный выход, который следует использовать с осторожностью. Ручное изменение узлов DOM другого компонента делает ваш код ещё более хрупким.

Вместо этого компоненты, которые хотят экспонировать свои узлы DOM, должны выбрать это поведение. Компонент может указать, что он «передаёт» свой ref одному из своих дочерних элементов. Вот как 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>
    </>
  );
}

В системах дизайна распространённый паттерн — низкоуровневые компоненты, такие как кнопки, поля ввода и т. д., передают свои ref в узлы DOM. С другой стороны, высокоуровневые компоненты, такие как формы, списки или разделы страниц, обычно не раскрывают свои узлы 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 вызывает ваши компоненты, чтобы выяснить, что должно отображаться на экране.
• Во время commit React применяет изменения к DOM.

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

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

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

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». Типичные примеры — управление фокусом, положением прокрутки или вызов браузерных 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>
    </>
  )
}