Funções Collect, Clear e ClearCollect no Power AppsCollect, Clear, and ClearCollect functions in Power Apps

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

DescriçãoDescription

CollectCollect

A função Collect adiciona registos a uma origem 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 registo.A single value: The value is placed in the Value field of a new record. Todas as outras propriedades são deixadas blank.All other properties are left blank.
  • Um registo: cada propriedade nomeada é colocada na propriedade correspondente de um novo registo.A record: Each named property is placed in the corresponding property of a new record. Todas as outras propriedades são deixadas blank.All other properties are left blank.
  • Uma tabela: cada registo da tabela é adicionado como um registo separado da origem 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 a um registo.The table isn't added as a nested table to a record. Para tal, molde primeiro a tabela num registo.To do this, wrap the table in a record first.

Quando utilizada com uma coleção, serão criadas colunas adicionais, conforme necessário.When used with a collection, additional columns will be created as needed. As colunas de outras origens de dados são corrigidas pela origem de dados e não é possível adicionar novas colunas.The columns for other data sources are fixed by the data source and new columns can't be added.

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

Por vezes, as coleções são utilizadas para conter variáveis globais ou efetuar uma cópia temporária de uma origem de dados.Collections are sometimes used to hold global variables or make a temporary copy of a data source. As aplicações de tela são baseadas em fórmulas que são recalculadas automaticamente à medida que o utilizador interage com uma aplicação.Canvas apps are based on formulas that automatically recalculate as the user interacts with an app. As coleções não beneficiam desta vantagem e, se as utilizar, pode tornar a aplicação mais difícil de criar e compreender.Collections don't enjoy this benefit and their use can make your app harder to create and understand. Antes de utilizar uma coleção desta forma, consulte trabalhar com variáveis.Before using a collection in this manner, review working with variables.

Também pode utilizar a função Patch para criar registos numa origem de dados.You can also use the Patch function to create records in a data source.

Collect devolve a origem de dados modificada como uma tabela.Collect returns the modified data source as a table. Só pode utilizar a função Collect numa fórmula de comportamento.Collect can only be used in a behavior formula.

ClearClear

A função Clear elimina todos os registos 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.

Note que Clear apenas funciona em coleções e não noutras origens de dados.Note that Clear only operates on collections and not other data sources. Pode utilizar RemoveIf( DataSource, true ) para essa finalidade.You can use RemoveIf( DataSource, true ) for this purpose. Deverá ter muito cuidado ao utilizar esta função, uma vez que removerá todos os registos do armazenamento da origem de dados e poderá afetar os outros utilizadores.Use caution as this will remove all records from the data source's storage and can affect other users.

Pode utilizar a função Remove para remover seletivamente os registos.You can use the Remove function to selectively remove records.

Clear não devolve nenhum valor.Clear has no return value. Esta função só pode ser utilizada numa fórmula de comportamento.It can only be used in a behavior formula.

ClearCollectClearCollect

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

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

DelegaçãoDelegation

Quando utiliza com uma origem de dados, estas funções não podem ser delegadas. Só será obtida a primeira parte da origem de dados e, em seguida, a função aplicada. O resultado pode não representar o cenário completo. Poderá aparecer um aviso à hora de criação para lembrá-lo desta limitação e para sugerir que mude para alternativas delegáveis sempre que possível. Para mais informações, consulte a descrição geral de delegação.

SintaxeSyntax

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

  • DataSource – Obrigatório.DataSource – Required. A origem de dados à qual pretende adicionar dados.The data source that you want to add data to. Se ainda não existir, será criada uma nova coleção.If it doesn't already exist, a new collection is created.
  • Item(ns) – Obrigatório.Item(s) - Required. Um ou mais registos ou tabelas a adicionar à origem de dados.One or more records or tables to add to the data source.

Clear( Collection )Clear( Collection )

  • Collection – Obrigatório.Collection – Required. A coleção que pretende limpar.The collection that you want to clear.

ClearCollect( Collection, Item, ... )ClearCollect( Collection, Item, ... )

  • Collection – Obrigatório.Collection – Required. A coleção que pretende limpar e, em seguida, adiciona dados.The collection that you want to clear and then add data to.
  • Item(ns) – Obrigatório.Item(s) - Required. Um ou mais registos ou tabelas a adicionar à origem de dados.One or more records or tables to add to the data source.

ExemplosExamples

Limpar e adicionar registos a uma origem de dadosClearing and adding records to a data source

