Galerias e formulários no Power Apps

Galerias e formulários no Power Apps travam na hora de listar e salvar, e o problema quase nunca é o dado#

Quase todo app de linha de negócio faz duas coisas o tempo todo: mostra uma lista de registros e deixa alguém abrir um item para editar e salvar. Parece trivial, mas é exatamente aí que a maioria dos apps que a gente recebe para revisar começa a ranger. A lista carrega devagar, o filtro esconde metade dos registros sem avisar, o botão de salvar às vezes grava e às vezes não, e ninguém sabe explicar por quê. Na quase totalidade dos casos o dado está certo. Galerias e formulários no Power Apps são os dois controles que sustentam esse fluxo, e é o uso errado deles que faz o app ranger.

Galerias e formulários são os dois blocos de construção que sustentam esse fluxo. A galeria é a lista, o formulário é a ficha de edição, e a ligação entre os dois é o que transforma um monte de controle solto em um app que as pessoas conseguem usar. Neste artigo eu mostro, com exemplos de Power Fx, como exibir dados, filtrar e ordenar sem quebrar nada, validar e gravar com SubmitForm e montar o clássico padrão mestre-detalhe. Se você ainda está decidindo o tipo de app, vale ler antes o guia de Power Platform, Power Apps e Power Automate.

Galeria e formulário resolvem problemas diferentes, e confundir isso custa caro#

Antes de qualquer fórmula, fixe a divisão de trabalho. A galeria existe para exibir uma coleção de registros. O formulário existe para editar ou mostrar um registro por vez. Quem tenta usar a galeria para editar, ou o formulário para listar, acaba escrevendo o triplo de código para fazer metade do trabalho.

Aspecto	Galeria	Formulário (Edit/Display)
Para que serve	Listar vários registros	Mostrar ou editar um registro
Propriedade central	Items (a tabela de registros)	DataSource e Item
Como interage	Seleção, rolagem, filtro	Cartões de campo, entrada de dados
Como grava	Não grava, só exibe	SubmitForm grava a fonte de dados
Estado	Selected, AllItems	DisplayMode, Mode, Unsaved

A regra prática é curta: se o objetivo é escolher, use galeria; se o objetivo é preencher, use formulário. Os dois juntos, conectados pela seleção, dão conta de quase todo cadastro de negócio.

A galeria exibe uma tabela de registros pela propriedade Items#

A propriedade que faz a galeria funcionar é a Items. Você entrega a ela uma tabela de registros e a galeria desenha uma linha por registro. Pode ser uma tabela do Dataverse, uma lista do SharePoint, uma coleção local ou o resultado de uma função. No caso mais simples, Items é só o nome da fonte:

// Galeria simples: todos os pedidos
Gallery_Pedidos.Items = Pedidos

Dentro da galeria, cada rótulo referencia o campo do registro daquela linha usando ThisItem. É assim que você mostra cliente, valor e data em cada linha:

// Dentro de um rótulo da galeria
Text( ThisItem.Cliente )
Text( ThisItem.Valor, "[$-pt-BR]R$ #.##0,00" )
Text( ThisItem.DataPedido, "dd/mm/yyyy" )

Filtrar e ordenar sem esbarrar na delegação#

Na prática você quase nunca quer todos os registros. Quer os pedidos em aberto, ordenados por data. Para isso, envolva a fonte em Filter, Sort ou Search:

// Pedidos em aberto, do mais recente para o mais antigo
Gallery_Pedidos.Items =
    Sort(
        Filter( Pedidos, Status = "Em aberto" ),
        DataPedido,
        SortOrder.Descending
    )

Para uma caixa de busca por texto, o Search casa bem com uma entrada de texto na tela:

// Busca pelo nome do cliente digitado em txtBusca
Gallery_Pedidos.Items =
    Search( Pedidos, txtBusca.Text, "Cliente" )

Aqui entra o conceito que mais derruba app na produção: a delegação. O Power Apps não traz a base inteira para o dispositivo. Ele empurra o filtro e a ordenação para a fonte de dados processar e devolver só o resultado. Quando a função usada na Items da galeria é delegável para aquela fonte, tudo funciona mesmo com milhões de linhas. Quando não é, o Power Apps processa apenas as primeiras linhas (o limite padrão é 500, ajustável até 2000) e o resto simplesmente não aparece. O app não dá erro, ele mente por omissão, e é por isso que "sumiram registros" é uma queixa tão comum.

