Compreender as variáveis no PowerAppsUnderstand variables in PowerApps

Se já utilizou outras ferramentas de programação, como o Visual Basic ou JavaScript, poderá perguntar-se Onde estão as variáveis?If you've used another programming tool, such as Visual Basic or JavaScript, you may be asking: Where are the variables? O PowerApps é ligeiramente diferente e requer outra abordagem.PowerApps is a little different and requires a different approach. Em vez de olhar para as variáveis, pergunte-se a si próprio O que faria no Excel?Instead of reaching for a variable, ask yourself: What would I do in Excel?

Noutras ferramentas, talvez tenha feito explicitamente um cálculo e armazenado o resultado numa variável.In other tools, you may have explicitly performed a calculation and stored the result in a variable. No entanto, o PowerApps 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.However, PowerApps and Excel both automatically recalculate formulas as the input data changes, so you usually don't need to create and update variables. Ao seguir esta abordagem sempre que possível, pode criar, compreender e manter a sua aplicação mais facilmente.By taking this approach whenever possible, you can more easily create, understand, and maintain your app.

Em alguns casos, terá de utilizar variáveis no PowerApps, o que expande o modelo do Excel mediante a adição de fórmulas de comportamento.In some cases, you'll need to use variables in PowerApps, which extends Excel's model by adding behavior formulas. Estas fórmulas são executadas quando, por exemplo, um utilizador seleciona um botão.These formulas run when, for example, a user selects a button. Dentro de uma fórmula de comportamento, é muitas vezes útil definir uma variável que será utilizada noutras fórmulas.Within a behavior formula, it's often helpful to set a variable to be used in other formulas.

Em geral, evite utilizar variáveis.In general, avoid using variables. Contudo, há casos em que só as variáveis podem proporcionar a experiência que procura.But sometimes only a variable can enable the experience you want.

Traduzir o Excel no PowerAppsTranslate Excel into PowerApps

ExcelExcel

Vamos rever o funcionamento do Excel.Let's review how Excel works. As células podem conter valores, como números ou cadeias, ou fórmulas que tenham por base os valores de outras células.A cell can contain a value, such as a number or a string, or a formula that's based on the values of other cells. Após o utilizador introduzir um valor diferente numa célula, o Excel recalcula automaticamente todas as fórmulas que dependem do valor novo.After the user enters a different value into a cell, Excel automatically recalculates any formulas that depend on the new value. Não tem de fazer qualquer programação para permitir este comportamento.You don't have to do any programming to enable this behavior.

O Excel não tem variáveis.Excel doesn't have variables. 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.The value of a cell that contains a formula changes based on its input, but there's no way to remember the result of a formula and store it in a cell or anywhere else. Se alterar o valor de uma célula, toda a folha de cálculo pode ser alterada e eventuais valores calculados anteriores perdem-se.If you change a cell's value, the entire spreadsheet may change, and any previously calculated values are lost. 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.An Excel user can copy and paste cells, but that's under the user's manual control and isn't possible with formulas.

PowerAppsPowerApps

As aplicações que criar no PowerApps têm um comportamento muito semelhante ao Excel.Apps that you create in PowerApps behave very much like 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.Instead of updating cells, you can add controls wherever you want on a screen and name them for use in formulas.

Por exemplo, pode replicar o comportamento do Excel numa aplicação ao adicionar um controlo de Etiqueta, com o nome TextBox1 e dois controlos de Entrada de texto, com os nomes TextInput1 e TextInput2.For example, you can replicate the Excel behavior in an app by adding a Label control, named TextBox1, and two Text input controls, named TextInput1 and TextInput2. Se, depois, definir a propriedade Text (Texto) de TextBox1 como TextInput1 + TextInput2, mostrará sempre a soma dos números que estejam em TextInput1 e em TextInput2 automaticamente.If you then set the Text property of TextBox1 to TextInput1 + TextInput2, it will always shows the sum of whatever numbers are in TextInput1 and TextInput2 automatically.

