ListView

Lista de uma coluna com teclado, seleção e ações por item.

O ListView é a lista rica de uma coluna: tentativas de Webhook, Pedidos no celular, Fontes. Ele traz navegação por teclado, busca por inicial, seleção e ações por item. Para dados em colunas use DataGrid; para linhas-cartão fixas, sem seleção, ItemCard.

import { ListView } from "@rastreio-x/ui";

Padrão

Passe items e um render function. Cada ListView.Item tem id e textValue; o conteúdo vai em ListView.ItemContent com ListView.Title e ListView.Description. O aria-label é obrigatório.

Marina Souzaped-8 · Em trânsito, Pluma

Rafael Limaped-7 · Entregue, Nimbo

Beatriz Alvesped-6 · Atrasado, Trilha

Caio Martinsped-5 · Em trânsito, Pluma

Variante secundária

primary (padrão) tem fundo cinza com itens em superfície; secondary não tem fundo e é a escolha dentro de Widget e Sheet.

Pedido ped-8 aceitohá 2 minutos

Duplicidade retidahá 1 hora

Pedido ped-7 aceitoontem, 17:45

Seleção

selectionMode="multiple" (ou single) mostra as caixas de seleção. Use selectedKeys e onSelectionChange para controlar. Combine com ActionBar para ações em lote.

Marina Souzaped-8

Rafael Limaped-7

Beatriz Alvesped-6

Caio Martinsped-5

0 selecionados

Ações por item

ListView.ItemAction reúne o estado e os botões à direita. onAction trata o clique na linha.

Loja AuroraWebhook genérico

Ativa

Loja BrisaWebhook genérico

Pausada

Itens desabilitados

disabledKeys impede seleção e foco. Explique o motivo no texto do item.

Marina Souza

Rafael Lima (entregue)

Beatriz Alves

Lista vazia

renderEmptyState mostra o que fazer quando não há itens.

Nenhuma tentativa ainda. Envie um Pedido de teste pela Fonte.

Anatomia

ListView
├── ListView.Description
├── ListView.Item
├── ListView.ItemAction
├── ListView.ItemContent
└── ListView.Title

ListView.Item: a linha, com id e textValue.
ListView.ItemContent: ícone ou avatar mais texto.
ListView.Title e ListView.Description: texto principal e de apoio, truncados.
ListView.ItemAction: o espaço de ações à direita.

Propriedades

ListView:

ListView
Prop	Tipo	Padrão	Descrição
`aria-label`	`string`	-	Nome acessível, lido por leitores de tela quando não há rótulo visível.
`autoFocus`	`boolean \| FocusStrategy`	-	Foca o elemento ao renderizar.
`children`	`React.ReactNode \| ((item: T) => React.ReactNode)`	-	Conteúdo do componente.
`className`	`ClassNameOrFunction<GridListRenderProps>`	`'react-aria-GridList'`	Classes CSS aplicadas ao elemento.
`defaultSelectedKeys`	`Iterable<Key> \| 'all'`	-	Chaves selecionadas inicialmente (não controlado).
`dependencies`	`readonly any[]`	-	Valores que invalidam o cache dos itens em coleções dinâmicas.
`disabledBehavior`	`DisabledBehavior`	`'all'`	Define se `disabledKeys` vale para todas as interações ou só para a seleção.
`disabledKeys`	`Iterable<Key>`	-	Chaves dos itens desabilitados: não podem ser focados nem selecionados.
`disallowEmptySelection`	`boolean`	-	Impede ficar sem nenhum item selecionado.
`disallowTypeAhead`	`boolean`	`false`	Whether typeahead navigation is disabled.
`dragAndDropHooks`	`DragAndDropHooks<NoInfer<T>>`	-	Opção de arrastar do motion (`dragAndDropHooks`).
`escapeKeyBehavior`	`'none' \| 'clearSelection'`	`'clearSelection'`	O que a tecla Esc faz: limpar a seleção ou nada.
`id`	`string`	-	Identificador único do elemento.
`items`	`Iterable<T>`	-	Itens a renderizar (coleção dinâmica).
`keyboardNavigationBehavior`	`'tab' \| 'arrow'`	`'arrow'`	Whether keyboard navigation to focusable elements within grid list items is via the left/right arrow keys or the tab key.
`onAction`	`((key: Key) => void)`	-	Chamada quando o item é acionado.
`onSelectionChange`	`((keys: Selection) => void)`	-	Chamada quando a seleção muda.
`render`	`DOMRenderFunction<'div', GridListRenderProps>`	-	Troca o elemento DOM padrão por outro, mantendo o comportamento e as props do componente.
`renderEmptyState`	`(() => React.ReactNode)`	-	Conteúdo exibido quando não há itens.
`rowHeight`	`number`	`48`	Estimated row height in pixels for virtualization.
`selectedKeys`	`Iterable<Key> \| 'all'`	-	Chaves selecionadas (controlado).
`selectionBehavior`	`SelectionBehavior`	`'toggle'`	Modelo de interação da seleção: `toggle` marca cada item; `replace` troca a seleção.
`selectionMode`	`SelectionMode`	-	Tipo de seleção permitida: nenhuma, única ou múltipla.
`shouldSelectOnPressUp`	`boolean`	-	Seleciona ao soltar, em vez de ao pressionar.
`style`	`StyleOrFunction<GridListRenderProps>`	-	Estilos em linha aplicados ao elemento.
`UNSTABLE_focusOnEntry`	`'first' \| 'last'`	-	Foca o conteúdo ao entrar. Interface instável.
`variant`	`'primary' \| 'secondary'`	`"primary"`	Variante visual do componente.
`virtualized`	`boolean`	`false`	Enable row virtualization for large datasets.

