Variáveis
Nota
O Microsoft Power Fx é o novo nome da linguagem de fórmula para aplicativos de tela. Estes artigos são um trabalho em andamento à medida que extraímos a linguagem de aplicativos de tela, a integramos a outros produtos do Microsoft Power Platform e a disponibilizamos como software livre. Comece com Visão geral do Microsoft Power Fx para obter uma introdução à linguagem.
Se você já usou outra ferramenta de programação, como Visual Basic ou JavaScript, você pode estar se perguntando: Onde estão as variáveis? O Microsoft Power Fx é um pouco diferente e requer uma abordagem diferente. Em vez de buscar uma variável ao escrever uma fórmula, pergunte-se: o que eu faria em uma planilha?
Em outras ferramentas, você pode ter realizado explicitamente um cálculo e armazenado o resultado em uma variável. No entanto, o Power Fx e o Excel automaticamente recalculam fórmulas à medida que os dados de entrada mudam, por isso geralmente não é necessário criar nem atualizar as variáveis. Ao utilizar essa abordagem sempre que possível, é mais fácil criar, compreender e manter seu aplicativo.
Em alguns casos, você precisará usar variáveis no Power Fx, que estende o modelo do Excel, adicionando fórmulas de comportamento. Essas fórmulas são executadas quando, por exemplo, um usuário seleciona um botão. Dentro de uma fórmula de comportamento, geralmente, é útil definir uma variável a ser usada em outras fórmulas.
Em geral, evite usar variáveis. Mas, às vezes, apenas uma variável pode habilitar a experiência que você deseja. As variáveis são implicitamente criadas e digitadas quando aparecem em funções que definem seus valores.
Converter o Excel no Power Fx
Excel
Vamos analisar o funcionamento do Excel. Uma célula pode conter um valor, como um número ou uma cadeia de caracteres ou uma fórmula com base nos valores de outras células. Depois que o usuário insere um valor diferente em uma célula, o Excel recalcula automaticamente todas as fórmulas que dependem do valor novo. Você não precisa fazer nenhuma programação para habilitar esse comportamento.
No exemplo a seguir, a célula A3 é definida como a fórmula A1 + A2. Se A1 ou A2 mudar, A3 será automaticamente recalculado para refletir a alteração. Esse comportamento não requer codificação fora da própria fórmula.
O Excel não tem variáveis. O valor de uma célula que contém uma fórmula muda com base em sua entrada, mas não há nenhuma maneira de lembrar o resultado de uma fórmula e armazená-lo em uma célula ou em qualquer outro lugar. Se você alterar o valor de uma célula, a planilha inteira poderá ser alterada e qualquer valor calculado anteriormente será perdido. Um usuário do Excel pode copiar e colar células, mas isso está sob o controle manual do usuário e não é possível com fórmulas.
Power Fx
A lógica que você cria no Power Fx se comporta de maneira muito parecida com o Excel. Em vez de atualizar células, é possível adicionar controles em qualquer local que desejar em uma tela e nomeá-los para uso em fórmulas.
Por exemplo, no Power Apps, você pode replicar o comportamento do Excel em um aplicativo adicionando um controle Rótulo, chamado TextBox1, e dois controles Entrada de texto, chamados TextInput1 e TextInput2. Se você definir a propriedade Texto de Label1 como TextInput1.Text + TextInput2.Text, ela sempre mostrará a soma de quaisquer números que estiverem em TextInput1 e TextInput2 automaticamente.
Observe que o controle Label1 está selecionado, mostrando sua fórmula Text na barra de fórmulas na parte superior da tela. Aqui, encontramos a fórmula TextInput1.Text + TextInput2.Text. Esta fórmula cria uma dependência entre esses controles, assim como as dependências são criadas entre as células em uma pasta de trabalho do Excel. Vamos alterar o valor de TextInput1:
A fórmula para Label1 foi automaticamente recalculada, exibindo o novo valor.
No Power Fx, você pode usar fórmulas para determinar não apenas o valor principal de um controle, mas também propriedades como a formatação. No próximo exemplo, uma fórmula para a propriedade Color do rótulo mostrará automaticamente os valores negativos em vermelho. A função If deve ser semelhante à do Excel:
If( Value(Label1.Text) < 0, Color.Red, Color.Black )
Você pode usar fórmulas para uma ampla variedade de cenários:
- Ao usar o GPS do seu dispositivo, um controle de mapa pode exibir seu local atual com uma fórmula que usa Location.Latitude e Location.Longitude. À medida que você se move, o mapa rastreará automaticamente seu local.
- Outros usuários podem atualizar as fontes de dados. Por exemplo, outras pessoas de sua equipe podem atualizar itens em uma lista do SharePoint. Quando você atualiza uma fonte de dados, todas as fórmulas dependentes são recalculadas automaticamente para refletir os dados atualizados. Ao aprofundar ainda mais o exemplo, você poderá definir a propriedade Items de uma galeria como a fórmula Filter( SharePointList), que exibirá automaticamente o conjunto de registros recém-filtrado.
Benefícios
Usar fórmulas para criar aplicativos tem muitas vantagens:
- Se você conhece o Excel, também conhece o Power Fx. O modelo e a linguagem de fórmula são os mesmos.
- Se você já usou outras ferramentas de programação, pense na quantidade de códigos necessária para executar esses exemplos. No Visual Basic, você precisaria escrever um manipulador de eventos para o evento de alteração em cada controle de entrada de texto. O código para realizar o cálculo em cada um deles é redundante e pode ficar fora de sincronia, ou você precisaria escrever uma sub-rotina comum. No Power Fx, você realizou tudo com uma única fórmula de uma linha.
- Para compreender de onde o texto de Label1 é proveniente, você sabe exatamente onde procurar: a fórmula na propriedade Text. Não há nenhuma outra forma de afetar o texto deste controle. Em uma ferramenta de programação tradicional, qualquer manipulador de eventos ou sub-rotina poderia alterar o valor do rótulo, de qualquer lugar no programa. Isso pode dificultar o rastreamento de quando e onde uma variável foi alterada.
- Se o usuário altera um controle deslizante e, em seguida, muda de ideia, ele pode alterar o controle deslizante de volta para seu valor original. E é como se nada nunca tivesse sido alterado: o aplicativo mostrará os mesmos valores de controle como fazia antes. Não há nenhuma ramificação para experimentar e perguntar "e se", assim como não há nada no Excel.
Em geral, se você puder obter um efeito usando uma fórmula, será melhor. Deixe que o mecanismo da fórmula no Power Fx trabalhe para você.
Saber quando usar variáveis
Vamos alterar nosso adicionador simples para atuar como uma calculadora antiga, com um total acumulado. Se você selecionar um botão Adicionar, um número será adicionado ao total acumulado. Se você selecionar um botão Limpar, redefinirá o total acumulado para zero.
| Exibir | Descrição |
|---|---|
 |
