Параметры loader-функций

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

Контекст вызова loader

Каждый вызов loader-функции получает один объект context, который содержит набор ключевых свойств, предоставляющих доступ к параметрам маршрута, навигации и текущему состоянию роутера:

type LoaderContext = {
  params: Record<string, string>;
  search: URLSearchParams;
  location: Location;
  navigate: (to: string, options?: { replace?: boolean }) => void;
  router: Router;
  preload: (to: string) => void;
};

params

params — объект с динамическими параметрами маршрута. Эти параметры задаются в пути маршрута через двоеточие (:) и автоматически извлекаются из URL.

Пример:

const userLoader: LoaderFunction = ({ params }) => {
  const { userId } = params;
  return fetch(`/api/users/${userId}`).then(res => res.json());
};
  • Ключи объекта совпадают с именами параметров в пути маршрута.
  • Значения всегда строки. Если требуется число, необходимо явно приводить тип.

search предоставляет объект URLSearchParams, который позволяет работать с query-параметрами.

const productsLoader: LoaderFunction = ({ search }) => {
  const category = search.get('category') ?? 'all';
  return fetch(`/api/products?category=${category}`).then(res => res.json());
};
  • Метод get возвращает значение параметра или null, если он отсутствует.
  • Методы has, entries, keys и values помогают обрабатывать несколько параметров.

location

location — объект, описывающий текущий URL, аналогичный объекту window.location, но в более безопасной форме для реактивного роутинга.

const loader: LoaderFunction = ({ location }) => {
  console.log(location.pathname, location.search);
};
  • pathname — путь URL без query и хеша.
  • search — строка query-параметров, включая знак ?.
  • hash — часть URL после #.

navigate — функция для программной навигации внутри loader. Она полезна, если загрузка данных выявляет необходимость редиректа.

const loader: LoaderFunction = async ({ navigate, params }) => {
  const response = await fetch(`/api/items/${params.id}`);
  if (!response.ok) {
    navigate('/error', { replace: true });
    return null;
  }
  return response.json();
};
  • replace: true предотвращает создание новой записи в истории браузера, заменяя текущую.

router

router предоставляет полный доступ к экземпляру роутера:

  • Можно использовать для динамического предзагрузки других маршрутов через preload.
  • Доступ к глобальной конфигурации роутера и состоянию всех маршрутов.
const loader: LoaderFunction = ({ router }) => {
  router.preload('/dashboard');
};

preload

preload используется для оптимизации пользовательского опыта: заранее загружает данные маршрута, не меняя URL.

const loader: LoaderFunction = ({ preload }) => {
  preload('/notifications');
};
  • Может принимать путь или объект маршрута.
  • Позволяет создавать стратегию «ленивой предзагрузки» данных для будущих переходов.

Асинхронная обработка и ошибки

Loader-функции могут быть асинхронными. Если запрос данных завершается ошибкой, роутер предоставляет механизмы её обработки:

const loader: LoaderFunction = async ({ params }) => {
  try {
    const response = await fetch(`/api/users/${params.userId}`);
    if (!response.ok) throw new Error('Пользователь не найден');
    return response.json();
  } catch (error) {
    throw new Response('Ошибка загрузки данных', { status: 500 });
  }
};
  • Ошибки могут быть пойманы через errorElement маршрута.
  • Статус кода и тело ответа можно задать через объект Response.

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

  1. Типизация — строго указывайте типы для params и результата loader, чтобы избежать ошибок на этапе компиляции.
  2. Минимизация зависимостей — loader должен зависеть только от параметров, query и роутера, а не напрямую от состояния компонентов.
  3. Оптимизация запросов — использовать preload для загрузки данных для будущих переходов, снижая задержки рендеринга.
  4. Обработка ошибок — всегда предусматривать сценарии, когда данные могут отсутствовать или запрос завершится неудачей.

Понимание и корректное использование всех параметров loader-функций позволяет создавать приложения на TanStack Router с надежной загрузкой данных, точной навигацией и предсказуемым поведением компонентов.

Оглавление