Работа с query parameters

В TanStack Router query parameters представляют собой мощный инструмент для передачи состояния между страницами или компонентами приложения через URL. Они позволяют строить более динамичные и реактивные интерфейсы без необходимости хранить состояние исключительно в памяти приложения.

Определение query parameters

Query parameters — это ключи и значения, добавляемые к URL после символа ?. В TanStack Router они могут быть определены на уровне маршрута через объект loader или useMatch для чтения значений. Структура определения query parameters в маршрутах следующая:

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

const searchRoute = createRoute({
  path: 'search',
  component: SearchPage,
  // Определение query параметров
  parseSearch: (search) => {
    return {
      query: search.get('query') ?? '',
      page: Number(search.get('page') ?? 1),
    };
  },
});

Здесь ключевое значение:

  • parseSearch — функция, которая принимает объект URLSearchParams и возвращает структурированные данные для использования в компоненте.
  • Значения query параметров можно приводить к нужному типу прямо в функции.

Чтение query parameters

Для работы с query parameters в компоненте маршрута используется хук useMatch:

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

function SearchPage() {
  const match = useMatch(searchRoute);
  const { query, page } = match.search;

  return (
    <div>
      <h2>Результаты поиска для: {query}</h2>
      <p>Страница: {page}</p>
    </div>
  );
}

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

  • match.search содержит объект, возвращаемый parseSearch.
  • Все изменения query параметров автоматически обновляют компонент без перезагрузки страницы.

Обновление query parameters

Для обновления query parameters используется метод navigate с передачей нового объекта search:

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

function Pagination({ currentPage }) {
  const navigate = useNavigate();

  const goToPage = (page) => {
    navigate({ search: { page } });
  };

  return (
    <button onCl ick={() => goToPage(currentPage + 1)}>
      Следующая страница
    </button>
  );
}

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

  • При использовании navigate можно изменять только выбранные query параметры, не трогая остальные.
  • TanStack Router автоматически объединяет новые параметры с существующими, если явно не указано перезаписывание всего объекта search.

Дефолтные значения и валидация

Дефолтные значения query parameters задаются внутри parseSearch, что позволяет безопасно использовать параметры даже при их отсутствии в URL. Валидация типов — обязательная практика:

parseSearch: (search) => {
  const page = Number(search.get('page'));
  return {
    query: search.get('query') ?? '',
    page: isNaN(page) || page < 1 ? 1 : page,
  };
}

Связь query parameters с состоянием компонента

Часто query parameters используются как источник состояния компонентов:

  • Фильтры таблиц (filter, sort).
  • Номер страницы (page) и количество элементов (limit) для пагинации.
  • Строки поиска (query) в динамических интерфейсах.

Важно: обновление query parameters автоматически триггерит обновление компонента через реактивные хуки TanStack Router, поэтому дополнительное состояние в useState не требуется, если данные полностью отражают URL.

Составные query parameters

Для передачи нескольких значений через один параметр удобно использовать сериализацию:

navigate({
  search: {
    filters: JSON.stringify({ category: 'books', priceRange: '0-100' }),
  },
});

И последующее чтение:

const filters = JSON.parse(match.search.filters ?? '{}');

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

Поддержка реактивных изменений URL

TanStack Router обеспечивает синхронизацию состояния query parameters с URL в реальном времени:

  • Любое изменение query parameters через navigate отражается в адресной строке.
  • Использование useMatch позволяет компоненту реагировать на изменения параметров, даже если они были изменены вручную в браузере.
  • Хуки useNavigate и useMatch полностью интегрированы с историей браузера.

Примеры использования

  1. Фильтрация товаров:
navigate({ search: { category: 'electronics', sort: 'price' } });
  1. Пагинация:
navigate({ search: { page: currentPage + 1 } });
  1. Поиск с автозаполнением:
navigate({ search: { query: inputValue } });

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

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

Оглавление