Quando o aplicativo é iniciado, o total acumulado é 0. O ponto vermelho representa o dedo do usuário na caixa de entrada de texto, onde o usuário insere 77. |
 |
O usuário seleciona o botão Adicionar. |
 |
77 são adicionados ao total acumulado. O usuário seleciona o botão Adicionar novamente. |
 |
77 é adicionado novamente ao total atual, resultando em 154. O usuário seleciona o botão Limpar. |
 |
O total acumulado é redefinido como 0. |
Nossa calculadora usa algo que não existe no Excel: um botão. Neste aplicativo, não é possível usar somente fórmulas para calcular o total acumulado porque seu valor depende de uma série de ações que o usuário realiza. Em vez disso, nosso total acumulado deve ser registrado e atualizado manualmente. A maioria das ferramentas de programação armazena essas informações em uma variável.
Às vezes, você precisará que uma variável para o seu aplicativo se comporte da maneira desejada. Mas a abordagem vem com advertências:
- Você deve atualizar manualmente o total acumulado. O recálculo automático não fará isso para você.
- O total acumulado não pode mais ser calculado com base nos valores de outros controles. Ele depende de quantas vezes o usuário selecionou o botão Adicionar e qual valor estava no controle de entrada de texto em cada uma das vezes. O usuário inseriu 77 e selecionou Adicionar duas vezes, ou ele especificou 24 e 130 para cada uma das adições? Você não pode determinar a diferença depois que o total atingiu 154.
- As alterações no total podem vir de caminhos diferentes. Neste exemplo, os botões Adicionar e Limpar podem atualizar o total. Se o aplicativo não se comportar da maneira esperada, qual botão estará causando o problema?
Usar uma variável global
Para criar nossa calculadora, precisamos de uma variável para manter o total acumulado. As variáveis mais simples para trabalhar com Power Fx são variáveis globais.
Como variáveis globais funcionam:
- Defina o valor da variável global com a função Set. Set (MyVar, 1) define a variável global MyVar como um valor 1.
- Você usa a variável global referenciando o nome usado com a função Set. Nesse caso, MyVar retornará 1.
- Variáveis globais podem conter qualquer valor, incluindo cadeias de caracteres, números, registros e tabelas.
Recompilaremos nossa calculadora usando uma variável global:
Adicione um controle de entrada de texto, chamado TextInput1, e dois botões, chamados Button1 e Button2.
Defina a propriedade Text de Button1 como "Add" e defina a propriedade Text de Button2 como "Clear".
Para atualizar o total acumulado sempre que um usuário seleciona o botão Add, defina sua propriedade OnSelect como esta fórmula:
Set( RunningTotal, RunningTotal + TextInput1.Text )
A mera existência dessa fórmula estabelece RunningTotal como uma variável global que contém um número por causa do operador +. Você pode referenciar RunningTotal em qualquer lugar do aplicativo. Sempre que o usuário abre este aplicativo, RunningTotal tem um valor inicial em branco.
A primeira vez que um usuário seleciona o botão Add e Set é executado, RunningTotal é definido como o valor RunningTotal + TextInput1.
Para definir o total acumulado como 0 sempre que o usuário selecionar o botão Clear, defina sua propriedade OnSelect como esta fórmula:
Set( RunningTotal, 0 )
Adicione um controle Label e defina sua propriedade Text como RunningTotal.
Esta fórmula será automaticamente recalculada e exibirá ao usuário o valor de RunningTotal à medida que ele mudar de acordo com os botões que o usuário selecionar.
Visualize o aplicativo e nossa calculadora estará como descrito acima. Insira um número na caixa de texto e pressione o botão Add algumas vezes. Quando estiver pronto, retorne para a experiência de criação usando a tecla Esc.
Para mostrar o valor da variável global, selecione o menu Arquivo e selecione Variáveis no painel à esquerda.
Para mostrar todos os locais em que a variável é definida e usada, selecione-a.
Tipos de variáveis
O Power Fx tem dois tipos de variáveis:
| Tipo de variáveis | Scope | Description | Funções que estabelecem |
|---|---|---|---|
| Variáveis globais | Aplicativo | O mais simples de usar. Contém um número, cadeia de caracteres de texto, booliano, registro, tabela, etc. que podem ser referências de qualquer lugar no aplicativo. | Set |
| Coleções | Apl | Mantém uma tabela que pode ser referenciada de qualquer lugar no aplicativo. Permite que o conteúdo da tabela seja modificado em vez de ser definido como um todo. Pode ser salvo para o dispositivo local para uso posterior. | Collect ClearCollect |
Quando usado no Power Apps, existe um terceiro tipo de variável:
| Tipo de variáveis | Scope | Descrição | Funções que estabelecem |
|---|---|---|---|
| Variáveis de contexto | Tela | Excelente para passar valores para uma tela, bem como parâmetros para um procedimento em outras linguagens. Pode ser referenciada somente de uma tela. | UpdateContext Navigate |
Criar e remover variáveis
Todas as variáveis são criadas implicitamente quando aparecem em uma função Set, UpdateContext, Navigate, Collect ou ClearCollect. Para declarar uma variável e seu tipo, você só precisa incluí-la em qualquer uma dessas funções em qualquer lugar do seu aplicativo. Nenhuma dessas funções cria variáveis; eles apenas preenchem variáveis com valores. Você nunca declara variáveis explicitamente como faria em outra ferramenta de programação, e toda a digitação está implícita no uso.
Por exemplo, você pode ter um controle de botão com uma fórmula OnSelect igual a Set( X, 1 ). Esta fórmula estabelece X como uma variável com um tipo de número. Você pode usar X em fórmulas como um número, e essa variável tem um valor em branco depois de abrir o aplicativo, mas antes de selecionar o botão. Quando você seleciona o botão, você dá X o valor 1.
Se você tiver adicionado outro botão e definiu sua propriedade OnSelect como Set( X, "Hello" ), ocorreria um erro porque o tipo (cadeia de caracteres de texto) não corresponde ao tipo no Set (número) anterior. Todas as definições implícitas da variável devem concordar com o tipo. Mais uma vez, tudo isso aconteceu porque você mencionou X nas fórmulas, não porque nenhuma dessas fórmulas tenha sido executada.
Você remove uma variável removendo todas as funções Set, UpdateContext, Navigate, Collect ou ClearCollect que estabelecem implicitamente a variável. Sem essas funções, a variável não existe. Você também deve remover todas as referências à variável, pois elas causarão um erro.
Vida útil e valor inicial da variável
Todas as variáveis são mantidas na memória enquanto o aplicativo está em execução. Depois que o aplicativo é fechado, os valores que as variáveis contêm são perdidos.
Você pode armazenar o conteúdo de uma variável em um fonte de dados usando as funções Patch ou Collect. Você também pode armazenar valores em coleções no dispositivo local usando a função SaveData.
Quando o usuário abre o aplicativo, todas as variáveis têm um valor inicial em branco.
Como ler variáveis
Você pode usar o nome da variável para ler o valor dela. Por exemplo, você pode definir uma variável com esta fórmula:
Set( Radius, 12 )
Então você pode simplesmente usar Radius em qualquer lugar que você possa usar um número, e ele será substituído por 12:
Pi() * Power( Radius, 2 )
Se você der a uma variável de contexto o mesmo nome que uma variável global ou uma coleção, a variável de contexto terá precedência. No entanto, você ainda poderá referenciar a variável global ou coleção se usar o operador de desambiguação[@Radius].
Usar uma variável de contexto (somente no Power Apps)
Examinaremos como nossa calculadora seria criada usando uma variável de contexto em vez de uma variável global.
Como funcionam as variáveis de contexto:
- Você estabelece e define variáveis de contexto implicitamente usando a função UpdateContext ou Navigate. Quando o aplicativo é iniciado, o valor inicial de todas as variáveis de contexto é em branco.
- Atualize as variáveis de contexto com registros. Em outras ferramentas de programação, geralmente você usa "=" para a atribuição, como em "x = 1". Para variáveis de contexto, use { x: 1 } em vez disso. Ao usar uma variável de contexto, use seu nome diretamente sem a sintaxe do registro.
- Também é possível definir uma variável de contexto quando você usa a função Navigate para mostrar uma tela. Se pensar em uma tela como um tipo de procedimento ou uma sub-rotina,essa abordagem é semelhante ao parâmetro que passa em outras ferramentas de programação.
- Exceto para Navigate, as variáveis de contexto são limitadas ao contexto de uma única tela, que é de onde elas obtêm o nome. Você não pode usar nem defini-las fora deste contexto.
- As variáveis de contexto podem conter qualquer valor, incluindo cadeias de caracteres, números, registros e tabelas.
Vamos recompilar nossa calculadora usando uma variável de contexto:
Adicione um controle de entrada de texto, chamado TextInput1, e dois botões, chamados Button1 e Button2.
Defina a propriedade Text de Button1 como "Add" e defina a propriedade Text de Button2 como "Clear".
Para atualizar o total acumulado sempre que um usuário seleciona o botão Add, defina sua propriedade OnSelect como esta fórmula:
UpdateContext( { RunningTotal: RunningTotal + TextInput1.Text } )
A mera existência dessa fórmula estabelece RunningTotal como uma variável de contexto que contém um número por causa do operador +. Você pode referenciar RunningTotal em qualquer lugar nesta tela. Sempre que o usuário abre este aplicativo, RunningTotal tem um valor inicial em branco.
A primeira vez em que o usuário seleciona o botão Add e UpdateContext é executado, RunningTotal é definido como o valor RunningTotal + TextInput1.
Para definir o total acumulado como 0 sempre que o usuário selecionar o botão Clear, defina sua propriedade OnSelect como esta fórmula:
UpdateContext( { RunningTotal: 0 } )
Novamente, UpdateContext é usado com a fórmula UpdateContext( { RunningTotal: 0 } ).
Adicione um controle Label e defina sua propriedade Text como RunningTotal.
Esta fórmula será automaticamente recalculada e exibirá ao usuário o valor de RunningTotal à medida que ele mudar de acordo com os botões que o usuário selecionar.
Visualize o aplicativo e nossa calculadora estará como descrito acima. Insira um número na caixa de texto e pressione o botão Add algumas vezes. Quando estiver pronto, retorne para a experiência de criação usando a tecla Esc.
Você pode definir o valor de uma variável de contexto ao navegar para uma tela. Isso é útil para a passagem de "contexto" ou de "parâmetros" de uma tela para outra. Para demonstrar essa técnica, insira uma tela, insira um botão e defina sua propriedade OnSelect como esta fórmula:
Navigate( Screen1, None, { RunningTotal: -1000 } )
Mantenha pressionada a tecla Alt enquanto seleciona este botão para mostrar Screen1 e defina a variável de contexto RunningTotal como -1000.
Para mostrar o valor da variável de contexto, selecione o menu Arquivo e selecione Variáveis no painel à esquerda.
Para mostrar onde a variável de contexto é definida e usada, selecione-a.
Usar uma coleção
Por fim, examinaremos a criação de nossa calculadora com uma coleção. Já que uma coleção contém uma tabela que é fácil de modificar, faremos com que essa calculadora mantenha uma "fita de papel" de cada valor conforme eles forem inseridos.
Como coleções funcionam:
- Crie e defina coleções usando a função ClearCollect. Como alternativa, você pode usar a função Collect, mas isso exigirá efetivamente outra variável em vez de substituir a antiga.
- Uma coleção é um tipo de fonte de dados e, portanto, uma tabela. Para acessar um único valor em uma coleção, use a função First e extraia um campo do registro resultante. Se você usar um único valor com ClearCollect, esse será o campo Value, como neste exemplo:
First(VariableName).Value
Vamos recriar nossa calculadora usando uma coleção:
Adicione um controle de Entrada de texto, chamado TextInput1, e dois botões, chamados Button1 e Button2.
Defina a propriedade Text de Button1 como "Add" e defina a propriedade Text de Button2 como "Clear".
Para atualizar o total acumulado sempre que um usuário seleciona o botão Add, defina sua propriedade OnSelect como esta fórmula:
Collect( PaperTape, TextInput1.Text )
A mera existência dessa fórmula estabelece PaperTape como uma coleção que contém uma tabela de coluna única de cadeias de texto. Você pode referenciar PaperTape em qualquer lugar deste aplicativo. Sempre que um usuário abrir este aplicativo, PaperTape será uma tabela vazia.
Quando essa fórmula for executada, ela adicionará o novo valor ao final da coleção. Já que estamos adicionando um único valor, Collect posiciona automaticamente esse valor em uma tabela de coluna única, e o nome da coluna é Value, que você usará mais tarde.
Para limpar a fita de papel quando o usuário seleciona o botão Clear, defina sua propriedade OnSelect como esta fórmula:
Clear( PaperTape )
Para adicionar o total acumulado, adicione um rótulo e defina sua propriedade Text como esta fórmula:
Sum( PaperTape, Value )
Para executar a calculadora, pressione F5 para abrir a Visualização, insira números no controle de entrada de texto e selecione botões.
Para retornar ao espaço de trabalho padrão, pressione a tela Esc.
Para exibir a fita de papel, insira um controle Data table e defina sua propriedade Items como esta fórmula:
PaperTape
No painel direito, selecione Editar campos, Adicionar campo, a coluna Valor e Adicionar para exibi-lo.
Para ver os valores em sua coleção, selecione Coleções no menu Arquivo.
Para armazenar e recuperar sua coleção, adicione dois controles de botão adicionais e defina as propriedades Text como Load e Save. Defina a propriedade OnSelect do botão Load como esta fórmula:
Clear( PaperTape ); LoadData( PaperTape, "StoredPaperTape", true )
É preciso limpar a coleção primeiro, já que LoadData acrescentará os valores armazenados no final da coleção.
Defina a propriedade OnSelect do botão para Save conforme esta fórmula:
SaveData( PaperTape, "StoredPaperTape" )
Visualize novamente pressionando a tecla F5, insira números no controle de entrada de texto e selecione os botões. Selecione o botão Salvar. Feche e recarregue o aplicativo e, em seguida, selecione o botão Load para recarregar sua coleção.