Uma listagem funciona bem com cinquenta registros e começa a causar problemas quando a operação cresce. A tela demora, os filtros produzem resultados difíceis de explicar e a próxima página parece repetir itens. A solução envolve consulta, contrato de API e experiência de uso, não apenas trocar o componente visual.
Este guia apresenta decisões para listas de pedidos, contratos, clientes e ocorrências. As recomendações devem ser avaliadas no contexto de dados, frequência de alteração e infraestrutura. Nenhuma técnica garante desempenho sem medição. Os exemplos são conceituais e não constituem uma implementação pronta.
1. Defina a tarefa antes de escolher o mecanismo
O usuário precisa localizar um registro específico, revisar uma fila ou navegar por um histórico? Cada tarefa favorece controles diferentes. Uma busca direta pode resolver o primeiro caso; uma fila ordenada por prioridade pode atender ao segundo; um relatório pode exigir outro tratamento.
Não carregue tudo por padrão para depois esconder linhas no navegador. Isso pode consumir memória, transferir dados desnecessários e dificultar autorização. O servidor precisa responder ao escopo e aos filtros aprovados.
Também defina o tamanho de página com base em uso e custo. Um limite muito pequeno exige muitas interações; um limite muito grande pode tornar a leitura e o processamento pesados. A escolha deve ser testada com tarefas e dados representativos.
2. Estabeleça uma ordenação determinística
Uma lista paginada precisa de uma ordem definida. Se vários registros possuem a mesma data ou prioridade, inclua um critério de desempate estável. Sem isso, o banco pode devolver subconjuntos diferentes entre requisições.
A documentação de LIMIT e OFFSET do PostgreSQL destaca a necessidade de ordenação previsível ao limitar resultados e observa que linhas ignoradas por grandes deslocamentos ainda precisam ser processadas. Essa é uma base técnica para avaliar consistência e custo da estratégia.
Decida também o que acontece com valores ausentes e com alterações de prioridade. A regra deve ser a mesma no servidor, na exportação e na descrição da interface. O usuário não deveria precisar deduzir por que determinado registro apareceu antes de outro.
3. Compare paginação por deslocamento e por continuidade
Na paginação por deslocamento, o cliente pede uma posição e uma quantidade. Ela facilita números de página, mas pode ficar cara ou instável em conjuntos muito grandes e alterados frequentemente. A adequação depende do caso, não de uma proibição universal.
Na paginação por continuidade, a próxima consulta utiliza uma referência da posição anterior na ordenação. O desenho precisa considerar os campos de ordenação, o desempate e a validade do cursor. Um cursor não deve permitir ao usuário ampliar o escopo de acesso.
| Estratégia | Pode facilitar | Exige atenção |
|---|---|---|
| Deslocamento | Ir a uma página numerada | Custo de posições distantes e mudanças no conjunto |
| Continuidade | Percorrer uma sequência ordenada | Contrato do cursor e ordenação estável |
| Carregamento incremental | Explorar mais itens na mesma tela | Foco, memória e retorno à posição |
| Busca direta | Encontrar um objeto conhecido | Identificação e autorização do resultado |
4. Trate mudanças no conjunto durante a navegação
Novos pedidos podem chegar enquanto o usuário está na terceira página. Registros podem mudar de estado ou deixar de atender ao filtro. Defina se a tela representa uma visão viva ou uma consulta estabilizada em determinado momento.
Uma visão viva deve informar atualizações sem reposicionar silenciosamente a pessoa no meio de uma decisão. Uma visão estabilizada precisa ter limites claros e mecanismo de renovação. Nenhuma das duas elimina todas as mudanças concorrentes; elas tornam o comportamento mais previsível.
Ao executar uma ação, confira novamente o estado atual no servidor. O fato de o registro estar visível na lista não prova que ainda pode ser aprovado, cancelado ou alterado. A operação precisa tratar conflitos com mensagens específicas e sem perder o contexto da seleção.
5. Desenhe filtros com semântica clara
Um filtro de data pode significar criação, atualização, execução ou vencimento. Use rótulos explícitos. Documente inclusividade dos limites e o fuso utilizado quando forem instantes. Um filtro que parece simples pode mudar o resultado de uma análise gerencial.
Múltiplos critérios também precisam de uma regra compreensível de combinação. O usuário deve enxergar quais filtros estão ativos e conseguir removê-los. Preserve a consulta na URL quando isso ajudar compartilhamento e retorno, sem incluir dados sensíveis desnecessários.
A orientação de desenho de APIs da Microsoft aborda filtragem e paginação como parte do contrato de uma API. Na aplicação empresarial, acrescente exemplos de uso e limites compatíveis com o volume e a autorização.
6. Contagem total pode ter outro custo e outro significado
Exibir “1.245 resultados” pode exigir uma consulta adicional. Em alguns cenários, a contagem não é necessária para a tarefa; em outros, ela é essencial. Avalie o benefício antes de torná-la obrigatória em toda navegação.
Se utilizar uma estimativa, identifique-a. Não apresente um valor aproximado como contagem exata. Uma contagem obtida em outro momento também pode divergir de uma lista viva. O contrato e a interface devem considerar essa possibilidade.
Não conte registros aos quais o usuário não possui acesso para depois filtrar a página visível. Além de confundir, isso pode revelar informação sobre o conjunto. A autorização precisa ser consistente em consulta, contagem e exportação.
7. Exemplo: fila de contratos a revisar
Uma equipe revisa contratos ordenados por vencimento e identificador. O filtro seleciona os que estão em revisão e dentro de uma janela definida. Durante o trabalho, outro usuário conclui um dos contratos e um novo registro entra na fila.
A tela preserva o contexto da pessoa e indica que há atualizações. Ao abrir um item, o servidor retorna o estado atual. Se ele já foi concluído, a interface explica a mudança e evita oferecer uma aprovação sem efeito ou duplicada.
Ao retornar, os filtros permanecem. A pessoa pode atualizar a fila conscientemente, em vez de perder a posição a cada operação. Esse comportamento combina contrato técnico e experiência de trabalho, sem prometer uma fotografia imutável de um processo que continua mudando.
8. Teste desempenho com distribuição representativa
Não basta criar muitos registros idênticos. Filtros seletivos e amplos, datas concentradas e valores ausentes podem produzir comportamentos diferentes. Meça tempo de consulta, transferência e renderização separadamente.
Observe consultas geradas e planos no ambiente apropriado. Índices precisam corresponder a padrões de consulta importantes, com seus custos de manutenção. Adicionar um índice para cada filtro sem avaliar o conjunto pode criar outra forma de desperdício.
O centro de engenharia A2CR oferece conteúdos complementares sobre dados, interface e testes. A melhoria deve ser sustentada por um protocolo comparável, e não por uma impressão de velocidade depois de alterar a tela.
9. Acessibilidade e estados de erro
Informe carregamento, falha e ausência de resultados de maneira distinta. Uma lista vazia não deve significar simultaneamente “nenhum contrato” e “consulta falhou”. Permita nova tentativa sem apagar filtros e contexto.
Ao carregar mais linhas, preserve foco e orientação. Pessoas que usam teclado ou leitor de tela precisam saber o que mudou. Em operações em lote, deixe claro se a seleção cobre apenas a página ou todo o resultado filtrado.
Checklist de implantação
- Definir a tarefa principal da listagem.
- Aplicar escopo e autorização no servidor.
- Estabelecer ordenação com desempate.
- Escolher estratégia de paginação por contexto.
- Definir comportamento quando o conjunto muda.
- Documentar filtros, datas e combinação de critérios.
- Identificar contagens estimadas ou desatualizadas.
- Preservar filtros, foco e retorno à posição.
- Medir consulta, transferência e renderização.
- Testar seleção em lote e conflitos de estado.
Checklist para usar com sua equipe
Baixe o checklist editável em CSV e registre a conferência, o responsável e as observações da implantação.
Perguntas frequentes
Cursor é sempre melhor que número de página?
Não. Ele pode ser adequado a percursos grandes e sequenciais, mas muda a experiência e exige um contrato consistente. Relatórios estáveis e navegação direta podem justificar outras escolhas.
Virtualizar linhas resolve uma consulta lenta?
Não necessariamente. A virtualização reduz trabalho de renderização no navegador, mas não corrige uma consulta cara ou uma transferência excessiva. É preciso localizar onde está o custo.
Posso aplicar filtros somente na interface?
Em conjuntos pequenos e já autorizados, isso pode ser útil. Para grandes bases, dados restritos e operações gerenciais, o contrato do servidor precisa atender aos filtros e limites definidos.
Para evoluir listas e consultas do seu sistema, prepare um briefing com volume, filtros usados e tarefas mais frequentes. A A2CR pode avaliar o fluxo completo antes de escolher a técnica.
Autoria: Agência A2CR. Preparação editorial: 12 de novembro de 2026. Exemplos conceituais; desempenho e consistência exigem testes na arquitetura e no volume pertinentes.