ListView.Item:

ListView.Item
Prop	Tipo	Padrão	Descrição
`children`*	`React.ReactNode`	-	Conteúdo do componente.
`allowsArrowNavigation`	`boolean`	-	Permite navegar entre células com as setas, mesmo com Tab como padrão.
`className`	`ClassNameOrFunction<GridListItemRenderProps>`	`'react-aria-GridListItem'`	Classes CSS aplicadas ao elemento.
`download`	`string \| boolean`	-	Faz o navegador baixar o arquivo do link; um texto sugere o nome.
`focusMode`	`'row' \| 'child'`	-	Define se o foco vai para a célula ou para o primeiro filho focável.
`href`	`string`	-	URL de destino do link.
`hrefLang`	`string`	-	Idioma do recurso do link.
`id`	`Key`	-	Identificador único do elemento.
`isDisabled`	`boolean`	-	Desabilita o componente: sem foco, clique nem envio.
`onAction`	`(() => void)`	-	Chamada quando o item é acionado.
`onPress`	`((e: PressEvent) => void)`	-	Chamada ao soltar o clique, o toque ou a tecla sobre o elemento.
`ping`	`string`	-	URLs notificadas quando o link é seguido.
`referrerPolicy`	`React.HTMLAttributeReferrerPolicy`	-	Quanto da origem (referrer) enviar ao seguir o link.
`rel`	`string`	-	Relação entre a página atual e o recurso do link.
`render`	`DOMRenderFunction<'div', GridListItemRenderProps>`	-	Troca o elemento DOM padrão por outro, mantendo o comportamento e as props do componente.
`routerOptions`	`undefined`	-	Opções do roteador do lado do cliente.
`style`	`StyleOrFunction<GridListItemRenderProps>`	-	Estilos em linha aplicados ao elemento.
`target`	`React.HTMLAttributeAnchorTarget`	-	Janela de destino do link (`_blank`, `_self`).
`textValue`	`string`	-	Texto do item, usado na busca por digitação e na acessibilidade.
`value`	`T`	-	Valor atual (controlado). Em campos de formulário, é o valor enviado.

Animações

Sem movimento
indicativo

O ListView não anima entradas nem saídas; só o estado de hover, seleção e foco muda de cor. Com prefers-reduced-motion, a folha global da fachada reduz qualquer transição a 0,01 ms.

Acessibilidade

Baseado em GridList do React Aria: papel grid, linhas com row, seleção anunciada.
Teclado: setas movem entre itens, Espaço seleciona, Enter dispara a ação, Home e End vão às pontas, digitar a inicial salta ao item.
aria-label obrigatório no ListView; textValue em cada item.
Botões dentro de ListView.ItemAction precisam do próprio aria-label.
Estado em ícone mais texto, nunca só cor.

Boas práticas

Faça

Título curto, uma linha de descrição e no máximo duas ações por item.

Evite

Dados tabulares com várias colunas dentro do ListView, ou botões sem rótulo acessível.

Use secondary dentro de painéis para não somar duas superfícies.
Para mais de 200 itens, ligue virtualized.
Para dados em colunas e ordenação, use DataGrid.

Relacionados

DataGrid para tabelas ordenáveis.
ItemCard para linhas-cartão simples.
ActionBar para ações em lote sobre a seleção.