Nestes exemplos, vai apagar e adicionar registos a uma coleção denominada Gelado.In these examples, you'll erase and add to a collection that's named IceCream. A origem de dados começa com estes conteúdos:The data source begins with these contents:

Origem de dados de exemplo

FórmulaFormula DescriçãoDescription ResultadoResult
ClearCollect( IceCream, { Sabor: "Morango", Quantidade: 300 } )ClearCollect( IceCream, { Flavor: "Strawberry", Quantity: 300 } ) Limpa todos os dados da coleção Gelado e, em seguida, adiciona um registo que inclui uma quantidade de gelado de morango.Clears all data from the IceCream collection and then adds a record that includes a quantity of strawberry ice cream. Tabela com um registo Table with one record

A coleção Gelado também foi modificada.The IceCream collection has also been modified.
Collect( IceCream, { Sabor: "Pistácio", Quantidade: 40 }, { Sabor: "Laranja", Quantidade: 200 } )Collect( IceCream, { Flavor: "Pistachio", Quantity: 40 }, { Flavor: "Orange", Quantity: 200 } ) Adiciona dois registos à coleção Gelado, que inclui uma quantidade de gelado de pistácio e laranja.Adds two records to the IceCream collection that includes a quantity of pistachio and orange ice cream. Tabela com dois registosTable with two records

A coleção Gelado também foi modificada.The IceCream collection has also been modified.
Clear( IceCream )Clear( IceCream ) Remove todos os registos da coleção Gelado.Removes all records from the IceCream collection. Tabela vaziaEmpty table

A coleção Gelado também foi modificada.The IceCream collection has also been modified.

Para obter exemplos passo a passo sobre a criação de uma coleção, consulte Criar e atualizar uma coleção.For step-by-step examples of how to create a collection, see Create and update a collection.

Registos e tabelasRecords and tables

Estes exemplos examinam como os argumentos de registo e tabela para Collect e ClearCollect são tratados.These examples examine how record and table arguments to Collect and ClearCollect are handled.

FórmulaFormula DescriçãoDescription ResultadoResult
ClearCollect( IceCream, { Sabor: "Chocolate", Quantidade: 100 }, { Sabor: "Baunilha", Quantidade: 200 } )ClearCollect( IceCream, { Flavor: "Chocolate", Quantity: 100 }, { Flavor: "Vanilla", Quantity: 200 } ) Limpa todos os dados e, em seguida, adiciona dois registos à coleção Gelado que inclui uma quantidade de gelado de chocolate e baunilha.Clear all data and then adds two records to the IceCream collection that includes a quantity of chocolate and vanilla ice cream. Os registos a adicionar são fornecidos como argumentos individuais para a função.The records to be added are provided as individual arguments to the function. Os registos de Chocolate e Baunilha são adicionados à coleçãoChocolate and Vanilla records added to collection

A coleção Gelado também foi modificada.The IceCream collection has also been modified.
ClearCollect( IceCream, Table( { Sabor: "Chocolate", Quantidade: 100 }, { Sabor: "Baunilha", Quantidade: 200 } ) )ClearCollect( IceCream, Table( { Flavor: "Chocolate", Quantity: 100 }, { Flavor: "Vanilla", Quantity: 200 } ) ) Igual ao exemplo anterior, exceto que os registos são combinados numa tabela e transmitidos através de um único argumento.Same as the previous example except that the records are combined in a table and passed in through a single argument. O conteúdo da tabela é extraído registo por registo antes de ser adicionado à coleção Gelado.The contents of the table are extracted record by record before being added to the IceCream collection. Os registos de Chocolate e Baunilha são adicionados à coleçãoChocolate and Vanilla records added to collection

A coleção Gelado também foi modificada.The IceCream collection has also been modified.
ClearCollect( IceCream,
{ MyFavorites: Table( { Sabor: "Chocolate", Quantidade: 100 }, { Sabor: "Baunilha", Quantidade: 200 } ) } )
ClearCollect( IceCream,
{ MyFavorites: Table( { Flavor: "Chocolate", Quantity: 100 }, { Flavor: "Vanilla", Quantity: 200 } ) } )
Igual ao exemplo anterior, exceto que a tabela está envolta por um registo.Same as the previous example except that the table is wrapped in a record. Os registos da tabela não são extraídos e, ao invés disso, a tabela inteira é adicionada como uma célula do registo.The records of the table aren't extracted and instead the entire table is added as a cell of the record. Os registos de Chocolate e Baunilha são adicionados à coleçãoChocolate and Vanilla records added to collection

A coleção Gelado também foi modificada.The IceCream collection has also been modified.