Função na Items	Delegável no Dataverse	Delegável no SharePoint	Observação
Filter com =	Sim	Sim	Comparação de igualdade é segura
Filter com <, >	Sim	Sim	Em colunas numéricas e de data
Sort	Sim	Sim	Por coluna simples
Search	Sim	Parcial	Depende da coluna e do conector
Filter com in	Parcial	Não	Costuma avisar com sublinhado azul
Cálculo dentro do Filter	Não	Não	Traga a coluna já calculada da fonte

O editor sublinha em azul o trecho não delegável e mostra um aviso. Trate esse aviso como bug, não como enfeite. Quando não der para fugir dele, filtre por uma coluna delegável primeiro para reduzir o volume, e só depois aplique o refino local. Esse cuidado com o volume de dados é o mesmo que defendemos nos projetos de engenharia de dados: o processamento pesado mora perto da fonte, não no cliente.

O formulário grava com SubmitForm, e o DisplayMode decide o que o usuário pode fazer#

O formulário de edição (Edit Form) é o controle que lê um registro, mostra um cartão por campo e grava as alterações. Ele tem duas propriedades que amarram tudo: DataSource, que diz onde gravar, e Item, que diz qual registro carregar.

Form_Pedido.DataSource = Pedidos
Form_Pedido.Item = Gallery_Pedidos.Selected

O formulário opera em modos, e é o modo que define o comportamento na hora de salvar:

1. NewForm prepara o formulário em branco para criar um registro novo.
2. EditForm carrega o registro do Item para alteração.
3. ViewForm (Display Form) mostra o registro só para leitura, sem edição.

Você troca de modo com funções nos botões, não editando propriedade na mão:

// Botão "Novo"
NewForm( Form_Pedido )

// Botão "Editar" a partir do item selecionado
EditForm( Form_Pedido )

A gravação em si é uma linha:

// Botão "Salvar"
SubmitForm( Form_Pedido )

O SubmitForm faz o trabalho pesado: valida os cartões, escreve na fonte de dados, respeita se é criação ou edição conforme o modo e ainda expõe o resultado. A propriedade DisplayMode do formulário reflete tudo isso: em NewForm e EditForm ela fica editável, em ViewForm fica em DisplayMode.View. Você pode ler essa propriedade para habilitar ou esconder o botão de salvar, evitando que alguém tente gravar num formulário que está só em leitura.

Reaja ao sucesso e ao erro, não confie na sorte#

O erro clássico é colocar SubmitForm e, na mesma fórmula, já mandar navegar de volta para a lista. Se a gravação falhar, o usuário sai da tela achando que salvou. O jeito correto é separar as reações usando OnSuccess e OnFailure do formulário:

// Form_Pedido.OnSuccess
Notify( "Pedido salvo com sucesso.", NotificationType.Success );
Back()

// Form_Pedido.OnFailure
Notify( "Não foi possível salvar. Verifique os campos.", NotificationType.Error )

Assim a navegação só acontece quando a gravação de fato deu certo. Esse é o tipo de detalhe que separa um protótipo de um app que a operação confia, e é padrão em toda entrega da nossa equipe de Power Platform.

Validação: barre o dado ruim antes de gravar#

Há três camadas de validação, e usar as três é o normal em app sério:

1. Campo obrigatório no cartão: marque Required no cartão do formulário. O SubmitForm recusa gravar se faltar.
2. Regra de negócio no Power Fx: valide antes de chamar o SubmitForm.
3. Regra na fonte de dados: colunas obrigatórias e tipos no Dataverse são a última linha de defesa.

Um exemplo de validação de regra antes de gravar, no botão de salvar:

// Botão "Salvar" com checagem de regra
If(
    DataValue( Form_Pedido, "Valor" ) <= 0,
    Notify( "O valor precisa ser maior que zero.", NotificationType.Error ),
    SubmitForm( Form_Pedido )
)

O padrão mestre-detalhe liga a galeria ao formulário pelo Gallery.Selected#

Aqui os dois controles viram um app de verdade. O padrão mestre-detalhe é: uma galeria à esquerda com a lista (o mestre) e um formulário à direita com o registro escolhido (o detalhe). A cola entre eles é a propriedade Selected da galeria, que sempre aponta para o registro da linha em que o usuário clicou.

