Что такое useQueryParams?

Что такое useQueryParams?

useQueryParams — это концепция, паттерн или часто реализуемый пользовательский хук в React-приложениях для удобной работы с параметрами строки запроса (URL Query Parameters). Он предназначен для чтения, обновления и синхронизации состояния компонентов с параметрами, которые находятся в URL после символа ? (например, ?search=react&page=2).

Основные цели и задачи useQueryParams

• Синхронизация UI с URL: Позволяет отражать состояние приложения (например, значения фильтров, страницу пагинации, режим сортировки) в URL, делая это состояние сохраняемым, делимым и восстанавливаемым.
• Управление состоянием через URL: Использование URL как источника состояния для компонентов, что особенно полезно для сложных фильтров, где параметры должны быть доступны для копирования, сохранения в истории браузера или использования в SSR.
• Упрощение кода: Абстрагирует ручную работу с window.location.search, URLSearchParams и историей браузера, предоставляя реактивный интерфейс, аналогичный useState.

Как работает типичная реализация хука?

В основе лежит браузерный API URLSearchParams и история браузера (window.history или библиотека react-router). Хук обычно возвращает текущие параметры и функцию для их обновления.

Пример базовой реализации с React Router

Если приложение использует react-router (v5+), useQueryParams часто реализуется через его хуки useLocation и useHistory.

import { useLocation, useHistory } from 'react-router-dom';

// Простой хук для работы с одним параметром
function useQueryParam(key, defaultValue) {
  const location = useLocation();
  const history = useHistory();
  
  const searchParams = new URLSearchParams(location.search);
  const paramValue = searchParams.get(key) || defaultValue;

  const setParam = (newValue) => {
    const newSearchParams = new URLSearchParams(location.search);
    if (newValue) {
      newSearchParams.set(key, newValue);
    } else {
      newSearchParams.delete(key);
    }
    history.push({
      pathname: location.pathname,
      search: newSearchParams.toString(),
    });
  };

  return [paramValue, setParam];
}

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

function SearchComponent() {
  // Используем хук для параметра 'q'
  const [searchTerm, setSearchTerm] = useQueryParam('q', '');

  const handleChange = (event) => {
    setSearchTerm(event.target.value);
  };

  return (
    <input
      type="text"
      value={searchTerm}
      onChange={handleChange}
      placeholder="Search..."
    />
  );
}

Ключевые особенности и преимущества

1. Реактивность: При изменении параметров в URL (например, через ссылки или браузерную историю) компонент автоматически обновляется благодаря реактивности хуков и react-router.
2. Совместное использование с другими хуками: useQueryParams может комбинироваться с useState, useEffect для сложной логики. Например, можно дебаунсить обновления параметров.
3. Поддержка типов и сериализации: В продвинутых реализациях хук может поддерживать сериализацию/десериализацию JSON, работу с массивами, булевыми значениями и т.д.

// Пример с сериализацией объекта
const [filters, setFilters] = useQueryParams({
  parse: (str) => JSON.parse(str),
  serialize: (obj) => JSON.stringify(obj),
});

1. SSR и Next.js: В Next.js можно использовать next/router (useRouter) и URLSearchParams для аналогичных задач.
2. Отсутствие зависимости от react-router: Можно реализовать хук, используя только браузерные API и useState/useEffect.

Проблемы и ограничения

• Сложность с несколькими параметрами: При работе с множеством параметров нужен хук, который управляет объектом, а не отдельными значениями.
• История изменений: При частых обновлениях (например, во время ввода в поле поиска) может создаваться много записей в истории браузера, что требует дебаунсинга или замены history.push на history.replace.
• Безопасность: При использовании JSON сериализации нужно учитывать риски и валидировать данные.

Альтернативы и библиотеки

Существуют готовые библиотеки, которые реализуют эту функциональность:

• use-query-params: Популярная библиотека для React, интегрируемая с react-router, поддерживает сложные типы данных, дебаунсинг.
• react-router-use-query-params: Специализированные решения для react-router.
• Встроенные возможности Next.js 13+: App Router предлагает useSearchParams как стандартный хук.

// Пример с use-query-params библиотекой
import { useQueryParams, StringParam } from 'use-query-params';

const [query, setQuery] = useQueryParams({ q: StringParam });

Заключение

useQueryParams — это мощный паттерн, который превращает URL из простого адреса страницы в полноценное хранилище состояния приложения. Он повышает пользовательский опыт (возможность делиться ссылками с сохранёнными фильтрами), улучшает архитектуру (централизованное управление состоянием) и снижает сложность кода. Реализация может варьироваться от простого хука на 10 строк до использования специализированных библиотек с поддержкой всех типов данных и продвинутой синхронизации.