Componentes · Dados

Listagem

É a tela que lista os registros de uma tabela em linhas, com busca, ordenação, páginas e botões em cada linha. Você não escreve consulta nem paginação: escolhe as colunas, decide o que cada botão faz e a tela já nasce com busca e ordenação funcionando.

<mad-grid> Novo → Listagem (ou Gerar CRUDs em lote) Até 8 colunas visíveis sem rolagem lateral
01

Quando usar

A Listagem mostra muitos registros de uma vez, um por linha, e é a porta de entrada da maioria dos cadastros: dali a pessoa busca, filtra e abre o registro que interessa.

Sua situaçãoComponente certo
Listar registros de uma tabela, com busca e páginasListagem
Lançar várias linhas em lote, como numa planilhaSheet
Editar as linhas filhas de um cadastro (itens de um pedido)Detail Form
Acompanhar cartões por etapa, arrastando entre colunasKanban
Mostrar números consolidados, sem linha a linhaPainel de indicadores
Escolher UM registro numa grade e voltar para o formulárioDB Seek
A Listagem é leitura: ela mostra e abre. Quem cria e edita é o Formulário que ela abre. As duas telas nascem juntas quando você usa Gerar CRUDs em lote.
1

Criar a listagem e apontar a tabela

  1. No rail, use Gerar CRUDs em lote para criar listagem e formulário de uma vez — é o caminho mais curto.
  2. Para uma tela avulsa, crie uma página do tipo Listagem e escolha a tabela.
  3. Abra a tela no Studio e clique na grade para o painel da direita mostrar as opções dela.
Resultado para quem usa o sistema: a tela já abre listando os registros, com busca no topo e páginas embaixo — antes de você configurar qualquer coisa.
2

Ajustar o comportamento da grade

  1. Selecione a grade e abra Layout.
  2. Ligue Buscável para a caixa de busca aparecer no topo; Exportável para o botão de exportar.
  3. Header Fixo mantém o cabeçalho visível enquanto a pessoa rola listas longas.
  4. Lado das ações decide se os botões da linha ficam à direita ou à esquerda.
  5. Em Paginação, ajuste Itens por página; em Ordenação, a Ordenação padrão.
Resultado para quem usa o sistema: a lista abre já ordenada pela coluna certa, com a quantidade de linhas que cabe na tela, e a busca filtra enquanto a pessoa digita.
Destaque
Painel de propriedades da grade, com Layout, Paginação e Ordenação abertas

Passe o mouse na lista — ou use ↑ ↓ depois de focar um item.

O que o painel escreve no código

        

      

      
Sem ordenação padrão a lista parece aleatória. O banco não garante ordem nenhuma quando
ninguém pede uma. Defina sempre uma coluna em Ordenação padrão.

    


    

      
3
Escolher o que a lista carrega e o que a pessoa filtra

      
São dois mecanismos diferentes, e confundi-los é o erro mais comum desta tela.

      
    
        
  1. Regras de carregamento é o corte que o sistema aplica sempre — só os ativos, só a minha unidade. A pessoa não vê e não desliga.
    2. 
        
  2. Filtros é a barra que a pessoa usa na tela — por período, por situação, por responsável.
    3. 
        
  3. Em Agrupamento, escolha Níveis de agrupamento para quebrar a lista em blocos, e ligue Subtotais por grupo para somar cada bloco.
    4. 
      

      
Resultado para quem usa o sistema: a lista chega já reduzida ao que interessa àquele usuário, e ele ainda pode apertar mais o resultado pelos filtros da tela.

      
Os dois mecanismos, com as janelas de configuração explicadas passo a passo, estão em
Filtrar.
Para deixar o próprio usuário montar o filtro (coluna, operador e valor) e salvá-lo, veja o
Filtro avançado da listagem.

      

        Destaque
        
        
        
        
      

      

        

          

            
Painel da grade com as seções Regras de carregamento, Filtros e Agrupamento

          

        

        

      

    


    

      
4
Escolher e formatar as colunas

      
    
        
  1. Na seção Colunas do painel da grade você vê a lista de colunas e adiciona ou remove.
    2. 
        
  2. Clique numa coluna para abrir o painel dela.
    3. 
        
  3. Campo: a coluna da tabela que ela mostra. Label: o título que aparece no cabeçalho.
    4. 
        
  4. Largura e Alinhamento ajustam a tabela; número alinhado à direita lê muito melhor.
    5. 
        
  5. Em Formato, escolha Formato de data ou um Transformador — dinheiro, porcentagem, situação com cor.
    6. 
      

      
Resultado para quem usa o sistema: a tabela fica legível: datas no formato do país, valores alinhados e com separador de milhar, e situação em cor em vez de código.

      

        Destaque
        
        
        
        
      

      

        

          

            
Painel da grade com as seções Colunas e Ações

          

        

        

      

      

        Destaque
        
        
        
        
      

      

        

          

            
Painel de propriedades de uma Coluna, com Identificação, Ordenação e Formato

          

        

        

      

      

        Destaque
        
        
        
        
      

      

        

          

            