Repare que o controlo TextBox1 está selecionado e que mostra a respetiva fórmula Text na barra de fórmulas, na parte superior do ecrã.Notice that the TextBox1 control is selected, showing its Text formula in the formula bar at the top of the screen. Aqui, encontramos a fórmula TextInput1 + TextInput2.Here we find the formula TextInput1 + TextInput2. 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.This formula creates a dependency between these controls, just as dependencies are created between cells in an Excel workbook. Vamos alterar o valor de TextInput1:Let's change the value of the TextInput1:

A fórmula para TextBox1 foi recalculada automaticamente, mostrando o valor novo.The formula for TextBox1 has been automatically recalculated, showing the new value.

No PowerApps, 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.In PowerApps, you can use formulas to determine not only the primary value of a control but also properties such as formatting. No exemplo seguinte, uma fórmula da propriedade Color (Cor) da etiqueta vai mostrar automaticamente valores negativos a vermelho.In the next example, a formula for the Color property of the label will automatically show negative values in red. A função If deve ser bastante familiar, por causa do Excel:The If function should look very familiar from Excel:
If( Value(TextBox1.Text) < 0, Red, Black )If( Value(TextBox1.Text) < 0, Red, Black )

Agora, se o resultado do nossa cálculo em TextBox1.Text for negativo, o número será mostrado a vermelho:Now, if the result of our calculation in TextBox1.Text is negative, the number will be shown in red:

Pode utilizar fórmulas para diversos cenários:You can use formulas for a wide variety of scenarios:

  • 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.By using your device's GPS, a map control can display your current location with a formula that uses Location.Latitude and Location.Longitude. À medida que se move, o mapa regista automaticamente a sua localização.As you move, the map will automatically track your location.
  • As origens de dados podem ser atualizadas por outros utilizadores.Other users can update data sources. Por exemplo, outras pessoas da sua equipa poderão atualizar itens numa lista do SharePoint.For example, others on your team might update items in a SharePoint list. Quando atualiza uma origem de dados, as fórmulas dependentes são automaticamente recalculadas para refletir os dados atualizados.When you refresh a data source, any dependent formulas are automatically recalculated to reflect the updated data. Prosseguindo o exemplo, poderá definir a propriedade Items (Itens) de uma galeria como a fórmula Filter( SharePointList ), que apresentará, de forma automática, o conjunto de registos que acabou de ser filtrado.Furthering the example, you might set a gallery's Items property to the formula Filter( SharePointList ), which will automatically display the newly filtered set of records.

BenefíciosBenefits

A utilização de fórmulas na criação de aplicações tem muitas vantagens:Using formulas to build apps has many advantages:

  • Se conhece o Excel, também conhece o PowerApps.If you know Excel, you know PowerApps. Os modelos e a linguagem das fórmulas são iguais.The model and formula language are the same.
  • Se já tiver utilizado outras ferramentas de programação, pense na quantidade de código que teria de escrever para realizar estes exemplos.If you've used other programming tools, think about how much code would be required to accomplish these examples. No Visual Basic, teria de escrever um processador de eventos para o evento de alteração em cada controlo de entrada de texto.In Visual Basic, you'd need to write an event handler for the change event on each text-input control. O código para efetuar o cálculo em cada um destes é redundante e poderia ficar dessincronizado ou, noutra hipótese, teria de escrever uma subrotina comum.The code to perform the calculation in each of these is redundant and could get out of sync, or you'd need to write a common subroutine. No PowerApps, fizemos tudo isto com uma única fórmula de uma só linha.In PowerApps, you accomplished all of that with a single, one-line formula.
  • Para saber de onde vem o texto de TextBox1, sabemos exatamente onde procurar: na fórmula na propriedade Text.To understand where TextBox1's text is coming from, you know exactly where to look: the formula in the Text property. Não existe nenhuma outra forma de afetar o texto deste controlo.There's no other way to affect the text of this control. Numa ferramenta de programação tradicional, qualquer processador de eventos ou subrotina poderia alterar o valor da etiqueta em qualquer parte do programa.In a traditional programming tool, any event handler or subroutine could change the value of the label, from anywhere in the program. Esta situação pode tornar mais difícil determinar quando e onde é que as variáveis foram alteradas.This can make it hard to track down when and where a variable was changed.
  • Se o utilizador altera um controlo de deslize e, em seguida, mudar de ideias, pode modificar o controlo para o valor original.If the user changes a slider control and then changes their mind, they can change the slider back to its original value. E é como se nada nunca tivesse mudado. A aplicação mostra os mesmos valores dos controlos que mostrava antes.And it's as if nothing had ever changed: the app shows the same control values as it did before. Não há consequências para experimentar e perguntar “e se”, tal como não as há no Excel.There are no ramifications for experimenting and asking "what if," just as there are none in Excel.

