Навигация с параметрами

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

Динамические сегменты маршрута

Динамические сегменты маршрута обозначаются с помощью двоеточия : в пути. Например:

const router = createRouter({
  routes: [
    {
      path: '/user/:userId',
      component: UserPage,
    },
  ],
});
  • :userId — это динамический параметр, который можно извлечь и использовать внутри компонента.
  • При переходе на /user/42, userId автоматически получает значение "42".

Доступ к параметрам осуществляется через хук useParams:

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

function UserPage() {
  const params = useParams();
  console.log(params.userId); // "42"
  return <div>Пользователь: {params.userId}</div>;
}

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

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

Обязательные и необязательные параметры

TanStack Router поддерживает как обязательные, так и необязательные параметры. Обязательные параметры указываются стандартным образом (:param), а необязательные параметры можно описывать через вопросительный знак в схеме маршрута:

{
  path: '/search/:query?',
  component: SearchPage,
}
  • Если URL /search/ — query будет undefined.
  • Если URL /search/javascript — query будет "javascript".

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

query-параметры

Помимо сегментов пути, TanStack Router позволяет работать с query-параметрами. Они автоматически парсятся и передаются в компонент:

const router = createRouter({
  routes: [
    {
      path: '/products',
      component: ProductsPage,
    },
  ],
});

Для навигации с query-параметрами используется метод router.navigate:

router.navigate({ to: '/products', search: { category: 'books', sort: 'price' } });
  • URL примет вид /products?category=books&sort=price.
  • В компоненте можно получить параметры через хук useSearch:
import { useSearch } from '@tanstack/router';

function ProductsPage() {
  const search = useSearch();
  console.log(search.category); // "books"
  console.log(search.sort);     // "price"
}

Особенности query-параметров:

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

Вложенные маршруты и параметры

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

const router = createRouter({
  routes: [
    {
      path: '/dashboard/:userId',
      component: DashboardLayout,
      children: [
        {
          path: 'settings',
          component: SettingsPage,
        },
      ],
    },
  ],
});
  • Параметр userId доступен как в DashboardLayout, так и в SettingsPage.
  • Используется единая система useParams, которая объединяет параметры всех уровней вложенности.

Навигация с параметрами программно

Программная навигация позволяет передавать параметры прямо при вызове router.navigate:

router.navigate({
  to: '/user/:userId',
  params: { userId: '42' },
});
  • Маршрутизатор автоматически заменяет :userId на значение из params.
  • Поддерживается навигация с query-параметрами одновременно:
router.navigate({
  to: '/user/:userId',
  params: { userId: '42' },
  search: { tab: 'profile' },
});
  • URL будет /user/42?tab=profile.

Валидация и типизация параметров

TanStack Router позволяет задавать схемы валидации для параметров с помощью библиотеки zod или собственного механизма:

import { z } from 'zod';

const userRoute = {
  path: '/user/:userId',
  component: UserPage,
  paramsSchema: z.object({
    userId: z.string().regex(/^\d+$/),
  }),
};
  • Параметр userId должен быть числом в виде строки.
  • Невалидные значения маршрутизатор может обрабатывать через fallback-компоненты или редиректы.

Использование параметров для подгрузки данных

Часто параметры маршрутов напрямую связывают с запросами к API:

function UserPage() {
  const { userId } = useParams();
  const { data, isLoading } = useQuery(['user', userId], () =>
    fetch(`/api/users/${userId}`).then(res => res.json())
  );

  if (isLoading) return <div>Загрузка...</div>;
  return <div>Имя пользователя: {data.name}</div>;
}
  • Динамические параметры позволяют получать нужные данные без создания отдельного состояния для каждого URL.
  • Используется совместно с библиотеками для управления состоянием и кеширования, такими как React Query.

Итоговая схема взаимодействия

  1. Динамические сегменты → путь с параметрами /:param.
  2. Query-параметры → дополнительная информация через ?key=value.
  3. Вложенные маршруты → передача параметров вниз по дереву компонентов.
  4. Программная навигация → router.navigate({ to, params, search }).
  5. Валидация и типизация → предотвращение некорректных данных.
  6. Подгрузка данных → связывание URL с API-запросами.

Использование этих возможностей делает TanStack Router гибким инструментом для построения сложных SPA с управляемой и предсказуемой навигацией.

Оглавление