Variáveis Power Fx

Aprenda como as variáveis Power Fx diferem das variáveis em ferramentas como Visual Basic ou JavaScript, e quando as fórmulas são uma escolha melhor. Este artigo explica como escolher variáveis globais, variáveis de contexto ou coleções para gerir os valores e o estado da aplicação.

Em outras ferramentas, você pode executar explicitamente um cálculo e armazenar o resultado em uma variável. No entanto, o Power Fx e o Excel recalculam automaticamente as fórmulas à medida que os dados de entrada mudam, pelo que, normalmente, não é necessário criar e atualizar variáveis. Ao seguir esta abordagem sempre que possível, pode criar, compreender e manter a sua aplicação mais facilmente.

Em alguns casos, precisas de usar variáveis no Power Fx. O Power Fx estende o modelo do Excel adicionando fórmulas de comportamento. Estas fórmulas são executadas quando, por exemplo, um utilizador seleciona um botão. Dentro de uma fórmula de comportamento, é frequentemente útil definir uma variável para usar noutras fórmulas.

Em geral, evite utilizar variáveis. Contudo, há casos em que só as variáveis podem proporcionar a experiência que procura. Implicitamente, crias e tipas variáveis quando aparecem em funções que definem os seus valores.

Traduzir o Excel no Power Fx

Excel

Vamos rever o funcionamento do Excel. As células podem conter valores, como números ou cadeias, ou fórmulas que tenham por base os valores de outras células. Após o utilizador introduzir um valor diferente numa célula, o Excel recalcula automaticamente todas as fórmulas que dependem do valor novo. Não tem de fazer qualquer programação para permitir este comportamento.

No exemplo seguinte, a célula A3 está definida com a fórmula A1+A2. Se A1 ou A2 forem alterados, A3 será recalculado automaticamente para refletir a alteração. Este comportamento não requer codificação fora da fórmula propriamente dita.

O Excel não tem variáveis. O valor de uma célula que contenha uma fórmula altera-se com base no que é introduzido, mas não há forma de memorizar o resultado de uma fórmula e armazená-lo numa célula ou noutro sítio qualquer. Se mudares o valor de uma célula, toda a folha de cálculo pode mudar, e quaisquer valores previamente calculados são perdidos. Os utilizadores do Excel podem copiar e colar células, mas essa operação está sob o controlo manual deles e não é possível com as fórmulas.

Potência Fx

A lógica que criar no Power Fx comporta-se de forma muito semelhante ao Excel. Em vez de atualizar as células, pode adicionar controlos onde quiser num ecrã e dar-lhes nomes para utilização em fórmulas.

Por exemplo, no Power Apps, pode replicar o comportamento do Excel numa aplicação ao adicionar um controlo de Etiqueta, com o nome Label1 e dois controlos de Entrada de texto, com os nomes TextInput1 and TextInput2. Se depois definires a propriedade Texto do Label1 para TextInput1.Text + TextInput2.Text, ela mostra sempre automaticamente a soma dos números que estão em TextInput1 e TextInput2 .

Repare que o controlo Label1 está selecionado e que mostra a respetiva fórmula Text na barra de fórmulas, na parte superior do ecrã. Aqui encontras a fórmula TextInput1.Text + TextInput2.Text. Esta fórmula cria uma dependência entre estes controlos, da mesma forma que as dependências são criadas entre células nos livros do Excel. Vamos alterar o valor de TextInput1:

A fórmula do Label1 é automaticamente recalculada, mostrando o novo valor.

No Power Fx, pode utilizar as fórmulas para determinar não só o valor principal de um controlo, mas também as propriedades, como a formatação. No exemplo seguinte, uma fórmula para a propriedade Color do rótulo mostra automaticamente valores negativos em vermelho. A função If deve ser familiar, por causa do Excel:

If( Value(Label1.Text) < 0, Color.Red, Color.Black )

Pode utilizar fórmulas para diversos cenários:

