Параметры запроса в URL с React Router

Сохраняйте значения поиска и другие состояния в строке запроса URL с помощью хука useSearchParams из React Router — это делает результаты поиска воспроизводимыми и легко шаримыми. Хук позволяет читать и обновлять query-параметры без дополнительного состояния и обеспечивает понятный, человеко-читаемый URL.

Что такое query-параметры и зачем они нужны

Query-параметры — это пары “ключ=значение”, которые добавляют к концу URL. Они позволяют хранить данные в адресной строке: например, результат поиска, фильтры или номер страницы. Пример: /posts?tag=react — здесь tag=react сохраняет выбранную категорию.

Короткое определение: URL-параметры — способ сериализовать состояние приложения в адресной строке для воспроизводимости и шаринга.

Важно:

• Не храните секреты или большие объёмы данных в query-параметрах.
• Используйте их для фильтров, терминов поиска, сортировок и пагинации.

Как это работает в React Router

React Router предоставляет хук useSearchParams, который помогает читать и обновлять строку запроса. Для работы хука маршрутизация должна быть настроена в приложении (BrowserRouter или аналог).

Пример: простой поисковый ввод

Создайте компонент поиска в App.js. Ниже — пример исходного кода из исходной статьи:

        `import { useState } from "react";  
export default function App() {  
  const [query, setquery] = useState('')  
  const handleChange = (e) => {  
    setquery(e.target.value)  
  };  
  return (  
    
  
        
          
        
    
  
  );  
}`
    

Помните о лучших практиках React: контролируемые компоненты, дебаунс ввода при необходимости и чистые обработчики событий.

Добавьте маршрутизацию

useSearchParams работает только внутри провайдера маршрутизации. Пример index.js, где оборачиваем приложение в BrowserRouter:

        `import React from "react";  
import ReactDOM from "react-dom/client";  
import "./index.css";  
import App from "./App";  
import { BrowserRouter, Route, Routes } from "react-router-dom";  
  
const root = ReactDOM.createRoot(document.getElementById("root"));  
root.render(  
    
      
        
        } />  
        
      
    
);  
`
    

Сохраняем ввод в URL по мере печати

Ниже показано, как обновлять query-параметры при каждом изменении ввода, используя useSearchParams:

        `import { useState } from "react";  
import { useSearchParams } from "react-router-dom";  
  
export default function App() {  
  const [query, setquery] = useState("");  
  const [searchParams, setSearchParams] = useSearchParams({});  
  
  const handleChange = (e) => {  
    setSearchParams({ query: e.target.value });  
    setquery(e.target.value);  
  };  
  return (  
    
  
        
          
        
    
  
  );  
}  
`
    

Пояснение: setSearchParams({ query: e.target.value }) заменяет или добавляет параметр query в адресную строку. Это обновляет URL и историю браузера.

Чтение значений из URL

useSearchParams возвращает объект URLSearchParams-подобный, и вы можете вызвать get для конкретного параметра:

        `const [searchParams, setSearchParams] = useSearchParams({});  
const value = searchParams.get('tag')  
`
    

Чтобы получить все параметры, используйте entries():

        `const [searchParams, setSearchParams] = useSearchParams({});  
const values = searchParams.entries()  
`
    

entries() возвращает итератор пар [ключ, значение], которые можно пройти в цикле:

        `for (const [key, value] of values) {  
    console.log(`${key}, ${value}`);  
}  
`
    

Порядок пар соответствует порядку в URL.

Практические советы и шаблоны использования

• Дебаунс: если запрос вызывает сетевой запрос при каждом вводе, добавьте debounce, чтобы снизить нагрузку.
• Замена vs добавление: setSearchParams заменяет всю карту параметров; если нужно добавлять/удалять отдельные ключи, получайте текущие searchParams, модифицируйте и заново устанавливайте.
• Поддержка истории: useSearchParams меняет историю — можно использовать replace для незаписываемых состояний (например, временные подсказки).

Когда подход не подходит

• Большие объёмы данных: не храните большие объёмы в URL.
• Чувствительные данные: никогда не храните личную или секретную информацию в URL.
• Сложные структуры: для вложенных структур лучше использовать state менеджер и сериализовать кратко или хранить в бекенде.

Альтернативы

• Локальный state (useState/useReducer) — для несообщаемого состояния.
• Контейнеры состояния (Redux/MobX) — для глобального управления состоянием.
• Хранение в sessionStorage/localStorage — для сохранения между сессиями, но не для шаринга.

Чек‑лист ролей перед релизом

• Разработчик: проверить корректность сериализации/десериализации query-параметров и обработку пустых значений.
• QA: проверить копирование/вставку URL, работу back/forward, и влияние на историю.
• PM/UX: убедиться, что URL остаётся человеко-читаемым и не раскрывает чувствительную информацию.

Критерии приёмки

• Значение поиска сохраняется в URL при вводе.
• Открытие того же URL восстанавливает состояние поиска.
• URL изменяется корректно при очистке поиска или смене фильтра.
• Никаких секретных данных в URL.

Небольшой глоссарий

• URLSearchParams — стандартный интерфейс для работы с параметрами запроса.
• useSearchParams — хук React Router для чтения и записи query-параметров.

Итог

useSearchParams — удобный инструмент для сериализации состояния поиска и простых фильтров в URL. Он повышает удобство пользователей за счёт шаринга и воспроизводимости поиска. Применяйте дебаунс при необходимости, избегайте хранения чувствительных или больших данных, и тестируйте поведение истории браузера.

Краткое резюме

• Используйте query-параметры для шаринга фильтров и поисковых запросов.
• Настройте BrowserRouter, затем применяйте useSearchParams для чтения/записи.
• Проверяйте edge‑кейсы: пустые значения, back/forward и чувствительные данные.