Утилитарные функции

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

useMatch и работа с активными маршрутами

Функция useMatch используется для получения информации о текущем активном маршруте и его параметрах. Она возвращает объект с подробной информацией о маршруте, включая его путь, параметры, состояние и сопоставленные родительские маршруты.

Пример использования:

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

const match = useMatch('/users/:userId');
console.log(match.params.userId); // Получение значения параметра userId

Ключевые моменты:

  • Позволяет проверять, активен ли конкретный маршрут.
  • Предоставляет доступ к параметрам маршрута без необходимости ручного разбора URL.
  • Работает как с вложенными маршрутами, так и с динамическими сегментами.

Утилита navigate обеспечивает программный переход между маршрутами. Она поддерживает навигацию с сохранением истории, заменой текущего состояния и передачей данных через state.

Пример использования:

import { router } from './router';

router.navigate({
  to: '/dashboard',
  replace: true,
  state: { from: 'login' }
});

Особенности:

  • replace: заменяет текущую запись истории, вместо добавления новой.
  • state: позволяет передавать произвольные данные, которые будут доступны в целевом маршруте.
  • Обеспечивает поддержку динамических параметров.

parsePath и buildPath для работы с URL

Эти функции позволяют преобразовывать строковые пути в объектное представление и обратно. parsePath разбивает URL на сегменты, query-параметры и hash, а buildPath собирает URL из этих данных.

Пример:

import { parsePath, buildPath } from '@tanstack/router';

const parsed = parsePath('/users/123?active=true#section');
console.log(parsed); 
// { pathname: '/users/123', search: '?active=true', hash: '#section' }

const url = buildPath({ pathname: '/users/123', search: '?active=true', hash: '#section' });
console.log(url); // '/users/123?active=true#section'

Преимущества:

  • Упрощает манипуляции с параметрами URL.
  • Позволяет безопасно формировать ссылки с динамическими сегментами и query-параметрами.
  • Обеспечивает совместимость с внутренними методами TanStack Router.

matchRoute для условной логики

matchRoute позволяет проверять соответствие маршрута конкретному пути. Это полезно для условного рендеринга компонентов или применения стилей к активным ссылкам.

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

const isActive = matchRoute('/users/:userId', '/users/42');
console.log(isActive); // true

Особенности:

  • Поддерживает динамические сегменты и вложенные маршруты.
  • Можно использовать в комбинации с useMatch для построения условных навигационных меню.

Работа с query-параметрами и state

TanStack Router включает утилиты для управления query-параметрами и состоянием навигации:

  • useSearchParams – хук для чтения и обновления query-параметров.
  • useLocation – возвращает объект текущего местоположения с pathname, search и hash.
  • useRouterState – позволяет сохранять и читать состояние маршрута между навигациями.

Пример обновления query-параметра:

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

const [searchParams, setSearchParams] = useSearchParams();
setSearchParams({ filter: 'active', page: 2 });

Это позволяет изменять параметры URL без перезагрузки страницы, сохраняя текущий контекст приложения.

Асинхронные утилиты

TanStack Router предоставляет функции для асинхронной загрузки данных перед переходом на маршрут:

  • loader – функция, выполняемая перед активацией маршрута для получения данных.
  • defer – позволяет загружать данные частично и рендерить страницу до завершения всех запросов.

Пример с loader:

const userLoader = async ({ params }) => {
  const response = await fetch(`/api/users/${params.userId}`);
  return response.json();
};

Эти утилиты позволяют строить маршруты с управлением загрузкой данных без лишних побочных эффектов и дублирования логики.

Резюме по ключевым утилитарным функциям

  • useMatch – получение информации о текущем маршруте и его параметрах.
  • navigate – программная навигация с поддержкой состояния и истории.
  • parsePath / buildPath – безопасная работа с URL.
  • matchRoute – проверка соответствия маршрута.
  • Хуки для query и состояния маршрута (useSearchParams, useLocation, useRouterState).
  • Асинхронные загрузчики данных (loader, defer).

Эти утилиты делают TanStack Router гибким инструментом для построения сложной и предсказуемой маршрутизации, обеспечивая удобное взаимодействие с URL, параметрами и состоянием приложения.

Оглавление