Link API

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

  1. Декларативная навигация Link API позволяет создавать ссылки с использованием компонента <Link> или хука useLink, что делает код более читаемым и поддерживаемым. Каждая ссылка автоматически управляет формированием URL на основе текущих маршрутов и параметров.

  2. Автоматическая генерация URL В отличие от ручного составления строк URL, Link API использует маршруты, зарегистрированные в Router, и автоматически подставляет нужные параметры. Это снижает риск ошибок при формировании ссылок.

  3. Поддержка параметров и query С помощью Link API можно передавать параметры маршрута, query-параметры и состояния, не прибегая к дополнительным библиотекам. Все параметры корректно кодируются и интегрируются в URL.

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

<Link
  to="/users/:userId"
  params={{ userId: 42 }}
  search={{ filter: 'active' }}
>
  Перейти к пользователю
</Link>
  • to – маршрут, на который нужно перейти, может содержать динамические сегменты.
  • params – объект с параметрами маршрута. TanStack Router автоматически подставляет их в URL.
  • search – объект query-параметров, которые будут добавлены к URL.

Link автоматически генерирует корректный URL и обрабатывает переход без перезагрузки страницы.

Для более сложных сценариев навигации используется хук useLink, который возвращает объект с полезными методами:

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

const link = useLink({ to: '/users/:userId', params: { userId: 42 } });

console.log(link.href); // /users/42
link.navigate();         // Выполняет переход
  • href – автоматически сгенерированный URL, который можно использовать для ссылок или кнопок.
  • navigate() – программный переход по маршруту. Позволяет реализовать навигацию по событию, отличному от клика.

Хук useLink особенно полезен для создания динамических ссылок, где параметры маршрута или query могут изменяться в зависимости от состояния приложения.

Работа с вложенными маршрутами

Link API полностью поддерживает вложенные маршруты. При создании ссылки можно ссылаться на маршрут на любом уровне и передавать параметры родительских маршрутов:

<Link
  to="user.settings"
  params={{ userId: 42 }}
>
  Настройки пользователя
</Link>

TanStack Router автоматически соберёт полный путь к маршруту, учитывая все уровни вложенности, что упрощает управление сложной структурой маршрутов.

Состояние перехода и оптимизация

Link API позволяет передавать состояние между маршрутами через свойство state. Это особенно удобно для передачи данных, которые не должны отображаться в URL:

<Link
  to="/checkout"
  state={{ cartId: 123 }}
>
  Оформить заказ
</Link>
  • state передаётся вместе с переходом и доступно через useLocation().
  • Это помогает хранить временные данные, такие как фильтры или текущие шаги формы, без загрязнения URL.

Доступность и SEO

Link API обеспечивает корректную генерацию стандартных <a> элементов, что улучшает SEO и поддерживает работу клавиатурной навигации:

<Link to="/about">О проекте</Link>

При клике происходит переход без полной перезагрузки, а при открытии в новой вкладке браузер URL ведёт на нужный маршрут. Компонент автоматически добавляет атрибуты href и rel, поддерживая принципы доступности.

Интеграция с программной навигацией

С помощью Link API можно комбинировать декларативные и программные подходы:

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

const link = useLink({ to: '/dashboard' });

function handleClick() {
  link.navigate({ replace: true });
}
  • replace: true – заменяет текущую запись истории вместо добавления новой, что полезно для редиректов.
  • Можно задавать дополнительные опции, включая сохранение состояния scroll, query или запрет анимации перехода.

Практические рекомендации

  • Для статических ссылок и навигации в JSX лучше использовать <Link>.
  • Для динамических ссылок или программной навигации стоит применять useLink.
  • Всегда передавать параметры маршрута через params, чтобы избежать ручной сборки URL.
  • Использовать state для данных, которые не должны быть видимы в URL.
  • Проверять корректность вложенных маршрутов для сложных приложений, чтобы избежать конфликтов параметров.

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

Оглавление