Padrões de UX / Dados e listas
Experiência degradada
O pedaço que falhou diz isso no lugar dele, o resto continua, e dado indisponível não vira vazio.
Quando um pedaço da tela falha, ele diz isso no lugar dele, e o resto continua funcionando. Degrade, não bloqueie.
O problema
O gráfico de faturamento não carregou, e a página inteira vira "Algo deu errado", levando junto a lista de pedidos que tinha carregado. Ou o contrário: o serviço de estoque caiu, e a tela mostra "Nenhum produto", que a pessoa lê como verdade e vai repor o que não falta. Os dois erram no mesmo ponto: tratam o que falhou como se fosse a tela toda, ou como se fosse vazio.
Quando usar
Toda tela que junta mais de uma fonte: o painel com quatro consultas, o registro com o histórico de outro serviço, a listagem com o estoque de outro sistema, o app que perdeu a conexão no meio do uso. E toda falha parcial de um serviço de fora: a busca por CEP que não respondeu, o cálculo de frete fora do ar, o intermediador de pagamento lento.
Quando não usar
- Quando nada da tela funciona sem o que falhou, a página de erro inteira é
a resposta honesta: o
Resultdo 500, do sem conexão ou da manutenção (erros.md). - Quando o dado que falhou é a condição da ação, a ação para: emitir a nota sem a resposta da prefeitura não é degradar, é emitir errado.
- Quando a falha é da ação, e não da consulta, é o "deu errado" dos quatro
momentos, no botão e no
Alert: erros.md.
As peças
QueryBoundarypor região, cada um com o seuisError,onRetrye o texto do pedaço.DataTableeQueryBoundarycomisRefetchError: o dado velho fica na tela com o aviso de que não está atualizado.Alertno lugar do pedaço que falhou, com a frase do que continua.Banner: a falha que atravessa a tela inteira (sem conexão, serviço de fora instável), uma faixa só, no topo.useNetworkStatus: online ou offline.Resultcom a ilustraçãoOffline: quando nada funciona sem rede.
Comportamento
- Cada região carrega e falha sozinha. Um
QueryBoundarypor consulta, e não um em volta da página. O gráfico que falhou mostra o erro do tamanho do gráfico, com "Tentar de novo", e a tabela ao lado segue com os dados dela. - Dado indisponível não vira estado vazio. "Não foi possível carregar o estoque" é uma coisa; "Nenhum produto em estoque" é outra, e trocar uma pela outra faz a pessoa agir sobre o que não é verdade. Na célula de uma tabela, o valor que não veio é "Indisponível", e não zero nem traço.
- O dado velho fica, com a data. Revalidação que falhou mantém o que já
estava, com "Atualizado às 14:02. Não foi possível atualizar agora." O
isRefetchErrorcom dado na mão faz isso nas peças de consulta. - A ação que depende do que falhou para; o resto não. Sem o frete, o carrinho continua editável, e só o "Finalizar compra" espera, com o motivo.
- No máximo umas cinco mensagens por página. Se mais que isso falhou, a
falha é de outra camada: troque as cinco por um
Bannerno topo ("O faturamento está fora do ar. Os números desta página podem estar desatualizados.") e deixe as regiões quietas, com o dado velho ou o espaço reservado. - Sem conexão, o que já está na tela continua legível, e o que precisa de rede diz isso no próprio controle. Ao voltar a conexão, a tela revalida sozinha, sem pedir para recarregar.
<div className="grid gap-8 lg:grid-cols-[minmax(0,2fr)_minmax(0,1fr)]">
<QueryBoundary
data={revenue.data}
isLoading={revenue.isPending}
isError={revenue.isError}
onRetry={revenue.refetch}
errorTitle="Não foi possível carregar o faturamento"
errorMessage="O resto do painel continua atualizado. Tente de novo em alguns minutos."
>
{(data) => <RevenueChart data={data} />}
</QueryBoundary>
<QueryBoundary
data={orders.data}
isLoading={orders.isPending}
isError={orders.isError}
onRetry={orders.refetch}
errorTitle="Não foi possível carregar os pedidos"
errorMessage="O sistema de pedidos não respondeu."
>
{(list) => <RecentOrders orders={list} />}
</QueryBoundary>
</div>
Texto
- O pedaço que falhou diz o que não veio e o que continua: "Não foi possível carregar o faturamento. O resto do painel continua atualizado."
- Quem falhou, quando isso muda o que a pessoa faz: "O sistema da operadora não respondeu", "A busca por CEP está fora do ar. Preencha o endereço à mão."
- O dado velho diz a hora: "Atualizado às 14:02".
- O "Indisponível" da célula não é "0" nem "-": zero é um valor, e traço quer dizer "não se aplica".
Acessibilidade
- Cada região que falha anuncia o erro dela uma vez, e não a página inteira em
coro: cinco
role="alert"disparando juntos atropelam o leitor de tela, e é mais um motivo do limite de cinco mensagens. - O "Tentar de novo" de cada região tem nome que diz qual: "Tentar carregar o faturamento de novo", ou o título da região ligado ao botão.
- A região que falhou guarda o espaço dela, para a tela não pular quando a segunda tentativa der certo.
No celular e no nativo
No celular a conexão cai mais, e entra e sai no meio do uso. O
useNetworkStatus é do web; no app, o estado da rede vem da biblioteca de rede
do projeto. O QueryBoundary e o DataList do @rivocode/ui-native portam o
isError, o isRefetchError e o onRetry com os mesmos nomes, e o Banner
também existe lá. O que ficou guardado no aparelho continua
aberto sem rede, e diz de quando é.