Em geral, se puder obter um efeito mediante a utilização de uma fórmula, ficará mais bem servidor.In general, if you can achieve an effect by using a formula, you'll be better off. Ponha o motor de fórmulas do PowerApps a trabalhar por si.Let the formula engine in PowerApps work for you.

Saber quando utilizar variáveisKnow when to use variables

Vamos modificar a nossa calculadora simples para que funcione como uma antiga máquina de somar, com um total corrente.Let's change our simple adder to act like an old-fashioned adding machine, with a running total. Se selecionar o botão Add (Adicionar), adicionará um número ao total corrente.If you select an Add button, you'll add a number to the running total. Se selecionar o botão Clear (Limpar), reporá o total corrente para zero.If you select a Clear button, you'll reset the running total to zero.

A nossa máquina de somar utiliza uma coisa que não existe no Excel - botões.Our adding machine uses something that doesn't exist in Excel: a button. 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.In this app, you can't use only formulas to calculate the running total because its value depends on a series of actions that the user takes. Em vez disso, o nosso total tem de ser registado e atualizado manualmente.Instead, our running total must be recorded and updated manually. A maioria das ferramentas de programação armazenam estas informações numa variável.Most programming tools store this information in a variable.

Em alguns casos, precisará de uma variável para que a sua aplicação se comporte da forma que pretende.You'll sometimes need a variable for your app to behave the way you want. Contudo, a abordagem tem alguns contras:But the approach comes with caveats:

  • Tem de atualizar o total corrente manualmente.You must manually update the running total. O recálculo automático não o vai ajudar em nada.Automatic recalculation won't do it for you.
  • O total corrente já não pode ser calculado com base nos valores dos outros controlos.The running total can no longer be calculated based on the values of other controls. 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.It depends on how many times the user selected the Add button and what value was in the text-input control each time. Será que o utilizador introduziu 77 e selecionou Add duas vezes ou especificou 24 e 130 em cada soma?Did the user enter 77 and select Add twice, or did they specify 24 and 130 for each of the additions? É impossível dizer, depois de o total ter atingido 154.You can't tell the difference after the total has reached 154.
  • As alterações ao total podem vir de diferentes caminhos.Changes to the total can come from different paths. Neste exemplo, tanto o botão Add, como o botão Clear, pode atualizar o total.In this example, both the Add and Clear buttons can update the total. Se a aplicação não se comportar da forma que pretende, qual dos botões está a causar o problema?If the app doesn't behave the way you expect, which button is causing the problem?

Criar uma variável globalCreate a global variable

Para criar a nossa máquina de somar, precisamos de uma variável que vai conter o total corrente.To create our adding machine, we require a variable to hold the running total. As variáveis mais simples com que trabalhar no PowerApps são as variáveis globais.The simplest variables to work with in PowerApps are global variables.

Como funcionam as variáveis globais:How global variables work:

  • É definido o valor da variável global com a função Set (Definir).You set the value of the global variable with the Set function. Set( MyVar, 1 ) define a variável global MyVar como o valor 1.Set( MyVar, 1 ) sets the global variable MyVar to a value of 1.
  • Para utilizar a variável global, é feita referência ao nome utilizado com a função Set.You use the global variable by referencing the name used with the Set function. Neste caso, MyVar vai devolver 1.In this case, MyVar will return 1.
  • As variáveis globais podem conter qualquer valor, incluindo cadeias, números, registos e tabelas.Global variables can hold any value, including strings, numbers, records, and tables.

