hydrateRoot

const root = hydrateRoot(domNode, reactNode, options?)

• Справочник
  • hydrateRoot(domNode, reactNode, options?)
  • root.render(reactNode)
  • root.unmount()
• Использование
  • Гидратация HTML, сгенерированного на сервере
  • Гидратация всего документа
  • Подавление неизбежных ошибок несоответствия гидратации
  • Обработка различного содержимого клиента и сервера
  • Обновление компонента корневого узла гидратации
  • Отображение диалогового окна для неперехваченных ошибок
  • Отображение ошибок граничных элементов
  • Отображение диалогового окна для восстанавливаемых ошибок несоответствия гидратации
• Отладка
  • Ошибка: «Вы передали второй аргумент в root.render»

Справочник

hydrateRoot(domNode, reactNode, options?)

Вызов hydrateRoot для «присоединения» React к существующему HTML, который уже был отрисован React в среде сервера.

import { hydrateRoot } from 'react-dom/client';

const domNode = document.getElementById('root');
const root = hydrateRoot(domNode, reactNode);

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

См. дополнительные примеры ниже.

Параметры

• domNode: Элемент DOM, который был отрисован как корневой элемент на сервере.

• reactNode: «Узел React», используемый для отрисовки существующего HTML. Обычно это фрагмент JSX, например <App />, который был отрисован с помощью метода ReactDOM Server, такого как renderToPipeableStream(<App />).

• необязательно options: Объект с параметрами для этого корня React.

  • Только Canary необязательно onCaughtError: Обратный вызов, вызываемый, когда React перехватывает ошибку в граничном элементе. Вызывается с ошибкой error, перехваченной граничным элементом, и объектом errorInfo, содержащим componentStack.
  • Только Canary необязательно onUncaughtError: Обратный вызов, вызываемый при возникновении ошибки, не перехваченной граничным элементом. Вызывается с ошибкой error, которая была выброшена, и объектом errorInfo, содержащим componentStack.
  • необязательно onRecoverableError: Обратный вызов, вызываемый, когда React автоматически восстанавливается от ошибок. Вызывается с ошибкой error, выброшенной React, и объектом errorInfo, содержащим componentStack. Некоторые восстанавливаемые ошибки могут включать первопричину ошибки в виде error.cause.
  • необязательно identifierPrefix: Префикс строки, используемый React для ID, генерируемых useId. Полезно для предотвращения конфликтов при использовании нескольких корней на одной странице. Должен совпадать с префиксом, использованным на сервере.

Возвращаемое значение

hydrateRoot возвращает объект с двумя методами: render и unmount.

Ограничения

• hydrateRoot() ожидает, что содержимое, которое было отрисовано, будет идентично содержимому, сгенерированному на сервере. Несоответствия следует рассматривать как ошибки и исправлять их.
• В режиме разработки React предупреждает о несоответствиях при гидратации. Нет гарантии, что различия в атрибутах будут исправлены в случае несоответствия. Это важно по причинам производительности, поскольку в большинстве приложений несоответствия встречаются редко, и поэтому проверка всей разметки была бы чрезмерно затратной.
• Вероятно, у приложения будет только один hydrateRoot вызов. Если вы используете фреймворк, он, возможно, выполнит этот вызов за вас.
• Если ваше приложение рендерится на клиенте без предварительно отрисованного HTML, использование hydrateRoot() не поддерживается. Используйте createRoot() вместо этого.

root.render(reactNode)

Вызов root.render для обновления компонента React внутри гидратированного корня React для элемента DOM браузера.

root.render(<App />);

React обновит <App /> в гидратированном root.

См. дополнительные примеры ниже.

Параметры

• reactNode: «Узел React», который вы хотите обновить. Обычно это фрагмент JSX, например <App />, но вы также можете передать элемент React, созданный с помощью createElement(), строку, число, null, или undefined.

Возвращаемое значение

root.render возвращает undefined.

Ограничения

• Если вы вызываете root.render до завершения гидратации корня, React очистит существующее содержимое, сгенерированное на сервере, и переключит весь корень на рендеринг на клиенте.

root.unmount()

Вызов root.unmount для уничтожения отрисованного дерева внутри корня React.

root.unmount();

В приложении, полностью построенном с помощью React, обычно не будет вызовов root.unmount.

