Программная навигация через navigate

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

Инициализация и базовое использование navigate

Для начала необходимо получить доступ к функции navigate, которая предоставляется через хук useNavigate в контексте React-приложения:

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

function MyComponent() {
  const navigate = useNavigate();

  function handleClick() {
    navigate({ to: '/dashboard' });
  }

  return ;
}

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

  • navigate всегда вызывается с объектом конфигурации.
  • Основное свойство объекта — to, которое указывает путь маршрута.
  • navigate можно использовать в обработчиках событий, асинхронных функциях и эффектах.

Параметры маршрутов и передача данных

TanStack Router поддерживает маршруты с динамическими параметрами и query-параметрами. При навигации эти значения можно передавать через объект params и search:

navigate({
  to: '/users/$userId',
  params: { userId: '42' },
  search: { tab: 'settings' }
});
  • params сопоставляет динамические сегменты маршрута с конкретными значениями.
  • search автоматически формирует query-параметры (?tab=settings).
  • Такой подход гарантирует корректное построение URL без ручного конкатенирования строк.

Опции навигации

Функция navigate поддерживает несколько дополнительных опций, влияющих на поведение перехода:

  1. replace — заменяет текущую запись в истории вместо добавления новой:
navigate({ to: '/login', replace: true });
  1. state — позволяет передать состояние для маршрута, доступное через useLocation().state:
navigate({
  to: '/profile',
  state: { from: '/dashboard' }
});
  1. from — определяет базовый маршрут, относительно которого строится переход. Используется редко, но полезно при сложной вложенной навигации.

Асинхронная навигация и ожидание данных

TanStack Router поддерживает асинхронные действия перед переходом. Например, можно дождаться завершения загрузки данных или проверки условий:

async function handleSave(data) {
  await saveData(data);
  navigate({ to: '/success' });
}

Это обеспечивает плавный и контролируемый переход между страницами.

Навигация по именованным маршрутам

Помимо прямого указания пути, TanStack Router позволяет использовать именованные маршруты для улучшения читаемости кода и поддержки рефакторинга:

const router = createRouter({
  routes: [
    { path: '/dashboard', id: 'dashboard' },
    { path: '/users/$userId', id: 'userProfile' }
  ]
});

navigate({ to: 'userProfile', params: { userId: '42' } });
  • id маршрута используется вместо строки пути.
  • Такой подход минимизирует риск ошибок при изменении структуры URL.

Вложенная и относительная навигация

TanStack Router поддерживает навигацию относительно текущего маршрута:

navigate({ to: '../settings' }); // переход на родительский маршрут + settings
navigate({ to: './edit' }); // переход на дочерний маршрут edit
  • Использование . и .. позволяет создавать динамичные вложенные интерфейсы.
  • Отлично подходит для модульных приложений с глубокими деревьями маршрутов.

Навигация с сохранением скролла и поведения браузера

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

navigate({
  to: '/articles',
  replace: false
});
  • В сочетании с пользовательской логикой можно сохранять позицию скролла или реализовать анимации переходов.

Взаимодействие с защищёнными маршрутами

Программная навигация часто используется вместе с авторизацией. TanStack Router позволяет проверять доступ перед переходом:

if (!user.isAuthenticated) {
  navigate({ to: '/login', replace: true });
} else {
  navigate({ to: '/dashboard' });
}
  • Такой подход позволяет централизованно контролировать доступ к защищённым страницам без лишних перезагрузок.

Использование navigate вне компонентов React

Для случаев, когда навигация требуется вне React-компонента (например, в утилитах или сервисах), можно сохранять ссылку на объект router и вызывать метод router.navigate напрямую:

router.navigate({ to: '/home' });
  • Это обеспечивает единый источник управления навигацией и упрощает интеграцию с внешними библиотеками.
Оглавление