useParams для доступа к параметрам

В библиотеке TanStack Router хук useParams используется для получения динамических параметров маршрута. Он является ключевым инструментом для работы с URL-параметрами, позволяя компонентам получать актуальные значения без необходимости вручную извлекать их из объекта location или history.

Основы использования useParams

Хук useParams возвращает объект, где ключи соответствуют именам параметров, определённых в маршруте. Например, маршрут может содержать динамический сегмент:

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

const userRoute = new Route({
  path: '/users/:userId',
  component: () => {
    const params = useParams();
    return <div>ID пользователя: {params.userId}</div>;
  },
});

В этом примере, если пользователь переходит по адресу /users/42, useParams вернёт объект { userId: '42' }.

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

  • Параметры всегда возвращаются в виде строк.
  • Параметры соответствуют тем именам, которые указаны в path маршрута.
  • Хук автоматически реагирует на изменение URL и обновляет параметры.

Использование нескольких параметров

Маршруты могут содержать несколько динамических сегментов:

const postRoute = new Route({
  path: '/users/:userId/posts/:postId',
  component: () => {
    const { userId, postId } = useParams();
    return (
      <div>
        Пользователь: {userId}, Пост: {postId}
      </div>
    );
  },
});

Здесь useParams возвращает объект { userId, postId }. При переходе на /users/5/posts/12 значения будут userId = '5' и postId = '12'.

Типизация параметров в TypeScript

Для проектов на TypeScript важно правильно типизировать возвращаемый объект. TanStack Router поддерживает строгую типизацию параметров маршрута через интерфейсы:

interface UserParams {
  userId: string;
}

const userRoute = new Route<UserParams>({
  path: '/users/:userId',
  component: () => {
    const params = useParams<UserParams>();
    return <div>{params.userId}</div>;
  },
});

Типизация позволяет получать автодополнение и предотвращает ошибки доступа к несуществующим ключам.

Дефолтные значения и необязательные параметры

В TanStack Router можно определять необязательные параметры маршрута, используя знак вопроса в пути (:param?):

const searchRoute = new Route({
  path: '/search/:query?',
  component: () => {
    const { query } = useParams();
    return <div>Результаты поиска: {query ?? 'все'}</div>;
  },
});

Если параметр отсутствует в URL, useParams возвращает undefined. Это позволяет безопасно устанавливать значения по умолчанию через оператор ??.

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

Хук useParams создаёт реактивное состояние. При изменении URL компонента автоматически получает новые значения параметров без перезагрузки страницы:

const userRoute = new Route({
  path: '/users/:userId',
  component: () => {
    const { userId } = useParams();

    React.useEffect(() => {
      console.log('Параметр userId изменился:', userId);
    }, [userId]);

    return <div>ID: {userId}</div>;
  },
});

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

Совместимость с вложенными маршрутами

В сложных приложениях часто используются вложенные маршруты. useParams возвращает все параметры, определённые в текущем маршруте и его родительских:

const appRoute = new Route({
  path: '/',
  children: [
    new Route({
      path: 'users/:userId/posts/:postId',
      component: () => {
        const params = useParams();
        return <div>{JSON.stringify(params)}</div>;
      },
    }),
  ],
});

При переходе на /users/7/posts/21 объект params будет содержать { userId: '7', postId: '21' }. Это упрощает доступ к параметрам для вложенных компонентов без необходимости передачи их через пропсы.

Советы по использованию

  • Для числовых параметров удобно выполнять преобразование вручную: const userId = Number(params.userId).
  • Избегать обращения к несуществующим ключам без проверки, чтобы предотвратить ошибки undefined.
  • Использовать TypeScript-интерфейсы для поддержки автодополнения и строгой типизации.
  • Для параметров, которые могут быть опциональными, использовать безопасное присваивание или оператор ?? для установки значений по умолчанию.

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

Оглавление