Опциональные сегменты пути

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

Синтаксис опциональных сегментов

Опциональный сегмент обозначается квадратными скобками []. Например:

const route = {
  path: '/products/[category]',
  component: ProductList,
};

В этом примере сегмент category является необязательным. Это означает, что маршрут будет совпадать как с /products, так и с /products/electronics.

Ключевые моменты синтаксиса:

  • Сегмент внутри квадратных скобок всегда интерпретируется как параметр.
  • Если параметр не передан, его значение будет undefined в объекте params.
  • Можно комбинировать несколько опциональных сегментов:
const route = {
  path: '/products/[category]/[brand]',
  component: ProductList,
};

Такой маршрут совпадает с:

  • /products
  • /products/electronics
  • /products/electronics/apple

Работа с параметрами опциональных сегментов

Опциональные параметры передаются в компонент через объект params:

function ProductList({ params }) {
  const { category, brand } = params;

  if (category) {
    console.log(`Фильтруем по категории: ${category}`);
  }

  if (brand) {
    console.log(`Фильтруем по бренду: ${brand}`);
  }

  return <div>Список продуктов</div>;
}

Если пользователь перейдёт на /products, оба параметра будут undefined. При переходе на /products/electronics параметр category будет "electronics", а brand останется undefined.

Вложенные опциональные сегменты

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

const routes = [
  {
    path: '/dashboard',
    children: [
      {
        path: '[section]',
        component: DashboardSection,
      },
    ],
  },
];

Здесь маршрут /dashboard доступен без section, а /dashboard/analytics передаст "analytics" в параметр section.

Генерация URL с опциональными сегментами

При генерации URL с помощью функции router.buildPath или аналогичных методов, необязательные параметры можно пропускать. Если параметр не указан, сегмент автоматически опускается:

const path1 = router.buildPath('/products/[category]/[brand]', {}); 
// результат: '/products'

const path2 = router.buildPath('/products/[category]/[brand]', { category: 'electronics' }); 
// результат: '/products/electronics'

const path3 = router.buildPath('/products/[category]/[brand]', { category: 'electronics', brand: 'apple' }); 
// результат: '/products/electronics/apple'

Ограничения и особенности

  • Опциональные сегменты не могут быть в середине пути, если за ними идут обязательные сегменты. Например, /products/[category]/details будет корректным, но /products/[category]/details/[id] может требовать тщательной обработки, если category отсутствует.
  • Если несколько опциональных сегментов идут подряд, важно учитывать порядок, чтобы избежать неоднозначностей при сопоставлении маршрутов.
  • При использовании nested routes необязательные сегменты могут быть полезны для динамических областей интерфейса, например, вкладок, фильтров или модальных окон, которые могут появляться или отсутствовать в URL.

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

  1. Фильтры товаров
const route = {
  path: '/shop/[category]/[brand]/[priceRange]',
  component: Shop,
};

Пользователь может перейти на /shop, /shop/electronics, /shop/electronics/apple, /shop/electronics/apple/100-500. Все параметры будут доступны в params по мере их присутствия.

  1. Страницы пользователя
const route = {
  path: '/profile/[tab]',
  component: ProfilePage,
};

tab может быть "posts", "settings" или отсутствовать. Это позволяет использовать единый компонент для разных представлений профиля.

  1. Документация или статьи
const route = {
  path: '/docs/[section]/[subsection]',
  component: DocsPage,
};

Если section или subsection не указаны, пользователь попадает на общий список документов.

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

Оглавление