Это в основном полезно, если узел DOM корневого элемента React (или любой из его предков) может быть удален из DOM другим кодом. Например, представьте себе панель вкладок jQuery, которая удаляет неактивные вкладки из DOM. Если вкладка удаляется, всё внутри неё (включая корни React внутри) также будет удалено из DOM. Вам необходимо указать React «остановить» управление содержимым удалённого корня, вызвав root.unmount. В противном случае компоненты внутри удалённого корня не очистят ресурсы, такие как подписки.

Вызов root.unmount отмонтирует все компоненты в корне и «отсоединит» React от узла DOM корня, включая удаление всех обработчиков событий или состояния в дереве.

Параметры

root.unmount не принимает никаких параметров.

Возвращаемое значение

root.unmount возвращает undefined.

Ограничения

• Вызов root.unmount отмонтирует все компоненты в дереве и «отсоединит» React от узла DOM корня.

• После вызова root.unmount вы не можете вызвать root.render для корня ещё раз. Попытка вызвать root.render для отмонтированного корня вызовет ошибку «Невозможно обновить отмонтированный корень».

Использование

Гидратация HTML, сгенерированного на сервере

Если HTML вашего приложения был сгенерирован с помощью react-dom/server, вам необходимо выполнить его гидратацию на клиенте.

import { hydrateRoot } from 'react-dom/client';

hydrateRoot(document.getElementById('root'), <App />);

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

Для гидратации вашего приложения React «присоединит» логику ваших компонентов к исходному HTML, сгенерированному сервером. Гидратация превращает начальный HTML-снимок с сервера в полностью интерактивное приложение, работающее в браузере.

import './styles.css';
import { hydrateRoot } from 'react-dom/client';
import App from './App.js';

hydrateRoot(
  document.getElementById('root'),
  <App />
);

Вам не нужно вызывать hydrateRoot снова или вызывать его в других местах. С этого момента React будет управлять DOM вашего приложения. Для обновления интерфейса ваши компоненты будут использовать состояние вместо этого.

Гидратация всего документа

Приложения, полностью построенные с помощью React, могут рендерить весь документ в виде JSX, включая тег <html>:

function App() {
  return (
    <html>
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <link rel="stylesheet" href="/styles.css"></link>
        <title>My app</title>
      </head>
      <body>
        <Router />
      </body>
    </html>
  );
}

Для гидратации всего документа передайте глобальный объект document в качестве первого аргумента в hydrateRoot:

import { hydrateRoot } from 'react-dom/client';
import App from './App.js';

hydrateRoot(document, <App />);

Подавление неизбежных ошибок несоответствия гидратации

Если атрибут или текстовое содержимое отдельного элемента неизбежно различаются между сервером и клиентом (например, метка времени), вы можете отключить предупреждение о несоответствии гидратации.

Для отключения предупреждений о гидратации для элемента добавьте suppressHydrationWarning={true}:

export default function App() {
  return (
    <h1 suppressHydrationWarning={true}>
      Current Date: {new Date().toLocaleDateString()}
    </h1>
  );
}

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

Обработка различного содержимого клиента и сервера

Если вам преднамеренно нужно отобразить что-то другое на сервере и клиенте, можно выполнить двукратное рендеринг. Компоненты, которые отображают что-то другое на клиенте, могут считывать переменную состояния состояния, например isClient, которую можно установить в true в эффекте:

import { useState, useEffect } from "react";

export default function App() {
  const [isClient, setIsClient] = useState(false);

  useEffect(() => {
    setIsClient(true);
  }, []);

  return (
    <h1>
      {isClient ? 'Is Client' : 'Is Server'}
    </h1>
  );
}

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

Обновление компонента корневого узла после гидратации

После завершения гидратации корневого узла можно вызвать root.render для обновления корневого компонента React. В отличие от createRoot, обычно это не нужно, поскольку начальное содержимое уже было отображено как HTML.

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

import { hydrateRoot } from 'react-dom/client';
import './styles.css';
import App from './App.js';

const root = hydrateRoot(
  document.getElementById('root'),
  <App counter={0} />
);

let i = 0;
setInterval(() => {
  root.render(<App counter={i} />);
  i++;
}, 1000);

Нечасто вызывать root.render для гидратированного корневого узла. Обычно вы будете обновлять состояние внутри одного из компонентов.

Отображение диалогового окна для неперехваченных ошибок

По умолчанию React будет регистрировать все неперехваченные ошибки в консоли. Для реализации собственной системы отслеживания ошибок можно указать необязательный параметр onUncaughtError для корневого узла:

