Funções de Collect, Clear e ClearCollect no PowerAppsCollect, Clear, and ClearCollect functions in PowerApps

Cria e limpa coleções e adiciona registros a qualquer fonte de dados.Creates and clears collections and adds records to any data source.

DescriçãoDescription

CollectCollect

A função Collect adiciona registros em uma fonte de dados.The Collect function adds records to a data source. Os itens a serem adicionados podem ser:The items to be added can be:

  • Um valor único: o valor é colocado no campo Valor de um novo registro.A single value: The value is placed in the Value field of a new record. Todas as outras propriedades são deixadas em branco.All other properties are left blank.
  • Um registro: cada propriedade nomeada é colocada na propriedade correspondente de um novo registro.A record: Each named property is placed in the corresponding property of a new record. Todas as outras propriedades são deixadas em branco.All other properties are left blank.
  • Uma tabela: cada registro da tabela é adicionado como um registro separado da fonte de dados, conforme descrito acima.A table: Each record of the table is added as a separate record of the data source as described above. A tabela não é adicionada como uma tabela aninhada em um registro.The table is not added as a nested table to a record. Para fazer isso, primeiro, encapsule a tabela em um registro.To accomplish this, wrap the table in a record first.

Quando usado com uma coleção, as colunas adicionais são criadas conforme o necessário.When used with a collection, additional columns will be created as needed. As colunas para outras fontes de dados são fixas pela fonte de dados e não é possível adicionar colunas novas.The columns for other data sources are fixed by the data source and new columns cannot be added.

Se a fonte de dados ainda não existir, uma coleção será criada.If the data source doesn't already exist, a collection is created.

Às vezes, as coleções são usadas para armazenar variáveis globais ou fazer uma cópia temporária de uma fonte de dados.Collections are sometimes used to hold global variables or make a temporary copy of a data source. Os PowerApps são baseados em fórmulas que se recalculam automaticamente conforme a interação do usuário com o aplicativo.PowerApps are based on formulas that automatically recalculate as the user interacts with an app. As coleções não têm esse benefício e usá-las pode dificultar a criação e compreensão do seu aplicativo.Collections do not enjoy this benefit and their use can make your app harder to create and understand. Antes de usar uma coleção dessa maneira, revise o artigo Como trabalhar com variáveis.Before using a collection in this manner, review working with variables.

Você também pode usar a função Patch para criar registros em uma fonte de dados.You can also use the Patch function to create records in a data source.

Collect retorna a fonte de dados modificados como uma tabela.Collect returns the modified data source as a table. Collect só pode ser usado em uma fórmula de comportamento.Collect can only be used in a behavior formula.

ClearClear

A função Clear exclui todos os registros de uma coleção.The Clear function deletes all the records of a collection. As colunas da coleção serão mantidas.The columns of the collection will remain.

Observe que Clear funciona apenas em coleções e não em outras fontes de dados.Note that Clear only operates on collections and not other data sources. Você pode usar RemoveIf( DataSource, true ) para essa finalidade.You can use RemoveIf( DataSource, true ) for this purpose. Tenha cuidado, pois essa função removerá todos os registros do armazenamento da fonte de dados e pode afetar outros usuários.Use caution as this will remove all records from the data source's storage and can affect other users.

Você pode usar a função Remover para selecionar quais registros você removerá.You can use the Remove function to selectively remove records.

Clear não tem valor de retorno.Clear has no return value. Ela só pode ser usada em uma fórmula de comportamento.It can only be used in a behavior formula.

ClearCollectClearCollect

A função ClearCollect exclui todos os registros de uma coleção e, em seguida, adiciona um conjunto diferente de registros na mesma coleção.The ClearCollect function deletes all the records from a collection and then adds a different set of records to the same collection. Com uma única função, o ClearCollect oferece a combinação de Clear e Collect.With a single function, ClearCollect offers the combination of Clear and then Collect.

ClearCollect retorna a coleção modificada como uma tabela.ClearCollect returns the modified collection as a table. ClearCollect só pode ser usado em uma fórmula de comportamento.ClearCollect can only be used in a behavior formula.

SintaxeSyntax

Collect( DataSource, Item, ... )Collect( DataSource, Item, ... )

  • Fonte de dados – Obrigatório.DataSource – Required. A fonte de dados na qual deseja adicionar dados.The data source that you want to add data to. Se ela ainda não existir, uma nova coleção será criada.If it does not already exist, a new collection is created.
  • Itens - obrigatório.Item(s) - Required. Um ou mais registros ou tabelas a serem adicionados à fonte de dados.One or more records or tables to add to the data source.

Clear( Coleção )Clear( Collection )

  • Coleção – obrigatório.Collection – Required. A coleção que você deseja apagar.The collection that you want to clear.

ClearCollect( Coleção, Item.)ClearCollect( Collection, Item, ... )

  • Coleção – obrigatório.Collection – Required. A coleção que você deseja apagar e, em seguida, adicionar dados.The collection that you want to clear and then add data to.
  • Itens - obrigatório.Item(s) - Required. Um ou mais registros ou tabelas a serem adicionados à fonte de dados.One or more records or tables to add to the data source.

ExemplosExamples

Como apagar e adicionar registros a uma fonte de dadosClearing and adding records to a data source

Nesses exemplos, você apagará e adicionará a uma coleção chamada Sorvete.In these examples, you'll erase and add to a collection that's named IceCream. A fonte de dados começa com esses conteúdos:The data source begins with these contents:

FórmulaFormula DescriçãoDescription ResultadoResult
ClearCollect( Sorvete, { Sabor: "Morango", Quantidade: 300 } )ClearCollect( IceCream, { Flavor: "Strawberry", Quantity: 300 } ) Apaga todos os dados da coleçãoSorvete e, em seguida, adiciona um registro que inclui a quantidade de sorvetes de morango.Clears all data from the IceCream collection and then adds a record that includes a quantity of strawberry ice cream.

A fonte de dados Sorvete também foi modificada.The IceCream data source has also been modified.
Collect( Sorvete, { Sabor: "Pistache", Quantidade: 40 }, { Sabor: "Laranja", Quantidade: 200 } )Collect( IceCream, { Flavor: "Pistachio", Quantity: 40 }, { Flavor: "Orange", Quantity: 200 } ) Adiciona dois registros na coleção Sorvete, que inclui a quantidade de sorvetes de pistache e de laranja.Adds two records to the IceCream collection that includes a quantity of pistachio and Orange ice cream.

A fonte de dados Sorvete também foi modificada.The IceCream data source has also been modified.
Clear( Sorvete )Clear( IceCream ) Remove todos os registros da coleção Sorvete.Removes all records from the IceCream collection.

A fonte de dados Sorvete também foi modificada.The IceCream data source has also been modified.

Passo a passoStep by step

  1. Adicione um botão e defina a propriedade OnSelect para esta função:Add a button, and set its OnSelect property to this function:
    Collect(Produtos, "Europa", "Ganímedes", "Calisto")Collect(Products, "Europa", "Ganymede", "Callisto")

    Esta função cria uma coleção denominada Produtos, que contém uma linha para cada um dos três nomes de produto.This function creates a collection that's named Products that contains a row for each of three product names.

  2. Pressione F5, clique o botão e, em seguida, pressione a tecla Esc para retornar ao espaço de trabalho de design.Press F5, click the button, and then press the Esc key to return to the design workspace.
  3. (opcional) Para exibir uma visualização de coleção que você criou, clique em Coleções na guia Conteúdo.(optional) To display a preview of the collection that you created, click Collections on the Content tab.