• Se utilizar o GPS do seu dispositivo, um controlo de mapa pode mostrar a sua localização atual com uma fórmula que utiliza Location.Latitude e Location.Longitude. À medida que se move, o mapa regista automaticamente a sua localização.
• As origens de dados podem ser atualizadas por outros utilizadores. Por exemplo, outras pessoas da sua equipa poderão atualizar itens numa lista do SharePoint. Quando atualiza uma fonte de dados, quaisquer fórmulas dependentes recalculam automaticamente para refletir os dados atualizados. Continuando o exemplo, pode definir a propriedade Itens de uma galeria para a fórmula Filter( SharePointList ), que mostra automaticamente o novo conjunto de registos filtrado.

Benefícios das fórmulas Power Fx

Usar fórmulas para construir aplicações oferece muitas vantagens:

• Se conhece o Excel, também conhece o Power Fx. Os modelos e a linguagem das fórmulas são iguais.
• Se usares outras ferramentas de programação, considera quanto código precisarias para realizar estes exemplos. No Visual Basic, teria de escrever um processador de eventos para o evento de alteração em cada controlo de entrada de texto. O código para realizar o cálculo em cada um destes gestores de eventos é redundante e pode ficar fora de sincronização, ou teria de escrever uma sub-rotina comum. No Power Fx, realizas todo esse trabalho com uma única fórmula de uma linha.
• Para perceber de onde vem o texto do Label1, sabes exatamente onde procurar: a fórmula na propriedade Texto . Não existe nenhuma outra forma de afetar o texto deste controlo. Numa ferramenta de programação tradicional, qualquer processador de eventos ou subrotina poderia alterar o valor da etiqueta em qualquer parte do programa. Esta abordagem pode dificultar a identificação de quando e onde uma variável foi alterada.
• Se o utilizador altera um controlo de deslize e, em seguida, mudar de ideias, pode modificar o controlo para o valor original. É como se nada tivesse mudado: a aplicação mostra os mesmos valores de controlo de antes. Não há consequências para experimentar e perguntar “e se”, tal como não as há no Excel.

Em geral, se conseguires um efeito usando uma fórmula, é melhor para ti. Ponha o motor de fórmulas do Power Fx a trabalhar por si.

Saber quando utilizar variáveis

Vamos modificar a nossa calculadora simples para que funcione como uma antiga máquina de somar, com um total corrente. Se selecionares um botão Adicionar , adicionas um número ao total acumulado. Se selecionares um botão Limpar , reinicias o total acumulado para zero.

Apresentar	Descrição
	Quando a aplicação é iniciada, o total em execução é 0. O ponto vermelho representa o dedo do utilizador na caixa de entrada de texto, em que o utilizador introduz 77.
	O utilizador seleciona o botão Adicionar.
	77 é adicionado ao total em execução. O utilizador seleciona novamente o botão Adicionar.
	77 é adicionado novamente ao total em execução, resultando em 154. O utilizador seleciona o botão Limpar.
	O total em execução é reposto para 0.

A nossa máquina de somar utiliza uma coisa que não existe no Excel - botões. Nesta aplicação, não pode utilizar apenas fórmulas para calcular o total corrente, porque o valor deste depende de uma série de ações realizadas pelo utilizador. Em vez disso, deve registar e atualizar manualmente o total em circulação. A maioria das ferramentas de programação armazenam estas informações numa variável.

Em alguns casos, precisará de uma variável para que a sua aplicação se comporte da forma que pretende. Contudo, a abordagem tem alguns contras:

• Tem de atualizar o total corrente manualmente. O recálculo automático não o vai ajudar em nada.
• Não podes calcular o total em funcionamento com base nos valores de outros controlos. Depende da quantidade de vezes que o utilizador selecionou o botão Add e do valor que estava no controlo de entrada de texto de cada vez que o selecionou. Será que o utilizador introduziu 77 e selecionou Add duas vezes ou especificou 24 e 130 em cada soma? Não dá para perceber a diferença depois que o total chega a 154.
• As alterações ao total podem vir de diferentes caminhos. Neste exemplo, tanto o botão Add, como o botão Clear, pode atualizar o total. Se a aplicação não se comportar da forma que pretende, qual dos botões está a causar o problema?

Utilize uma variável global

