useMatches для информации о совпадениях

useMatches — это хук из библиотеки TanStack Router, предназначенный для получения информации о всех совпадениях маршрутов на текущем пути. Он возвращает массив объектов, каждый из которых соответствует маршруту, совпавшему с текущим URL. Этот массив особенно полезен для извлечения данных, метаданных или контекста, предоставляемого различными уровнями маршрутов.

Структура возвращаемого значения

Каждый элемент массива, возвращаемого useMatches, содержит несколько ключевых свойств:

  • id — уникальный идентификатор маршрута.
  • pathname — путь маршрута относительно корня.
  • params — объект параметров маршрута, извлечённых из URL.
  • data — асинхронные или синхронные данные, загруженные маршрутом через loader.
  • handle — произвольные данные, заданные для маршрута через свойство handle. Используется для передачи дополнительной информации, например, метаданных.

Пример объекта:

{
  id: 'user-profile',
  pathname: '/users/42',
  params: { userId: '42' },
  data: { name: 'Alice', age: 30 },
  handle: { requiresAuth: true }
}

Основные сценарии использования

  1. Доступ к данным маршрутов useMatches позволяет получить данные, загруженные на любом уровне вложенности маршрута. Это особенно удобно, если компонент расположен глубоко в дереве маршрутов, но ему нужны данные с верхнего уровня.
import { useMatches } from '@tanstack/router';

function UserProfile() {
  const matches = useMatches();
  const userData = matches.find(match => match.id === 'user-profile')?.data;

  return (
    <div>
      <h1>{userData?.name}</h1>
      <p>Возраст: {userData?.age}</p>
    </div>
  );
}
  1. Доступ к глобальным метаданным Свойство handle позволяет хранить информацию, которая нужна не для рендеринга данных, а для конфигурации компонентов. Например, проверка авторизации или настройка заголовков страницы.
const matches = useMatches();
const requiresAuth = matches.some(match => match.handle?.requiresAuth);

if (requiresAuth) {
  // логика проверки авторизации
}
  1. Динамическая генерация хлебных крошек Используя массив совпадений маршрутов, можно создавать хлебные крошки, которые соответствуют текущему пути.
function Breadcrumbs() {
  const matches = useMatches();

  return (
    <nav>
      {matches.map(match => (
        <span key={match.id}>
          <a href={match.pathname}>{match.handle?.breadcrumb || match.id}</a> /
        </span>
      ))}
    </nav>
  );
}

Особенности поведения

  • useMatches всегда возвращает совпадения для текущего маршрута, включая родительские маршруты.
  • Если URL не совпадает ни с одним маршрутом, массив будет пустым.
  • data обновляется автоматически при изменении маршрута или при повторной загрузке данных через loader.

Отличие от useMatch

useMatch возвращает информацию только о конкретном маршруте, который совпал с текущим URL, тогда как useMatches предоставляет полную цепочку всех совпадений. Это делает useMatches предпочтительным для задач, где нужен доступ к данным из разных уровней маршрутов одновременно.

Рекомендации по использованию

  • Использовать useMatches для компонентов, которые находятся глубоко в дереве маршрутов, чтобы не передавать данные через props.
  • Извлекать только необходимые данные из массива совпадений, чтобы избежать лишних вычислений.
  • Для динамических UI-элементов, таких как хлебные крошки или настройка заголовков страницы, хранить конфигурационные данные в handle.

Пример полного сценария

import { useMatches } from '@tanstack/router';

function PageHeader() {
  const matches = useMatches();

  const pageTitle = matches
    .map(match => match.handle?.title)
    .filter(Boolean)
    .join(' - ');

  const requiresAuth = matches.some(match => match.handle?.requiresAuth);

  if (requiresAuth) {
    // проверка авторизации
  }

  return <h1>{pageTitle}</h1>;
}

В этом примере комбинируются несколько возможностей useMatches: получение метаданных title для заголовка страницы и проверка условий через handle. Такой подход обеспечивает консистентность данных на всех уровнях маршрутов и упрощает поддержку кода.

Оглавление