Параметры маршрутов

В TanStack Router параметры маршрутов используются для передачи динамических значений через URL и позволяют строить гибкую навигацию без необходимости повторной отрисовки компонентов на уровне всего приложения. Параметры делятся на path parameters и search parameters.

Path parameters

Path parameters (параметры пути) определяются в маршруте через двоеточие :. Они позволяют создавать маршруты с переменными сегментами.

Пример маршрута с path parameter:

import { createRouter, Route } from '@tanstack/router';

const userRoute = new Route({
  path: '/users/:userId',
  component: UserProfile,
});
  • :userId – динамическая часть URL.
  • Значение параметра доступно через хук useParams():
import { useParams } from '@tanstack/router';

function UserProfile() {
  const { userId } = useParams();
  return <div>Пользователь с ID: {userId}</div>;
}

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

  1. Обязательные параметры: любой параметр в пути, указанный через :, является обязательным. Если значение отсутствует, маршрут не совпадает.
  2. Совместимость с nested routes: параметры родительского маршрута доступны во всех дочерних маршрутах.
  3. Типизация: в TypeScript можно указать тип параметра через generic:
const userRoute = new Route<{ userId: string }>({
  path: '/users/:userId',
  component: UserProfile,
});

Search parameters

Search parameters (параметры поиска) передаются через строку запроса, после ? в URL. В TanStack Router они определяются через объект searchSchema при создании маршрута:

import { z } from 'zod';

const searchRoute = new Route({
  path: '/products',
  component: ProductsPage,
  searchSchema: z.object({
    category: z.string().optional(),
    page: z.number().default(1),
  }),
});
  • searchSchema использует Zod для валидации и приведения типов.
  • Значения доступны через хук useSearchParams():
import { useSearchParams } from '@tanstack/router';

function ProductsPage() {
  const { category, page } = useSearchParams();
  return <div>Категория: {category}, Страница: {page}</div>;
}

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

  1. Необязательность: параметры поиска могут быть опциональными, по умолчанию значения задаются через default.
  2. Синхронизация с URL: любые изменения searchParams автоматически обновляют URL без полной перезагрузки страницы.
  3. Типизация и валидация: Zod гарантирует корректный тип данных, что снижает количество ошибок при обработке параметров.

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

Вложенные маршруты могут наследовать параметры от родителя:

const userRoute = new Route({
  path: '/users/:userId',
  component: UserLayout,
});

const userSettingsRoute = new Route({
  path: 'settings',
  parent: userRoute,
  component: UserSettings,
});
  • В UserSettings доступны все параметры родителя (userId) через useParams().
  • Полный путь к дочернему маршруту формируется автоматически: /users/:userId/settings.

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

Для перехода к маршруту с параметрами используется router.navigate():

router.navigate({
  to: '/users/:userId',
  params: { userId: '123' },
  search: { tab: 'activity' },
});
  • params – объект для path parameters.
  • search – объект для search parameters.
  • TanStack Router автоматически подставляет значения в URL и сериализует параметры поиска.

Обработка ошибок параметров

Некорректные или отсутствующие параметры можно обрабатывать через validate функцию или через searchSchema:

const userRoute = new Route({
  path: '/users/:userId',
  component: UserProfile,
  validate: ({ params }) => {
    if (!/^\d+$/.test(params.userId)) {
      return { redirectTo: '/users' };
    }
  },
});
  • validate позволяет проверять значения path parameters и перенаправлять пользователя при ошибке.
  • Для search parameters валидация выполняется автоматически через Zod.

Динамические маршруты с несколькими параметрами

Можно комбинировать несколько path и search parameters:

const blogRoute = new Route({
  path: '/blogs/:blogId/posts/:postId',
  component: BlogPost,
  searchSchema: z.object({
    highlight: z.boolean().optional(),
  }),
});
  • Доступ к параметрам:
const { blogId, postId } = useParams();
const { highlight } = useSearchParams();
  • Позволяет создавать глубокую, но типизированную структуру URL.

Основные рекомендации по параметрам маршрутов

  • Явно указывайте типы для path и search parameters, особенно в TypeScript.
  • Используйте Zod для валидации search parameters.
  • Наследуйте параметры родителя для вложенных маршрутов, чтобы избежать дублирования.
  • Старайтесь различать path и search параметры: динамика маршрута — в path, фильтры и сортировка — в search.
  • Обрабатывайте некорректные параметры через validate или searchSchema, чтобы избежать ошибок рендеринга.

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

Оглавление