Painel da Coluna com as seções Cálculo e Visibilidade

          

        

        

      

      

        Destaque
        
        
        
        
      

      

        

          

            
Painel da Coluna com as seções Filtro da coluna e Edição inline

          

        

        

      

    


    

      
5
Botões em cada linha

      
    
        
  1. Na seção Ações da grade, adicione um botão e clique nele.
    2. 
        
  2. Label e Ícone: o que a pessoa vê. Em listas com muitos botões, use só o ícone e preencha o Tooltip.
    3. 
        
  3. Navigate: escolha a tela que o botão abre e o método dela.
    4. 
        
  4. Argumentos: o que é passado para essa tela — normalmente o código do registro da linha.
    5. 
        
  5. Abrir em: página inteira, gaveta ou modal.
    6. 
        
  6. Para excluir, use Tipo de confirmação — sem isso a pessoa apaga sem querer.
    7. 
        
  7. Em Visibilidade, Exibir quando… esconde o botão nas linhas em que ele não faz sentido.
    8. 
      

      
Resultado para quem usa o sistema: cada linha ganha os botões certos: abrir, editar, excluir com confirmação — e o botão some nas linhas em que a ação não vale.

      

        Destaque
        
        
        
        
      

      

        

          

            
Painel de propriedades de uma Ação de linha, com Conteúdo, Navegação, Estilo e Visibilidade

          

        

        

      

      
Botão que não faz nada. Uma ação sem Navigate e sem método fica na tela e não responde
ao clique — não dá erro, não avisa. Se um botão parece morto, é o primeiro lugar para olhar.

    


    

      
6
Testar antes de entregar

      
Salve a tela e publique no Teste online. Confira nesta ordem:

      

        

            
O que fazerO que tem que acontecer

            
Abrir a listagemAs linhas aparecem na ordem definida em Ordenação padrão.

            
Digitar na buscaA lista filtra pelas colunas visíveis.

            
Clicar no cabeçalho de uma colunaA lista reordena por ela, nos dois sentidos.

            
Ir para a página 2A navegação funciona e a ordenação se mantém.

            
Clicar no botão de abrir de uma linhaA tela de destino abre com o registro daquela linha.

            
Clicar em excluirAparece a confirmação antes de qualquer coisa acontecer.

            
Conferir com outro usuárioAs regras de carregamento continuam valendo para ele.

        

      

    


    

      
08
Problemas comuns

      
A lista abre em ordem diferente a cada vez

      
Falta a Ordenação padrão no painel da grade. Sem ela o banco devolve as linhas na ordem
      que quiser, e ela muda conforme os registros são editados.

      
Cliquei no botão da linha e nada aconteceu

      
A ação está sem destino: Navigate vazio, ou o método escolhido não existe mais na tela de
      destino. Abra o painel da ação e confira os dois.

      
O botão abre a tela certa, mas ela vem em branco

      
Faltam os Argumentos — a tela de destino não recebeu o código do registro e abriu como
      cadastro novo. Adicione o argumento com o campo de identificação da linha.

      
Uma coluna de outra tabela não ordena

      
A coluna vem por relação (cidade→nome). Ordenar por caminho de relação nem sempre é
      possível: desligue Ordenável nela ou traga o valor para uma coluna própria.

      
Os subtotais aparecem repetidos ou fora de lugar

      
O agrupamento está por uma coluna que a lista não está ordenando. Ordene pela mesma coluna do
      agrupamento — o subtotal fecha a cada mudança de valor, então a ordem tem que acompanhar.

      
A listagem demora a abrir

      
Ou são muitas linhas por página, ou muitas colunas com fórmula. Reduza Itens por página e
      prefira trazer o valor já calculado da tabela quando a conta se repete em todas as linhas.

    


    

      
09
Referência: painel × código

      
Para quem também mexe no Blade, este é o de-para entre o painel e os atributos gerados.

      

        

            
No painelNo códigoPadrão

            
Header Fixostickydesligado

            
Buscávelsearchableligado

            
Exportávelexportabledesligado

            
Atualizávelrefreshabledesligado

            
Lado das açõesaction-sidedireita

            
Itens por páginaper-page20

            
Ordenação padrãoorder-by—

            
Subtotais por grupogroup-totaldesligado

            
Campo (da Coluna)field—

            
Label (da Coluna)label—

            
Largurawidthautomática

            
Alinhamentoalignesquerda

            
Ordenávelsortligado

            
Formato de datadate—

            
Transformadortransform—

            
Render HTMLhtmldesligado

            
Fórmulaevaluate—

            
Totaltotal—

            
Ocultahiddendesligado

            
Ocultávelhideabledesligado

            
Condição de exibição (PHP)display-condition—

            
Label (da Ação)label—

            
Tooltiptitle—

            
Tipo de confirmaçãoconfirm-typenenhuma

            
Navigatenavigate—

            
Abrir em_open-modeautomático

            
Argumentosparams—

            
Íconeicon—

            
Variantevariant—

            
Exibir quando…_visibility_whensempre visível