Vamos recriar a máquina de somar com uma variável global:Let's rebuild our adding machine by using a global variable:

  1. Adicione um controlo de entrada de texto, denominado TextInput1, e dois botões, Button1 e Button2.Add a text-input control, named TextInput1, and two buttons, named Button1 and Button2.
  2. Defina a propriedade Text de Button1 como "Add" e defina a propriedade Text de Button2 como "Clear".Set the Text property of Button1 to "Add", and set the Text property of Button2 to "Clear".
  3. Para atualizar o total corrente sempre que um utilizador seleciona o botão Adiciona, defina a respetiva propriedade OnSelect como esta fórmula:To update the running total whenever a user selects the Add button, set its OnSelect property to this formula:

    Set( RunningTotal, RunningTotal + Text1 )Set( RunningTotal, RunningTotal + Text1 )

    Da primeira vez que um utilizador selecionador o botão Add e for invocado Set, é criado RunningTotal com o valor predefinido blank (branco).The first time a user selects the Add button and Set is called, RunningTotal is created with a default value of blank. Na soma, será tratado como um zero.In the addition, it will be treated as a zero.

  4. Para definir o total corrente como 0 sempre que o utilizador seleciona o botão Clear, defina a respetiva propriedade OnSelect como esta fórmula:To set the running total to 0 whenever the user selects the Clear button, set its OnSelect property to this formula:

    Set( RunningTotal, 0 )Set( RunningTotal, 0 )

  5. Adicione um controlo de Etiqueta e defina a respetiva propriedade Text como RunningTotal.Add a Label control, and set its Text property to RunningTotal.

    Esta fórmula é recalculada automaticamente e mostra ao utilizador o valor de RunningTotal, à medida que é alterado com base nos botões que ele seleciona.This formula will automatically be recalculated and show the user the value of RunningTotal as it changes based on the buttons that the user selects.

  6. Pré-visualizamos a aplicação e temos uma máquina de somar igual à descrita acima.Preview the app, and we have our adding machine as described above. Introduza um número na caixa de texto e prima o botão Add algumas vezes.Enter a number in the text box and press the Add button a few times. Quando estiver pronto, regresse à experiência de criação com a tecla Esc.When ready, return to the authoring experience using the Esc key.

  7. Para ver o valor da variável global, selecione o menu File e selecione Variables (Variáveis) no painel do lado esquerdo.To see our global variable's value, select the File menu and select Variables in the left hand pane.

  8. Para ver todos os locais onde a variável é definida e utilizada, selecione-a.To see all the places where our variable is defined and used, select it.

Tipos de variáveisTypes of variables

Existem três tipos de variáveis no PowerApps:There are three types of variables in PowerApps:

Tipo de variávelVariables type ÂmbitoScope DescriçãoDescription FunçõesFunctions
Variáveis globaisGlobal variables AplicaçãoApp Mais simples de utilizar.Simplest to use. Contém um número, texto, cadeia, booleano, registo, tabela, etc., que pode ser uma referência de qualquer parte da aplicação.Holds a number, text string, Boolean, record, table, etc. that can be references from anywhere in the app. SetSet
Variáveis de contextoContext variables EcrãScreen Ideais para transmitir valores para ecrãs, de forma semelhante aos parâmetros transmitidos para procedimentos noutras linguagens.Great for passing values to a screen, much like parameters to a procedure in other languages. Só podem ser referenciadas a partir de um ecrã.Can only be referenced from one screen. UpdateContextUpdateContext
NavigateNavigate
ColeçõesCollections AplicaçãoApp Contêm uma tabela que pode ser uma referência de qualquer parte da aplicação.Holds a table that can be references from anywhere in the app. Permitem que os conteúdos de uma tabela sejam modificados em vez de serem definidos como um todo.Allows the contents of the table to be modified rather than being set as a whole. Podem ser guardadas no dispositivo local para utilização posterior.Can be saved to the local device for later use. CollectCollect
ClearCollectClearCollect
PatchPatch
UpdateUpdate
RemoveRemove
SaveDataSaveData
LoadDataLoadData
etc.etc.

Quando utilizadas nas funções Set, UpdateContext, Navigate ou Collect, todas as variáveis são criadas implicitamente.All variables are created implicitly when used in Set, UpdateContext, Navigate, or Collect functions. Ao contrário do que acontece noutras ferramentas de programação, não há uma declaração explícita das variáveis.There is no explicit declaration of variables as is done in other programming tools. Os tipos das variáveis também derivam implicitamente dos valores que são introduzidos nas mesmas.The types of the variables are also derived implicitly from the values that are placed in them.

