Wildcard-маршруты

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

Определение wildcard-маршрута

Для создания wildcard-маршрута используется путь вида:

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

const routes = createRouteConfig()
  .createRoute({
    path: '/files/*',
    component: FilesPage,
  });

const router = createRouter({ routeConfig: routes });

Здесь * соответствует любой последовательности символов после /files/. Например, маршруты /files/documents/report.pdf и /files/images/photo.png будут сопоставляться с этим wildcard-маршрутом.

Доступ к значению wildcard

Wildcard-параметр автоматически передается в объект params компонента, которому соответствует маршрут. По умолчанию имя параметра — '*':

function FilesPage({ params }) {
  console.log(params['*']); // "documents/report.pdf" или "images/photo.png"
  return <div>Путь: {params['*']}</div>;
}

Чтобы сделать код более читаемым, рекомендуется использовать именованные wildcard-параметры с помощью двоеточия и *:

.createRoute({
  path: '/files/:path*',
  component: FilesPage,
});

Теперь доступ к значению производится через params.path:

function FilesPage({ params }) {
  console.log(params.path); // "documents/report.pdf"
  return <div>Путь: {params.path}</div>;
}

Вложенные wildcard-маршруты

Wildcard-маршруты можно использовать совместно с вложенной структурой маршрутов. Например, если есть родительский маршрут /dashboard/*:

const dashboardRoute = createRouteConfig()
  .createRoute({
    path: '/dashboard/*',
    component: DashboardLayout,
    children: [
      {
        path: 'analytics',
        component: AnalyticsPage,
      },
      {
        path: 'settings',
        component: SettingsPage,
      },
    ],
  });

Wildcard-сегмент родительского маршрута (*) будет включать оставшийся путь, а дочерние маршруты проверяются внутри этого диапазона. Если пользователь переходит на /dashboard/analytics, wildcard родителя содержит "analytics", и срабатывает дочерний маршрут analytics.

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

Позиция wildcard: Wildcard должен быть в конце пути, иначе маршрутизация может работать некорректно. Например, /files/*/edit не будет корректно сопоставляться с TanStack Router.
Совмещение с обычными параметрами: Можно комбинировать именованные параметры и wildcard:
```
path: '/projects/:projectId/*'
```
Здесь :projectId захватывает первый сегмент после /projects/, а * — оставшуюся часть пути.
Приоритет маршрутов: TanStack Router всегда проверяет маршруты с более специфическими путями перед wildcard. Это позволяет использовать wildcard как “захватывающий” маршрут для всех неопределённых путей.

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

Пример 1: Отображение файлов по пути

const routes = createRouteConfig()
  .createRoute({
    path: '/files/:filePath*',
    component: FileViewer,
  });

function FileViewer({ params }) {
  return <div>Файл: {params.filePath}</div>;
}

Переход на /files/docs/report.pdf выведет: Файл: docs/report.pdf.

Пример 2: Catch-all для 404 страниц

const routes = createRouteConfig()
  .createRoute({
    path: '*',
    component: NotFoundPage,
  });

Любой URL, не сопоставленный с другими маршрутами, попадёт на компонент NotFoundPage.