Componentes · Dados
Itens dentro do formulário
Um pedido tem itens, um cliente tem contatos, um imóvel tem endereços: são registros filhos que nascem, mudam e morrem junto com o registro principal. Você escolhe a tabela filha e as colunas; carregar, gravar e apagar as linhas junto com o cadastro já vem pronto.
<mad-field-list>
Paleta → Dados → Field List / Detail Form
Até 8 colunas na lista de itens — acima disso, um formulário por linha
01
Lista de itens ou formulário por linha
Os dois guardam linhas filhas de um cadastro — registros de outra tabela que apontam para o registro aberto — e gravam tudo junto quando a pessoa salva. A diferença é onde se digita: na lista de itens cada linha é uma linha de tabela, editada ali mesmo; no formulário por linha cada item abre num formulário próprio, e a tabela embaixo só mostra o resultado.
| Sua situação | Componente certo |
|---|---|
| Linhas curtas, poucas colunas, tudo à vista na mesma tela (itens do pedido, parcelas, telefones) | Lista de itens |
| Cada linha tem muitos campos ou campos grandes (endereços com CEP, contatos com foto, observações longas) | Formulário por linha |
| Só consultar, filtrar e exportar registros que já existem | Listagem |
| Campos do próprio registro, sem repetição | Formulário |
| Uma tela longa que precisa de organização, não de linhas filhas | Abas e cards |
| Digitar dezenas de registros de uma vez, no estilo planilha | Planilha |
A régua é simples: até 8 colunas cabem numa linha de tabela sem rolagem lateral. Passou
disso, a pessoa vai perder de vista o que está preenchendo — troque pelo formulário por linha.
1
Colocar na tela
- Abra o formulário no Studio — o cadastro principal precisa existir antes das linhas filhas.
- Clique com o botão direito na seção ou aba onde os itens vão ficar.
- Escolha Field List para a lista de itens, ou Detail Form para o formulário por linha.
- Clique no componente para o painel da direita mostrar as opções.
Resultado: o componente nasce vazio e sem tabela: ainda não sabe de onde as linhas vêm, e no app apareceria só o aviso Nenhum item adicionado.
2
Ligar à tabela filha
- Em Nome, dê um nome curto para a lista — é como ela vai ser citada nos eventos e no código.
- Em Tabela detalhe, escolha a tabela das linhas: a que tem uma coluna apontando para a tabela deste formulário.
- Confira Coluna FK: é a coluna da tabela filha que guarda o código do registro principal. Ela é preenchida sozinha quando a ligação existe no modelo de dados. Depois disso a tabela fica travada — para trocar, remova o componente e adicione outro.
- Clique em Escolher colunas (ou Editar N colunas, quando já houver) para abrir o assistente, marque as colunas que a pessoa vai preencher e clique em Aplicar.
- As colunas escolhidas aparecem no acordeão Colunas e na tabela do canvas, na mesma ordem.
Resultado para quem usa o sistema: ao abrir um pedido, os itens dele já vêm carregados; ao salvar, o que está na tela é gravado na tabela filha junto com o cadastro — inclusive as linhas removidas, que são apagadas.
Destaque
Passe o mouse na lista — ou use ↑ ↓ depois de focar um item.
O que o painel escreve no código
Ligada pela metade, a lista não grava — e não avisa. Tabela sem coluna de ligação, ou
coluna sem tabela, faz a pessoa adicionar linhas, salvar e perder tudo em silêncio. O editor
barra o caso mais comum, mas confira os dois campos antes de publicar.
Destaque
Clique no print para ampliar.
3
Adicionar, remover e reordenar
- Abra a seção Comportamento.
- Addable liga o botão de criar linha; Removable liga o × no fim de cada linha; Sortable liga a alça de arrastar no início.
- Dica é uma frase curta que aparece abaixo da lista — use para dizer o que cada linha representa.
- Na seção Eventos, quem programa pode ligar um método a cada momento: Ao adicionar linha, Ao remover linha e Ao totalizar — este último é o lugar certo para gravar o total do pedido.
Resultado para quem usa o sistema: a pessoa clica em Adicionar linha e o cursor já cai no primeiro campo da linha nova; para tirar uma linha, clica no × e confirma em Remover esta linha?.
Destaque
Remover é remover. Ao salvar, o que está na tela vira a verdade: linha mantida é
atualizada, linha nova é criada e linha tirada da tela é apagada do banco. Se um item precisa
ficar no histórico, dê a ele uma coluna de situação (cancelado, devolvido) em vez de removê-lo.
4
Configurar cada coluna
- Clique na engrenagem no cabeçalho da coluna, no canvas — ou na linha dela no acordeão Colunas.
- No cartão Coluna: Campo é a coluna da tabela filha, Label é o título que a pessoa lê, Largura é o espaço que ela ocupa.
- No cabeçalho do cartão Campo, escolha o Tipo: texto, número, dinheiro, data, escolha, tabela do banco… O tipo decide quais opções aparecem abaixo.
- Numa coluna ligada a outra tabela, o Datasource diz de onde vêm as opções; em Depende de, aponte a coluna da mesma linha que filtra esta.
- Obrigatório impede salvar com a célula vazia.
Resultado para quem usa o sistema: na linha do pedido, escolher o Tipo de Produto recarrega a lista de Produto só naquela linha — e escolher o produto já preenche o preço.
Destaque
O cartão Campo de uma coluna de texto mostra máscara, ícone e digitação forçada; o de
dinheiro mostra decimais e prefixo; o de escolha mostra as opções. Se aparecer Este tipo
não tem configurações específicas, está tudo certo: é um tipo simples.
5
Fórmula e totais
- Selecione a coluna do total da linha e deixe o Tipo em dinheiro ou número.
- Marque Read-only: a pessoa vê o resultado, não digita nele.
- Em Cálculo, clique em Adicionar fórmula e escreva a conta com os nomes das colunas entre chaves — por exemplo {quantidade} * {valor} - {desconto}.
- Em Formato, ajuste Decimais e Prefixo.
- No cartão Totalizador, marque Somar valores para a soma da coluna aparecer no rodapé — ou Contar linhas, quando o que importa é a quantidade.
Resultado para quem usa o sistema: o total da linha muda enquanto a pessoa digita a quantidade, sem esperar o servidor, e o rodapé mostra a soma de todas as linhas.
Destaque
Destaque
Clique no print para ampliar.
A soma do rodapé não grava nada. Ela é um cálculo de tela. O total do pedido, no
cadastro principal, é outro campo — e precisa ser gravado no evento Ao totalizar ou pelo
assistente que gerou a tela. Sem isso, a lista mostra a soma certa e o pedido grava zero.
6
Formulário por linha
- Selecione o Detail Form e, em Nome, dê o nome da lista.
- Modo decide onde o formulário da linha aparece: inline embutido acima da tabela, drawer numa gaveta lateral, modal numa janela no centro.
- Label Botão é o texto do botão que abre o formulário; Título do Form é o título da gaveta ou da janela.
- Em Tabela detalhe, escolha a tabela filha e siga o assistente: ele tem um terceiro passo, Dispor campos no formulário, onde você escolhe em quantas colunas os campos ficam e arrasta os cartões para a ordem certa.
- Em Layout, Colunas Form define em quantas colunas os campos são arrumados; Layout do Form em custom desliga a arrumação automática e respeita o que você montar.
- Os campos ficam dentro de Campos do formulário por linha e têm o mesmo painel dos campos comuns; as colunas da tabela ficam em Colunas, como numa listagem.
Resultado para quem usa o sistema: a pessoa clica em Adicionar endereço, a gaveta abre com o título Endereço, ela preenche e clica em Adicionar; o item entra na tabela embaixo, com lápis para editar e lixeira para remover.
Destaque
Destaque
Clique no print para ampliar.
No formulário por linha o botão de adicionar, o lápis e a lixeira existem sempre. Para impedir
que alguém inclua ou remova itens, use permissões — não há opção no componente para isso.
7
Testar antes de entregar
Salve a tela e publique no Teste online. Confira nesta ordem:
| O que fazer | O que tem que acontecer |
|---|---|
| Abrir um cadastro que já tem itens | As linhas dele aparecem, e só as dele. |
| Adicionar uma linha e salvar | Ao reabrir, a linha está lá. |
| Remover uma linha e salvar | Ao reabrir, a linha sumiu — do banco também. |
| Digitar quantidade e valor | O total da linha muda na hora, e o rodapé soma. |
| Mudar a coluna de que outra depende | A lista da coluna dependente recarrega só naquela linha. |
| Salvar com uma coluna obrigatória vazia | O navegador aponta a célula; nada é gravado. |
| No formulário por linha, editar um item | O botão vira Atualizar e a linha em edição fica destacada. |
09
Problemas comuns
Adiciono as linhas, salvo, e nada é gravado
A lista está ligada pela metade: falta a Tabela detalhe ou a Coluna FK. Os dois precisam estar preenchidos — sem um deles, o salvamento das linhas é pulado sem aviso.
O formulário não salva e só diz "Corrija os erros antes de continuar"
Uma coluna obrigatória da tabela filha não está na lista, e a mensagem de erro não tem onde aparecer. Adicione a coluna, ou tire a obrigatoriedade dela no modelo de dados. Republique.
Os valores das colunas somem ao salvar e o total dá zero
É um defeito antigo, já corrigido: depois de editar a tela no editor, o app deixava de reconhecer as colunas da lista. Atualize e republique o projeto.
Arrastei as linhas para outra ordem e, ao reabrir, voltou como estava
A ordem do arraste vale só na tela; as linhas voltam do banco na ordem em que foram criadas. Se a ordem importa, crie uma coluna de sequência na tabela filha e mostre-a na lista.
A lista soma certo, mas o total do pedido gravou zero
A soma do rodapé é de tela. O total do cadastro principal precisa ser gravado no evento Ao totalizar — ou pelo assistente que gerou a tela, que já faz isso.
As opções de uma coluna aparecem vazias ou mostram "Array"
As opções foram escritas fora do formato. Preencha Opções do combo pelo painel; se for escrever no código, use sempre pares valor e texto.
10
Referência: painel × código
Para quem também mexe no Blade, este é o de-para entre o painel e os atributos gerados. As colunas da tabela do formulário por linha são as mesmas da Listagem.
| No painel | No código | Padrão |
|---|---|---|
| Nome | name | — |
| Tabela detalhe | detail-table | — |
| Coluna FK | foreign-key | — |
| Model | model | — |
| Label Botão | add-label | Adicionar linha |
| Dica | hint | — |
| Addable | addable | — |
| Removable | removable | — |
| Sortable | sortable | — |
| Largura | width | — |
| Ao adicionar linha | on-add | — |
| Ao remover linha | on-remove | — |
| Ao totalizar | on-totalize | — |
| Campo (da coluna) | field | — |
| Label (da coluna) | label | — |
| Tipo (da coluna) | type | text |
| Largura (da coluna) | width | — |
| Placeholder | placeholder | — |
| Valor Default | default | — |
| Dica (da coluna) | hint | — |
| Read-only | readonly | — |
| Opções do combo | options | — |
| Obrigatório | required | — |
| Step | step | — |
| Max Length | maxlength | — |
| Ícone · Cor do ícone · Lado do ícone | icon · icon-color · icon-side | — |
| Forçar digitação | force-case | — |
| Máscara de digitação | mask | — |
| Remover máscara ao salvar | strip-mask | — |
| Largura máxima | max-width | — |
| Botão mostrar/esconder | toggle-password | — |
| Decimais | decimals | — |
| Prefixo | prefix | — |
| Datasource (da coluna) | model · display · order-by | — |
| Depende de | depends-on | — |
| Coluna FK (do combo dependente) | depends-column | — |
| Fórmula | compute | — |
| Somar valores | sum | — |
| Contar linhas | count | — |
| On Change | on-change | — |
| Desabilitar quando | disabled-when | — |
| Readonly quando | readonly-when | — |
| Obrigatório quando | required-when | — |
| Visível quando | visible-when | — |
| Nome (do formulário por linha) | name | — |
| Modo | mode | inline |
| Label Botão (do formulário por linha) | add-label | Adicionar |
| Título do Form | form-title | — |
| Colunas Form | form-cols | 2 |
| Layout do Form | form-layout | grid |
| Header Fixo | sticky | — |
| Por Página | per-page | sem paginação |
| Before Add | before-add | — |
| Before Delete | before-delete | — |
| Largura (do formulário por linha) | width | — |
| Campos do formulário por linha | <mad-detail-fields> | — |
| Colunas da lista do formulário por linha | <mad-columns> · <mad-col> | — |