Todas as variáveis são guardadas na memória enquanto a aplicação está em execução.All variables are held in memory while the app is running. Quando a aplicação é fechada, os valores contidos as variáveis perdem-se.After the app closes, the values held in the variables are lost. Pode armazenar os conteúdos de uma variável numa Origem de Dados com as funções Patch ou Collect ou, caso se tratem de coleções, pode armazenar no dispositivo local com a função SaveData.You can store the contents of a variable in a Data Source using Patch or Collect functions, or in the case of collections you can store to the local device with the SaveData function. Da primeira vez que a aplicação é carregada, todas as variáveis terão o valor blank.When the app is first loaded, all variables will have the blank value.

Para ler os valores das variáveis, utilize os nomes das mesmas.You use the variables name to read its value. Por exemplo, se for definida com Set( MyColor, Red ), pode simplesmente utilizar MyVar em qualquer parte onde pode ser utilizado um valor de cor e a mesma será substituída por Red.For example, once defined with Set( MyColor, Red ) you can simply use MyVar anywhere a color value can be used and it will be replaced with the Red. É possível ter uma variável global ou uma coleção com o mesmo nome de uma variável de contexto.It is possible to have a global variable or collection with the same name as a context variable. Neste caso, a variável de contexto terá precedência.In this case, the context variable will take precedence. Continua a poder fazer referência à variável global ou à coleção com o operador de desambiguação @[MyColor].You can still reference the global variable or collection using the disambiguation operator @[MyColor].

Criar uma variável de contextoCreate a context variable

Vamos ver de que forma podemos criar a nossa máquina de somar com uma variável de contexto em vez de uma global.Let's look at how our adding machine would be created using a context variable instead of a global variable.

Como funcionam as variáveis de contexto:How context variables work:

  • As variáveis de contexto são criadas e definidas com a função UpdateContext.You create and set context variables by using the UpdateContext function. Se ainda não existir uma variável de contexto quando for atualizada pela primeira vez, será criada com o valor predefinido blank.If a context variable doesn't already exist when first updated, it will be created with a default value of blank.
  • As variáveis de contexto são criadas e atualizadas com registos.You create and update context variables with records. Noutras ferramentas de programação, normalmente utiliza-se "=" para atribuição, como, por exemplo, "x = 1".In other programming tools, you commonly use "=" for assignment, as in "x = 1". Por sua vez, nas variáveis de contexto utiliza-se { x: 1 }.For context variables, use { x: 1 } instead. Quando utilizar uma variável de contexto, utilize o nome da mesma diretamente.When you use a context variable, use its name directly.
  • Também pode definir uma variável de contexto quando for apresentado um ecrã através da função Navigate.You can also set a context variable when a screen is displayed, by using the Navigate function. Se encarar os ecrãs como um tipo de procedimento ou subrotina, isto é semelhante à transmissão de parâmetros noutras ferramentas de programação.If you think of a screen as a kind of procedure or subroutine, this is similar to parameter passing in other programming tools.
  • À 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.Except for Navigate, context variables are limited to the context of a single screen, which is where they get their name. Não pode utilizá-las nem defini-las fora deste contexto.You can't use or set them outside of this context.
  • As variáveis de contexto podem conter qualquer valor, incluindo cadeias, números, registos e tabelas.Context variables can hold any value, including strings, numbers, records, and tables.