Para criar a sua máquina de calcular, precisa de uma variável para conter o total acumulado. As variáveis mais simples com que trabalhar no Power Fx são as variáveis globais.

Como funcionam as variáveis globais:

• Use a função Set para definir o valor da variável global. Set( MyVar, 1 ) define a variável global MyVar como o valor 1.
• Use a variável global referenciando o nome que usou com a função Set . Neste caso, MyVar retorna 1.
• As variáveis globais podem conter qualquer valor, incluindo cadeias, números, registos e tabelas.

Vamos recriar a máquina de somar com uma variável global:

1. Adicione um controlo de entrada de texto, denominado TextInput1, e dois botões, Button1 e Button2.

2. Defina a propriedade Text de Button1 como "Adicionar" e defina a propriedade Text de Button2 como "Limpar".

3. Para atualizar o total corrente sempre que um utilizador seleciona o botão Adicionar, defina a respetiva propriedade OnSelect como esta fórmula:

   Set( RunningTotal, RunningTotal + TextInput1.Text )

   A simples existência desta fórmula estabelece RunningTotal como uma variável global que mantém um número devido ao operador +. Pode referenciar RunningTotal em qualquer parte da aplicação. Sempre que o utilizador abre esta aplicação, o RunningTotal tem um valor inicial de em branco.

   A primeira vez que um utilizador seleciona o botão Adicionar e as execuções Definir, RunningTotal é definido como o valor RunningTotal + TextInput1.

   

4. Para definir o total corrente como 0 sempre que o utilizador seleciona o botão Limpar, defina a respetiva propriedade OnSelect como esta fórmula:

   Set( RunningTotal, 0 )

   

5. Adicione um controlo de Etiqueta e defina a respetiva propriedade Text como RunningTotal.

   Esta fórmula recalcula automaticamente e mostra ao utilizador o valor do RunningTotal à medida que este muda, consoante os botões selecionados pelo utilizador.

   

6. Pré-visualize a aplicação e terá a sua máquina de somar como descrito anteriormente. Introduza um número na caixa de texto e prima o botão Add algumas vezes. Quando estiver pronto, volte à experiência de autoria usando a tecla Esc .

   

7. Para mostrar o valor da variável global, selecione o menu File (Ficheiro) e selecione Variables (Variáveis) no painel do lado esquerdo.

   

8. Para mostrar todos os locais onde a variável é definida e utilizada, selecione-a.

   

Tipos de variáveis

O Power Fx tem dois tipos de variáveis:

Quando usa o Power Apps, vê um terceiro tipo de variável:

Criar e remover variáveis

Crias todas as variáveis implicitamente quando aparecem numa função Set, UpdateContext, Navigate, Collect ou ClearCollect . Para declarar uma variável e seu tipo, basta incluí-la em qualquer uma dessas funções em qualquer lugar do seu aplicativo. Nenhuma destas funções cria variáveis; só preenchem variáveis com valores. Nunca declaram variáveis explicitamente como poderá fazer noutra ferramenta de programação, sendo que toda a digitação é implícita ao uso.

Por exemplo, poderá ter um controlo Botão com uma fórmula OnSelect igual a Set( X, 1 ). Esta fórmula estabelece X como variável com um tipo de número. Pode utilizar X em fórmulas como número e essa variável tem um valor em branco depois de abrir a aplicação, mas antes de selecionar o botão. Quando seleciona o botão, atribui a X o valor 1.

Se você adicionar outro botão e definir sua propriedade OnSelect como set( X, "Hello" ), ocorrerá um erro porque o tipo (cadeia de texto) não corresponde ao tipo no anterior set (número). Todas as definições implícitas da variável têm de concordar no tipo. Mais uma vez, tudo isto aconteceu porque mencionou X nas fórmulas, não porque alguma dessas fórmulas realmente funcionou.

Pode remover uma variável removendo todas as funções Set, UpdateContext, Navigate, Collectou ClearCollect que implicitamente estabelecem a variável. Sem estas funções, a variável não existe. Também deve remover quaisquer referências à variável porque causam erro.

Tempo de vida variável e valor inicial

A aplicação mantém todas as variáveis na memória enquanto corre. Quando a aplicação é fechada, os valores contidos nas variáveis perdem-se.

