Навигация по истории: назад и вперед

TanStack Router предоставляет гибкий и мощный механизм управления историей навигации, позволяя точно контролировать переходы между страницами и состояние приложения. История в TanStack Router основана на концепции history objects, которые могут быть браузерными, памятью или кастомными. Основные методы для управления историей включают navigate, go, back, forward и replace.

Метод navigate

Метод navigate используется для программного перехода на другой маршрут. Его синтаксис:

router.navigate({
  to: '/users/42',
  replace: false,
  params: { id: 42 },
  search: { filter: 'active' }
});

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

  • to — путь маршрута или объект маршрута.
  • replace — если true, переход заменяет текущую запись в истории, не создавая новую.
  • params — динамические параметры маршрута.
  • search — параметры query string, передаваемые в URL.

Методы back и forward

back и forward предоставляют доступ к стеку истории браузера, аналогично стандартным window.history.back() и window.history.forward(). Используются для навигации в пределах истории без явного указания маршрута:

router.back();    // Переход на предыдущую страницу
router.forward(); // Переход на следующую страницу

Эти методы полезны при реализации кнопок “Назад” и “Вперед” в пользовательском интерфейсе.

Метод go

Метод go позволяет перемещаться по истории на определённое количество шагов:

router.history.go(-2); // Возврат на две страницы назад
router.history.go(3);  // Переход на три страницы вперёд

Особенности использования:

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

Замена текущего маршрута: replace

Использование replace в navigate позволяет обновлять URL без добавления новой записи в историю. Это важно для страниц с динамическими параметрами или фильтрами, когда не нужно создавать новые шаги в истории при каждом изменении состояния:

router.navigate({
  to: '/search',
  replace: true,
  search: { query: 'javascript' }
});

Это предотвращает накопление избыточных записей в истории и обеспечивает более предсказуемое поведение кнопки “Назад”.

Работа с state истории

TanStack Router позволяет сохранять произвольное состояние для каждого шага истории, аналогично history.state в браузере:

router.navigate({
  to: '/profile',
  state: { scrollPosition: 300 }
});

Доступ к state осуществляется через объект router.state или через хуки маршрута:

const state = router.state;
console.log(state.scrollPosition); // 300

Использование состояния полезно для сохранения данных интерфейса, таких как позиции прокрутки или состояние фильтров при возврате на предыдущие страницы.

События изменения истории

TanStack Router предоставляет подписку на события изменения истории:

router.subscribe(({ location, action }) => {
  console.log(action, location.pathname);
});

Параметры:

  • location — текущий объект маршрута, включая путь, параметры и query.
  • action — тип действия: push, replace, pop.

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

Программное управление навигацией при асинхронных действиях

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

async function submitForm(data) {
  await api.save(data);
  router.navigate({ to: '/success', replace: true });
}

Использование replace предотвращает лишние записи в истории, если пользователь часто отправляет формы.

Интеграция с кнопками интерфейса

Программная навигация легко комбинируется с элементами UI:

<button onCl ick={() => router.back()}>Назад</button>
<button onCl ick={() => router.forward()}>Вперед</button>
<button onCl ick={() => router.navigate({ to: '/dashboard' })}>На главную</button>

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

Обработка переходов и отмена навигации

TanStack Router поддерживает хуки beforeUnload и beforeNavigate, которые позволяют предотвратить переход при определённых условиях:

router.beforeNavigate(({ cancel, next }) => {
  if (!formSaved) {
    cancel();
  }
});

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

Синхронизация с внешними библиотеками истории

TanStack Router может работать с любыми объектами истории, совместимыми с history API. Это позволяет интегрировать роутер с серверным рендерингом, React Native или Electron, обеспечивая единое управление навигацией во всех окружениях:

import { createMemoryHistory } from 'history';

const memoryHistory = createMemoryHistory();
const router = new Router({ history: memoryHistory });

Использование памяти вместо браузерной истории позволяет тестировать и управлять навигацией вне стандартного браузера.

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

Оглавление