0Pricing
React Academy · Aula

Gerenciando estado nos parâmetros de busca da URL

Sincronize filtros, ordenação e paginação com a URL usando useSearchParams.

Gerenciando estado nos parâmetros de busca da URL é uma aula grátis de React Academy no CoddyKit. Esta é a aula 4 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de React Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de React Academy inclui 4 aulas no total.

Por que armazenar o estado na URL?

Filtros, consultas de pesquisa, ordens de classificação e paginação pertencem à URL para que os usuários possam criar favoritos, compartilhar e voltar à mesma visualização sem perder o estado.

Gancho useSearchParams

useSearchParams() retorna a instância atual de URLSearchParams e uma função para defini-la, de modo semelhante a useState, mas com base na cadeia de consulta da URL.

import { useSearchParams } from 'react-router-dom';

function ProductList() {
  const [searchParams, setSearchParams] = useSearchParams();
  const query = searchParams.get('q') || '';
  const page = Number(searchParams.get('page') || 1);
  // ...
}

Lendo um único parâmetro

Use searchParams.get('key') para ler um valor. Ele retorna null se o parâmetro estiver ausente; portanto, forneça um valor alternativo.

const sort = searchParams.get('sort') ?? 'name';
const order = searchParams.get('order') ?? 'asc';

Escrevendo parâmetros sem navegação

Chame setSearchParams() com um novo objeto ou uma função atualizadora para alterar os parâmetros. O React Router atualiza a URL e renderiza novamente sem uma navegação completa.

function SortButton({ field }) {
  const [searchParams, setSearchParams] = useSearchParams();
  const handleClick = () => {
    setSearchParams(prev => {
      prev.set('sort', field);
      prev.set('page', '1');
      return prev;
    });
  };
  return <button onClick={handleClick}>Sort by {field}</button>;
}

Preservando outros parâmetros durante a atualização

Use a forma com função atualizadora de setSearchParams para alterar apenas os parâmetros que você pretende modificar, mantendo todos os outros intactos.

setSearchParams(prev => {
  prev.set('q', newQuery);
  // 'sort' and 'page' are unchanged
  return prev;
});

Sincronizando um campo de entrada com os parâmetros de pesquisa

Controle o valor de um campo de entrada a partir do parâmetro da URL e atualize a URL quando ele mudar para mantê-los sincronizados.

function SearchBar() {
  const [params, setParams] = useSearchParams();
  const q = params.get('q') || '';
  return (
    <input
      value={q}
      onChange={e => setParams(prev => {
        prev.set('q', e.target.value);
        prev.set('page', '1');
        return prev;
      })}
    />
  );
}

Sinalizadores booleanos nos parâmetros de pesquisa

Use a presença ou a ausência de um parâmetro (ou uma cadeia '1'/'0') para representar um estado booleano da interface, como um painel aberto ou filtros ativos.

const showFilters = searchParams.has('filters');

const toggleFilters = () => {
  setSearchParams(prev => {
    if (prev.has('filters')) prev.delete('filters');
    else prev.set('filters', '1');
    return prev;
  });
};

Valores de matriz nos parâmetros de pesquisa

URLSearchParams aceita vários valores para a mesma chave. Use getAll('key') para lê-los como uma matriz.

// URL: /products?tag=react&tag=typescript
const tags = searchParams.getAll('tag'); // ['react', 'typescript']

// Setting multiple values:
const newParams = new URLSearchParams();
selectedTags.forEach(t => newParams.append('tag', t));
setSearchParams(newParams);

Substituindo versus adicionando ao histórico

Passe { replace: true } como segundo argumento para setSearchParams para que as alterações nos filtros não sobrecarreguem a pilha de histórico do navegador.

setSearchParams(prev => { prev.set('q', val); return prev; }, { replace: true });

Derivando o estado dos parâmetros

Calcule valores derivados (como inteiros analisados ou enumeradores validados) a partir dos parâmetros brutos em formato de texto no início do componente, para usá-los com segurança em todo o código.

const rawPage = searchParams.get('page');
const page = Math.max(1, parseInt(rawPage || '1', 10));

const rawSort = searchParams.get('sort');
const sort = ['name', 'price', 'date'].includes(rawSort) ? rawSort : 'name';

Navegando com parâmetros de pesquisa

Use a propriedade search em um componente de link ou em um objeto de destino para navegar para uma URL com parâmetros de consulta específicos definidos.

<Link to={{ pathname: '/products', search: '?sort=price&order=asc' }}>
  Sort by Price
</Link>

Verificação rápida

Qual método de URLSearchParams lê todos os valores de uma chave repetida como ?tag=react&tag=ts?

Recapitulação

useSearchParams() sincroniza o estado do componente com a cadeia de consulta da URL. Use a forma com função atualizadora para preservar outros parâmetros, { replace: true } para evitar o excesso de entradas no histórico e getAll() para parâmetros com valores em matriz.

Perguntas Frequentes

A aula “Gerenciando estado nos parâmetros de busca da URL” é grátis?

Sim — o texto completo de “Gerenciando estado nos parâmetros de busca da URL” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de React Academy, atualize para CoddyKit PRO. O curso de React Academy inclui 4 aulas no total.

O que vou aprender em “Gerenciando estado nos parâmetros de busca da URL”?

Sincronize filtros, ordenação e paginação com a URL usando useSearchParams. Você pratica React Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar React Academy?

Nenhuma experiência prévia é necessária. React Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 4 de 4.

Quanto tempo leva a aula “Gerenciando estado nos parâmetros de busca da URL”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de React Academy?

Sim. Cada aula de React Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

  1. Rotas aninhadas e layouts com Outlet
  2. Carregadores e ações (API de roteador de dados)
  3. Rotas protegidas e guardas de autenticação
  4. Gerenciando estado nos parâmetros de busca da URL
← Voltar para React Academy