Pode armazenar o conteúdo de uma variável num origem de dados utilizando as funções Patch ou Collect. Também pode armazenar valores em coleções no dispositivo local utilizando a função SaveData.

Quando o utilizador abre a aplicação, todas as variáveis têm um valor inicial de em branco.

Variáveis de leitura

Use o nome da variável para ler seu valor. Por exemplo, pode definir uma variável com esta fórmula:

Set( Radius, 12 )

Depois podes simplesmente usar o Radius em qualquer lugar onde possas usar um número, e ele substitui por 12:

Pi() * Power( Radius, 2 )

Se atribuir 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, pode continuar a fazer referência à variável global ou à coleção se utilizar o operador de desambiguação[@Radius].

Utilizar uma variável de contexto (apenas Power Apps)

Aqui está como criar a máquina de somar usando uma variável de contexto em vez de uma variável global.

Como funcionam as variáveis de contexto:

• Estabelece e define implicitamente variáveis de contexto usando a função UpdateContext ou Navigate. Quando o utilizador inicia a aplicação, todas as variáveis de contexto têm um valor inicial de em branco.
• As variáveis de contexto são atualizadas com registos. Noutras ferramentas de programação, normalmente utiliza-se "=" para atribuição, como, por exemplo, "x = 1". Por sua vez, nas variáveis de contexto utiliza-se { x: 1 }. Quando utiliza uma variável de contexto, utilize o respetivo nome diretamente sem a sintaxe do registo.
• Também pode definir uma variável de contexto quando usar a função Navigate para mostrar um ecrã. Se encarar os ecrãs como um tipo de procedimento ou subrotina, isso assemelha-se à transmissão de parâmetros noutras ferramentas de programação.
• À exceção de Navigate, as variáveis de contexto estão limitadas ao contexto de um único ecrã, a partir do qual recebem o nome. Não pode utilizá-las nem defini-las fora deste contexto.
• As variáveis de contexto podem conter qualquer valor, incluindo cadeias, números, registos e tabelas.

Vamos recriar a máquina de somar com uma variável de contexto:

1. Adicione um controlo de entrada de texto, denominado TextInput1, e dois botões, Button1 e Button2.

2. Defina a propriedade Text de Button1 como "Adicionar" e defina a propriedade Text de Button2 como "Limpar".

3. Para atualizar o total corrente sempre que um utilizador seleciona o botão Adicionar, defina a respetiva propriedade OnSelect como esta fórmula:

   UpdateContext( { RunningTotal: RunningTotal + TextInput1.Text } )

   A simples existência desta fórmula estabelece RunningTotal como uma variável de contexto que mantém um número devido ao operador +. Pode referenciar RunningTotal em qualquer parte deste ecrã. Sempre que o utilizador abre esta aplicação, o RunningTotal tem um valor inicial de em branco.

   A primeira vez que o utilizador seleciona o botão Adicionar e as execuções UpdateContext, RunningTotal é definido como o valor RunningTotal + TextInput1.

   

4. Para definir o total corrente como 0 sempre que o utilizador seleciona o botão Limpar, defina a respetiva propriedade OnSelect como esta fórmula:

   UpdateContext( { RunningTotal: 0 } )

   Mais uma vez, UpdateContext é utilizado com a fórmula UpdateContext( { RunningTotal: 0 } ).

   

5. Adicione um controlo de Etiqueta e defina a respetiva propriedade Text como RunningTotal.

   Esta fórmula recalcula automaticamente e mostra ao utilizador o valor do RunningTotal à medida que este muda, consoante os botões selecionados pelo utilizador.

   

6. Pré-visualiza a aplicação e tens a tua máquina de somar como descrito anteriormente. Introduza um número na caixa de texto e prima o botão Add algumas vezes. Quando estiver pronto, volte à experiência de autoria usando a tecla Esc .

   

