История параметров поиска

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

Определение и структура параметров поиска

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

Пример URL с параметрами поиска:

/users?filter=active&page=2

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

В TanStack Router параметры поиска определяются в объекте searchSchema при конфигурации маршрута. Этот объект позволяет:

  • Указывать тип параметра (строка, число, булевое значение)
  • Определять значение по умолчанию
  • Настраивать встроенную валидацию значений
  • Обеспечивать синхронизацию с состоянием без необходимости вручную читать location.search

Пример конфигурации маршрута с параметрами поиска:

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

const usersRoute = createRoute({
  path: '/users',
  searchSchema: {
    filter: {
      type: 'string',
      defaultValue: 'all',
    },
    page: {
      type: 'number',
      defaultValue: 1,
    },
  },
});

После такой конфигурации значения filter и page будут автоматически парситься из URL и доступны в маршруте как свойства:

const filter = usersRoute.useSearch().filter; // 'active' или 'all'
const page = usersRoute.useSearch().page; // 2 или 1

Управление историей параметров поиска

TanStack Router интегрирует параметры поиска с History API браузера. Это позволяет:

  • Переходить назад и вперед между состояниями параметров поиска
  • Обновлять URL без перезагрузки страницы при изменении параметров
  • Сохранять состояние фильтров и настроек при навигации

Обновление параметров поиска осуществляется с помощью метода setSearch:

const { setSearch } = usersRoute.useSearch();

setSearch({ filter: 'inactive', page: 1 });

Этот вызов автоматически:

  1. Обновляет URL: /users?filter=inactive&page=1
  2. Добавляет новое состояние в историю браузера
  3. Перезапускает ререндер компонента с актуальными параметрами поиска

Если требуется заменить текущее состояние без добавления в историю (аналог replaceState):

setSearch({ filter: 'inactive' }, { replace: true });

Динамическое обновление параметров поиска

TanStack Router поддерживает частичное обновление параметров. Например, можно изменить только один параметр, сохранив остальные:

setSearch(prev => ({ ...prev, page: 3 }));

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

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

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

Пример интеграции с React Query:

import { useQuery } from '@tanstack/react-query';

const { filter, page } = usersRoute.useSearch();

const { data, isLoading } = useQuery(['users', filter, page], () =>
  fetch(`/api/users?filter=${filter}&page=${page}`).then(res => res.json())
);

При изменении filter или page запрос автоматически повторяется, а URL и состояние компонента остаются синхронизированными.

Поддержка сложных структур и массивов

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

const usersRoute = createRoute({
  path: '/users',
  searchSchema: {
    tags: {
      type: 'array',
      defaultValue: [],
    },
  },
});

setSearch({ tags: ['admin', 'editor'] }); 
// URL: /users?tags=admin&tags=editor

При чтении:

const tags = usersRoute.useSearch().tags; // ['admin', 'editor']

Особенности работы с историей браузера

  • Переход назад восстанавливает предыдущие значения параметров поиска.
  • Обновление одного параметра не удаляет другие параметры, если используется частичное обновление.
  • Замена состояния через replace: true не добавляет запись в историю.
  • События popstate автоматически синхронизируют параметры поиска с компонентами, которые их используют.

Выводы по архитектуре

История параметров поиска в TanStack Router строится на трех принципах:

  1. Типизация и валидация через searchSchema для безопасного парсинга значений.
  2. Синхронизация с History API для поддержки навигации назад/вперед.
  3. Реактивное обновление состояния компонентов при изменении параметров поиска.

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

Оглавление