Валидация search params

TanStack Router предоставляет мощные возможности для работы с параметрами URL, включая query-параметры (search params). Одной из ключевых функций является валидация этих параметров, что позволяет гарантировать корректность данных до того, как они будут использоваться в компоненте или логике маршрута.

Основы search params

Search params — это параметры, передаваемые в URL после знака ?. Например, в URL:

/products?category=books&page=2

category и page являются search params. TanStack Router позволяет их типизировать и валидировать с помощью схем, что особенно важно при работе с динамическими страницами, где пользователь может вручную изменять URL.

Определение валидируемых параметров

Для валидации search params используется объект searchSchema, в котором задаются правила и типы каждого параметра. Пример:

import { z } from 'zod';
import { createRouter, route } from '@tanstack/router';

const productRoute = route({
  path: '/products',
  searchSchema: z.object({
    category: z.string().optional(),
    page: z.string().transform(Number).default('1'),
    sort: z.enum(['asc', 'desc']).optional(),
  }),
});

В этом примере:

  • category может быть строкой или отсутствовать.
  • page по умолчанию равен "1", но автоматически преобразуется в число.
  • sort допускает только два значения: "asc" или "desc".

Преобразование и типизация

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

Обработка ошибок валидации

Если search param не соответствует схеме, TanStack Router по умолчанию не пропустит маршрут с некорректными параметрами. Можно задать обработчик ошибок:

const productRoute = route({
  path: '/products',
  searchSchema: z.object({
    category: z.string().optional(),
    page: z.string().transform(Number),
  }),
  onSearchParamError: (error, context) => {
    console.error('Ошибка search param:', error);
    context.router.navigate({ to: '/error' });
  },
});

onSearchParamError получает объект ошибки и контекст маршрутизатора, позволяя, например, перенаправлять пользователя на страницу ошибки или показывать уведомление.

Дефолтные значения и fallback

Search params могут иметь значения по умолчанию, что предотвращает ошибки при отсутствии параметра в URL:

searchSchema: z.object({
  page: z.string().transform(Number).default('1'),
  filter: z.string().optional().default('all'),
}),

При отсутствии page или filter в URL, TanStack Router автоматически подставит указанные значения.

Динамическая генерация URL с учетом search params

С помощью валидированной схемы легко генерировать корректные ссылки, не боясь ошибочного формата параметров:

router.navigate({
  to: productRoute,
  search: {
    category: 'books',
    page: 3,
  },
});

Система автоматически проверит значения через searchSchema и преобразует их, если требуется.

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

Внутри компонента можно безопасно получать валидированные параметры:

function ProductList() {
  const { search } = useRouteLoader(productRoute);
  const { category, page } = search;

  // page уже число, category — строка или undefined
  return (
    <div>
      <h1>Категория: {category ?? 'Все'}</h1>
      <p>Страница: {page}</p>
    </div>
  );
}

Нет необходимости вручную проверять типы или обрабатывать неправильные значения — вся логика валидации вынесена в схему маршрута.

Комплексная схема для сложных параметров

Можно создавать вложенные объекты и массивы в search params:

searchSchema: z.object({
  filters: z.array(z.enum(['books', 'electronics'])).optional(),
  range: z.object({
    min: z.string().transform(Number).default('0'),
    max: z.string().transform(Number).default('100'),
  }).optional(),
}),

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

Валидация search params в TanStack Router обеспечивает надежность и предсказуемость работы приложения. Схемы позволяют не только проверять значения, но и автоматически преобразовывать их, задавать дефолтные параметры и управлять ошибками без громоздкой ручной логики. Такой подход повышает безопасность маршрутизации и упрощает работу с динамическими URL.

Оглавление