import { hydrateRoot } from 'react-dom/client';

const root = hydrateRoot(
  document.getElementById('root'),
  <App />,
  {
    onUncaughtError: (error, errorInfo) => {
      console.error(
        'Uncaught error',
        error,
        errorInfo.componentStack
      );
    }
  }
);
root.render(<App />);

Параметр onUncaughtError — это функция, вызываемая с двумя аргументами:

1. Ошибка error, которая была сгенерирована.
2. Объект errorInfo, содержащий componentStack ошибки.

Для отображения диалоговых окон ошибок можно использовать параметр onUncaughtError для корневого узла:

import { hydrateRoot } from "react-dom/client";
import App from "./App.js";
import {reportUncaughtError} from "./reportError";
import "./styles.css";
import {renderToString} from 'react-dom/server';

const container = document.getElementById("root");
const root = hydrateRoot(container, <App />, {
  onUncaughtError: (error, errorInfo) => {
    if (error.message !== 'Known error') {
      reportUncaughtError({
        error,
        componentStack: errorInfo.componentStack
      });
    }
  }
});

Отображение ошибок граничных значений

По умолчанию React будет регистрировать все ошибки, перехваченные границей ошибок, в console.error. Чтобы переопределить это поведение, можно указать необязательный параметр onCaughtError для корневого узла, предназначенный для ошибок, перехваченных границей ошибок:

import { hydrateRoot } from 'react-dom/client';

const root = hydrateRoot(
  document.getElementById('root'),
  <App />,
  {
    onCaughtError: (error, errorInfo) => {
      console.error(
        'Caught error',
        error,
        errorInfo.componentStack
      );
    }
  }
);
root.render(<App />);

Параметр onCaughtError — это функция, вызываемая с двумя аргументами:

1. Ошибка error, которая была перехвачена границей.
2. Объект errorInfo, содержащий componentStack ошибки.

Для отображения диалоговых окон ошибок или фильтрации известных ошибок из журналов можно использовать параметр onCaughtError для корневого узла:

import { hydrateRoot } from "react-dom/client";
import App from "./App.js";
import {reportCaughtError} from "./reportError";
import "./styles.css";

const container = document.getElementById("root");
const root = hydrateRoot(container, <App />, {
  onCaughtError: (error, errorInfo) => {
    if (error.message !== 'Known error') {
      reportCaughtError({
        error,
        componentStack: errorInfo.componentStack
      });
    }
  }
});

Отображение диалогового окна для ошибок восстанавливаемых несоответствий при гидратации

При обнаружении несоответствия при гидратации React автоматически попытается восстановиться, выполнив рендеринг на клиенте. По умолчанию React будет регистрировать ошибки несоответствия при гидратации в console.error. Чтобы переопределить это поведение, можно указать необязательный параметр onRecoverableError для корневого узла:

import { hydrateRoot } from 'react-dom/client';

const root = hydrateRoot(
  document.getElementById('root'),
  <App />,
  {
    onRecoverableError: (error, errorInfo) => {
      console.error(
        'Caught error',
        error,
        error.cause,
        errorInfo.componentStack
      );
    }
  }
);

Параметр onRecoverableError — это функция, вызываемая с двумя аргументами:

1. Ошибка error, сгенерированная React. Некоторые ошибки могут содержать первопричину как error.cause.
2. Объект errorInfo, содержащий componentStack ошибки.

Для отображения диалоговых окон ошибок при несоответствиях в гидратации можно использовать параметр onRecoverableError для корневого узла:

import { hydrateRoot } from "react-dom/client";
import App from "./App.js";
import {reportRecoverableError} from "./reportError";
import "./styles.css";

const container = document.getElementById("root");
const root = hydrateRoot(container, <App />, {
  onRecoverableError: (error, errorInfo) => {
    reportRecoverableError({
      error,
      cause: error.cause,
      componentStack: errorInfo.componentStack
    });
  }
});

Отладка

Ошибка: «Вы передали второй аргумент в root.render»

Частая ошибка заключается в передаче опций для hydrateRoot в root.render(...):

Для исправления передайте параметры корневого узла в hydrateRoot(...), а не в root.render(...):

// 🚩 Wrong: root.render only takes one argument.
root.render(App, {onUncaughtError});

// ✅ Correct: pass options to createRoot.
const root = hydrateRoot(container, <App />, {onUncaughtError});