Como usar a função Patch no Power Apps: passo a passo

A função Patch é uma das ferramentas mais poderosas do Power Apps: permite criar e atualizar registos numa fonte de dados com total controlo, campo a campo, sem depender de um formulário automático. Saber como usar Patch no Power Apps é essencial quando precisa de gravar apenas alguns campos, escrever em mais do que uma tabela ou construir ecrãs de edição à medida. Ao contrário do SubmitForm, que está preso a um controlo de formulário, o Patch funciona em qualquer sítio da aplicação.

Pré-requisitos

• Uma conta com acesso ao Power Apps para criar uma Canvas App.
• Uma fonte de dados ligada, como uma lista do SharePoint ou uma tabela do Dataverse.
• Noções básicas de controlos: ecrãs, botões, galerias e caixas de texto.

Passo 1: Ligar a fonte de dados

Abra a Canvas App e, no painel Dados, adicione a fonte onde vai gravar. Neste exemplo usamos uma lista do SharePoint chamada Contactos com três colunas: Title (o nome), Email e Telefone. Depois de ligada, a fonte passa a estar disponível pelo nome em qualquer fórmula. Adicione ainda três caixas de texto ao ecrã e mude o nome para txtNome, txtEmail e txtTelefone, para as fórmulas ficarem fáceis de ler.

Passo 2: Criar um novo registo com Patch e Defaults

Para criar um registo do zero, combinamos Patch com a função Defaults. O Defaults devolve um registo vazio com os valores por omissão da fonte, e o Patch preenche apenas os campos que indicarmos. Adicione um botão e, na propriedade OnSelect, escreva:

Patch(
    Contactos,
    Defaults(Contactos),
    {
        Title: txtNome.Text,
        Email: txtEmail.Text,
        Telefone: txtTelefone.Text
    }
)

Quando clicar no botão, é criado um item novo na lista com os valores escritos nas três caixas de texto. Repare que o nome dos campos, à esquerda dos dois pontos, tem de corresponder ao nome interno das colunas na fonte de dados.

Passo 3: Atualizar um registo existente

Para atualizar, trocamos o Defaults pelo registo que queremos alterar. Se o utilizador escolheu uma linha numa galeria, o registo selecionado está em Gallery1.Selected. Uma grande vantagem do Patch é que só mexe nos campos que enviarmos: todos os outros ficam exatamente como estavam.

Patch(
    Contactos,
    Gallery1.Selected,
    { Telefone: txtTelefone.Text }
)

Em alternativa, pode encontrar o registo pelo seu identificador com LookUp. É prático quando guardou o ID numa variável:

Patch(
    Contactos,
    LookUp(Contactos, ID = varId),
    { Email: txtEmail.Text }
)

Passo 4: Validar antes de gravar

Antes de gravar, convém verificar se os campos obrigatórios estão preenchidos. Use If com IsBlank para só chamar o Patch quando os dados forem válidos:

If(
    IsBlank(txtNome.Text),
    Notify("O nome é obrigatório.", NotificationType.Error),
    Patch(Contactos, Defaults(Contactos), { Title: txtNome.Text })
)

Assim evita registos incompletos e dá uma mensagem clara ao utilizador quando falta informação.

Passo 5: Guardar o resultado e dar feedback

O Patch devolve o registo que criou ou alterou. Guarde-o numa variável com Set para o reutilizar, por exemplo para mostrar o ID gerado, e avise o utilizador com Notify. No fim, Reset limpa a caixa de texto para o próximo registo:

Set(
    regGravado,
    Patch(Contactos, Defaults(Contactos), { Title: txtNome.Text })
);
Notify("Contacto guardado com sucesso!", NotificationType.Success);
Reset(txtNome)

Verificar o resultado

Para confirmar que correu tudo bem, abra a fonte de dados (a lista do SharePoint ou a tabela do Dataverse) e veja se o registo aparece com os valores corretos. Dentro da app, adicione uma galeria ligada a Contactos: ao gravar, o novo item surge de imediato na lista, porque o Power Apps atualiza a fonte automaticamente. Se usou Notify, deve ver a mensagem verde de sucesso no topo do ecrã. Caso apareça um erro de coluna, confirme que os nomes dos campos coincidem com os da fonte.

Conclusão

Com o Patch passa a ter controlo total sobre como e quando os dados são gravados no Power Apps, algo que os formulários automáticos nem sempre permitem. A partir daqui, experimente gravar em duas fontes no mesmo botão, ou usar Patch com uma coleção para gravar vários registos de uma só vez. Qual é o primeiro ecrã da sua aplicação que vai simplificar com Patch?