Vamos recriar a máquina de somar com uma variável de contexto:Let's rebuild our adding machine by using a context variable:

  1. Adicione um controlo de entrada de texto, denominado TextInput1, e dois botões, Button1 e Button2.Add a text-input control, named TextInput1, and two buttons, named Button1 and Button2.
  2. Defina a propriedade Text de Button1 como "Add" e defina a propriedade Text de Button2 como "Clear".Set the Text property of Button1 to "Add", and set the Text property of Button2 to "Clear".
  3. Para atualizar o total corrente sempre que um utilizador seleciona o botão Adiciona, defina a respetiva propriedade OnSelect como esta fórmula:To update the running total whenever a user selects the Add button, set its OnSelect property to this formula:

    UpdateContext( { RunningTotal: RunningTotal + Text1 } )UpdateContext( { RunningTotal: RunningTotal + Text1 } )

    Da primeira vez que um utilizador selecionador o botão Add e for invocado UpdateContext, é criado RunningTotal com o valor predefinido blank (branco).The first time a user selects the Add button and UpdateContext is called, RunningTotal is created with a default value of blank. Na soma, será tratado como um zero.In the addition, it will be treated as a zero.

  4. Para definir o total corrente como 0 sempre que o utilizador seleciona o botão Clear, defina a respetiva propriedade OnSelect como esta fórmula:To set the running total to 0 whenever the user selects the Clear button, set its OnSelect property to this formula:

    UpdateContext( { RunningTotal: 0 } )UpdateContext( { RunningTotal: 0 } )

    Mais uma vez, UpdateContext é utilizado com a fórmula UpdateContext( { RunningTotal: 0 } ).Again, UpdateContext is used with the formula UpdateContext( { RunningTotal: 0 } ).

  5. Adicione um controlo de Etiqueta e defina a respetiva propriedade Text como RunningTotal.Add a Label control, and set its Text property to RunningTotal.

    Esta fórmula é recalculada automaticamente e mostra ao utilizador o valor de RunningTotal, à medida que é alterado com base nos botões que ele seleciona.This formula will automatically be recalculated and show the user the value of RunningTotal as it changes based on the buttons that the user selects.

  6. Pré-visualizamos a aplicação e temos uma máquina de somar igual à descrita acima.Preview the app and we have our adding machine as described above. Introduza um número na caixa de texto e prima o botão Add algumas vezes.Enter a number in the text box and press the Add button a few timnes. Quando estiver pronto, regresse à experiência de criação com a tecla Esc.When ready, return to the authoring experience using the Esc key.

  7. Pode definir o valor de uma variável de contexto enquanto navega para um ecrã.You can set the value of a context variable while navigating to a screen. Isto é útil para transmitir "contexto" ou "parâmetros" de um ecrã para outro.This is useful for passing "context" or "parameters" from one screen to another. Para ver um exemplo, insira um ecrã novo e insira um botão com a propriedade OnSelect definida como:To see this, insert a new screen, and insert a button with the OnSelect property set to:

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

    Selecionar este botão em Screen2 (que pode fazer no momento da criação, se selecionar o botão junto à parte inferior) mostra Screen1 e define também a variável de contexto RunningTotal como -1000.Selecting this button on Screen2 (which you can do while authoring if you select the button toward the ends) will show Screen1 and also set the context variable RunningTotal to -1000.

  8. Para ver o valor da variável de contexto, selecione o menu File e selecione Variables no painel do lado esquerdo.To see our context variable's value, select the File menu and select Variables in the left hand pane.

  9. Para ver onde a variável de contexto é definida e utilizada, selecione-a.To see where your context variable is defined and used, select it.

Criar uma coleçãoCreate a collection

Por fim, vamos ver como criar a nossa máquina de somar com uma coleção.Finally, let's look at creating our adding machine with a collection. Uma vez que as coleções contêm tabelas que são facilmente modificáveis, vamos fazer com que esta máquina guarde um “registo em papel” de todos os valores, à medida que são introduzidos.Since a collection holds a table that is easy to modify, we will make this adding machine keep a "paper tape" of each value as they are entered.

Como funcionam as coleções:How collections work:

  • Utilize a função ClearCollect para criar e definir as coleções.Create and set collections by using the ClearCollect function. Pode utilizar a função Collect em alternativa, mas esta requer, efetivamente, outra variável em vez de substituir a antiga.You can use the Collect function instead, but it will effectively require another variable instead of replacing the old one.
  • As coleções são uma espécie de origem de dados e, consequentemente, são tabelas.A collection is a kind of data source and, therefore, a table. Para aceder a um valor único numa coleção, utilize a função First e extraia um campo no registo resultante.To access a single value in a collection, use the First function, and extract one field from the resulting record. Se tiver utilizado um valor único com ClearCollect, este será o campo Value, como neste exemplo:If you used a single value with ClearCollect, this will be the Value field, as in this example:
    First( VariableName ).ValueFirst( VariableName ).Value