7. Pode definir o valor de uma variável de contexto enquanto navega para um ecrã. Esta técnica é útil para passar "contexto" ou "parâmetros" de um ecrã para outro. Para demonstrar esta técnica, introduza um ecrã, introduza um botão e, em seguida, defina a propriedade OnSelect para esta fórmula:

   Navigate( Screen1, None, { RunningTotal: -1000 } )

   

   Mantenha pressionada a tecla Alt enquanto seleciona este botão para mostrar o Ecrã1 e definir a variável de contexto RunningTotal para -1000.

   

8. Para mostrar o valor da variável contexto, selecione o menu File (Ficheiro) e depois selecione Variables (Variáveis) no painel do lado esquerdo.

   

9. Selecione a variável de contexto para ver onde está definida e utilizada.

   

Usar uma coleção

Por fim, vamos ver como criar a nossa máquina de somar com uma coleção. Como uma coleção contém uma tabela que pode facilmente modificar, esta máquina de somar mantém uma "fita de papel" de cada valor à medida que os introduz.

Como funcionam as coleções:

• Use a função ClearCollect para criar e definir coleções. Podes usar a função Collect em vez disso, mas efetivamente requer outra variável em vez de substituir a antiga.
• As coleções são uma espécie de origem de dados e, consequentemente, são tabelas. Para aceder a um valor único numa coleção, utilize a função First e extraia um campo no registo resultante. Se usar um único valor com o ClearCollect, esse valor é o campo Value , como neste exemplo:
  First(VariableName).Value

Vamos recriar a nossa máquina de somar com uma coleção:

1. Adicione um controlo de Entrada de texto, denominado TextInput1, e dois botões, Button1 e Button2.

2. Defina a propriedade Text de Button1 como "Adicionar" e defina a propriedade Text de Button2 como "Limpar".

3. Para atualizar o total corrente sempre que um utilizador seleciona o botão Adicionar, defina a respetiva propriedade OnSelect como esta fórmula:

   Collect( Fita de papel, TextInput1.Text )

   A simples existência desta fórmula estabelece PaperTape como uma coleção que mantém uma tabela de cadeias de texto de uma única coluna. Pode referenciar PaperTape em qualquer parte desta aplicação. Sempre que um utilizador abre esta aplicação, PaperTape é uma tabela vazia.

   Quando esta fórmula é executada, adiciona o valor novo ao fim da coleção. Como estás a adicionar um único valor, o Collect coloca-o automaticamente numa tabela de uma única coluna, e o nome da coluna é Valor, que usas mais tarde.

   

4. Para limpar o registo em papel quando o utilizador seleciona o botão Clear, defina a respetiva propriedade OnSelect como esta fórmula:

   Clear(PaperTape)

   

5. Para apresentar o total corrente, adicione uma etiqueta e defina a respetiva propriedade Text como esta fórmula:

   Sum( Fita de Papel, Valor )

   

6. Para executar a máquina de somar, prima F5 para abrir a Pré-visualização, introduza números no controlo de entrada de texto e selecione botões.

   

7. Para voltar ao espaço de trabalho predefinido, pressione a tecla Esc .

8. Para apresentar o registo em papel, insira um controlo de Tabela de dados e defina a respetiva propriedade Items como esta fórmula:

   PaperTape

   No painel direito, selecione Editar campos e, em seguida, selecione Adicionar campo, selecione a coluna Valor e, em seguida, selecione Adicionar para o mostrar.

   

9. Para ver os valores na sua coleção, selecione Collections, no menu Ficheiro.

   

10. Para armazenar e obter a sua coleção, adicione mais dois controlos de botão e defina as suas propriedades Texto como Load (Carregar) e Save (Guardar). Defina a propriedade OnSelect do botão Load (Carregar) como esta fórmula:

    Clear( Fita de Papel ); LoadData( PaperTape, "StoredPaperTape", verdadeiro )

    Tem de limpar a coleção primeiro, pois LoadData vai acrescentar os valores armazenados ao final da coleção.

    

11. Defina a propriedade OnSelect do botão Guardar para esta fórmula:

    SaveData (PaperTape, "StoredPaperTape")

    

12. Pré-visualize novamente pressionando a tecla F5 , insira números no controlo de entrada de texto e selecione os botões. Selecione o botão Save. Feche e atualize a aplicação e, em seguida, selecione o botão Load para atualizar a coleção.