Você liga o formulário à seleção assim:

// O detalhe segue o item escolhido no mestre
Form_Pedido.Item = Gallery_Pedidos.Selected

Quando alguém clica em outra linha da galeria, Gallery_Pedidos.Selected muda, o Item do formulário muda junto e o detalhe se atualiza sozinho. Não precisa de variável nem de código extra para isso funcionar.

Um fluxo mestre-detalhe completo, botão a botão, costuma ficar assim:

Ação do usuário	Controle	Fórmula
Escolher um registro	Galeria (OnSelect)	EditForm( Form_Pedido )
Criar novo	Botão "Novo"	NewForm( Form_Pedido )
Salvar	Botão "Salvar"	SubmitForm( Form_Pedido )
Cancelar edição	Botão "Cancelar"	ResetForm( Form_Pedido )
Excluir	Botão "Excluir"	Remove( Pedidos, Gallery_Pedidos.Selected )

Duas dicas que economizam horas de suporte. Primeira: depois de criar um registro com NewForm e salvar, a galeria já reflete o novo item porque a fonte de dados é a mesma; você não precisa recarregar nada. Segunda: use Form_Pedido.Unsaved para avisar quando há alteração pendente, evitando que a pessoa troque de registro e perca o que digitou.

// Alerta de alteração não salva ao tentar sair
If( Form_Pedido.Unsaved,
    Notify( "Você tem alterações não salvas.", NotificationType.Warning ),
    Back()
)

Esse mesmo padrão sustenta cadastros, aprovações e apoios operacionais que a gente entrega dentro do portfólio de soluções. Muda o dado, muda o layout, mas a espinha dorsal galeria mais formulário mais seleção é sempre a mesma.

Perguntas frequentes#

Qual a diferença entre galeria e formulário no Power Apps? A galeria exibe uma tabela de registros pela propriedade Items, ou seja, mostra vários itens ao mesmo tempo em formato de lista. O formulário trabalha com um registro por vez, para exibir (Display Form) ou editar e criar (Edit Form), e é ele quem grava na fonte de dados com SubmitForm. Um lista, o outro edita.

Como salvar os dados de um formulário? Use SubmitForm( NomeDoFormulario ) num botão. Essa função valida os cartões, decide entre criar ou atualizar conforme o modo do formulário e escreve na fonte definida em DataSource. Trate o resultado em OnSuccess e OnFailure para só navegar depois de confirmar que a gravação deu certo.

Por que minha galeria não mostra todos os registros? Quase sempre é delegação. Quando a função usada na Items não é delegável para aquela fonte, o Power Apps processa só as primeiras linhas (500 por padrão, até 2000) e ignora o resto sem dar erro. O editor sublinha o trecho em azul. Filtre por uma coluna delegável, como uma igualdade simples, para trazer o conjunto certo.

Como conectar a galeria ao formulário no padrão mestre-detalhe? Aponte a propriedade Item do formulário para Gallery.Selected. Quando o usuário clica numa linha, a seleção muda e o formulário passa a mostrar o registro escolhido automaticamente. É a ligação nativa entre lista e detalhe, sem precisar de variável.

Como validar campos antes de gravar? Combine três camadas: marque Required nos cartões do formulário, escreva regras de negócio em Power Fx antes de chamar o SubmitForm (por exemplo, barrar valor menor ou igual a zero) e mantenha colunas obrigatórias na própria fonte de dados. Assim o dado ruim é barrado antes de chegar ao banco.

Galerias e formulários servem para canvas e model-driven? Galeria e Edit/Display Form com SubmitForm são controles do app canvas. No model-driven a interface é gerada pelo modelo de dados e usa grades e formulários próprios da plataforma. Se você está em dúvida sobre qual tipo usar, veja nosso comparativo em Power Apps canvas x model-driven.

Onde isso te leva#

Galeria para listar, formulário para editar e a seleção ligando os dois: com esse tripé e um pouco de disciplina com delegação e validação, você cobre a maior parte dos apps de linha de negócio sem gambiarra. O resto é repetição do mesmo padrão sobre dados diferentes.

Se você quer acelerar esse caminho ou colocar um app assim em produção com governança de verdade, fale com a gente. A gente ajuda a tirar a ideia do quadro branco e botar na mão de quem usa.