Vamos recriar a nossa máquina de somar com uma coleção:Let's recreate our adding machine by using a collection:

  1. Adicione um controlo de Entrada de texto, denominado TextInput1, e dois botões, Button1 e Button2.Add a Text input control, named TextInput1, and two buttons, named Button1 and Button2.
  2. Defina a propriedade Text de Button1 como "Add" e defina a propriedade Text de Button2 como "Clear".Set the Text property of Button1 to "Add", and set the Text property of Button2 to "Clear".
  3. Para atualizar o total corrente sempre que um utilizador seleciona o botão Adiciona, defina a respetiva propriedade OnSelect como esta fórmula:To update the running total whenever a user selects the Add button, set its OnSelect property to this formula:

    Collect( PaperTape, TextInput1.Text )Collect( PaperTape, TextInput1.Text )

    Esta fórmula adiciona o valor novo ao fim da coleção.This formula will add the new value to the end of the collection. Uma vez que estamos a adicionar um valor único, Collect coloca-o automaticamente numa tabela de coluna única, com o nome de coluna Value, que vamos utilizar mais tarde.Since we are adding a single value, Collect will automatically place it in a single column table with the column name Value which we will use later.

  4. Para limpar o registo em papel quando o utilizador seleciona o botão Clear, defina a respetiva propriedade OnSelect como esta fórmula:To clear our paper tape when the user selects the Clear button, set its OnSelect property to this formula:

    Clear( PaperTape )Clear( PaperTape )

  5. Para apresentar o total corrente, adicione uma etiqueta e defina a respetiva propriedade Text como esta fórmula:To display the running total, add a label, and set its Text property to this formula:

    Sum( PaperTape, Value )Sum( PaperTape, Value )

  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.To run the adding machine, press F5 to open Preview, enter numbers in the text-input control, and select buttons.

  7. Para voltar à área de trabalho predefinida, prima a tecla Esc.To return to the default workspace, press the Esc key.
  8. Para apresentar o registo em papel, insira um controlo de Tabela de dados e defina a respetiva propriedade Items como esta fórmula:To display the paper tape, insert a Data table control, and set its Items property to this formula:

    PaperTapePaperTape

    Também tem de selecionar as colunas que vão aparecer no painel do lado direito, neste caso, a coluna Value.You will also need to select the columns to show in the right hand pane, in our case show the Value column:

  9. Para ver os valores na sua coleção, selecione Collections, no menu Ficheiro.To see the values in your collection, select Collections on the File menu.

  10. Para armazenar e obter a sua coleção, adicione mais dois controlos de botão e defina os respetivos textos como Load (Carregar) e Save (Guardar).To store and retrieve your collection, add two additional button controls and set their text to Load and Save. Para Load, defina a propriedade OnSelect como:For Load, set the OnSelect property to:

    Clear( PaperTape ); LoadData( PaperTape, "StoredPaperTape", true )Clear( PaperTape ); LoadData( PaperTape, "StoredPaperTape", true )

    Primeiro, temos de limpar a coleção, pois LoadData vai acrescentar os valores armazenados ao final da coleção.We need to clear the collection first as LoadData will append the stored values to the end of the collection.

  11. Para Save, defina a propriedade OnSelect como:For Save, set the OnSelect property to:

    SaveData( PaperTape, "StoredPaperTape" )SaveData( PaperTape, "StoredPaperTape" )

  12. Prima a tecla F5 para pré-visualizar outra vez, introduza números no controlo de entrada de texto e selecione botões.Preview again by pressing the F5 key, enter numbers in the text-input control, and select buttons. Selecione o botão Save.Select the Save button. Feche e atualize a aplicação e, em seguida, selecione o botão Load para atualizar a coleção.Close and reload your app, and select the Load button to reload your collection.

    Nota: SaveData e LoadData não funcionam quando em execução num browser; tem de utilizar o Studio instalado no Windows ou um dos leitores para dispositivos móveis.Note: SaveData and LoadData do not function when running in a web browser, you must be using the studio installed on Windows or one of the players for mobile device.