Funções Collect, Clear e ClearCollect

Cria e limpa coleções e adiciona registos a qualquer origem de dados.

Collect

Aplica-se a: Canvas apps Cartões Dataverse low-code plug-ins Power Platform CLI Fluxos da área de trabalho

A função Collect adiciona registos a uma origem de dados. Os itens a serem adicionados podem ser:

• Um valor único: o valor é colocado no campo Valor de um novo registo. Todas as outras propriedades são deixadas blank.
• Um registo: cada propriedade nomeada é colocada na propriedade correspondente de um novo registo. Todas as outras propriedades são deixadas blank.
• Uma tabela: cada registo da tabela é adicionado como um registo separado da origem de dados, conforme descrito acima. A tabela não é adicionada como uma tabela aninhada a um registo. Para tal, encapsule primeiro a tabela num registo.

Quando utilizada com uma coleção, serão criadas colunas adicionais, conforme necessário. As colunas de outras origens de dados são corrigidas pela origem de dados e não é possível adicionar novas colunas.

Se a origem de dados ainda não existir, será criada uma coleção.

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. 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. As coleções não beneficiam desta vantagem e, se as utilizar, pode tornar a aplicação mais difícil de criar e compreender. Antes de utilizar uma coleção desta forma, consulte trabalhar com variáveis.

Também pode utilizar a função Patch para criar registos numa origem de dados.

Collect retorna o origem de dados modificado como uma tabela. Collect só pode ser usado em uma fórmula decomportamento.

Clear

Aplica-se a: Aplicativos de tela

A função Clear elimina todos os registos de uma coleção. As colunas da coleção serão mantidas.

Note que Clear apenas funciona em coleções e não noutras origens de dados. Pode utilizar RemoveIf( DataSource, true ) para essa finalidade. 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.

Pode utilizar a função Remove para remover seletivamente os registos.

Clear não tem valor de retorno. Esta função só pode ser utilizada numa fórmula de comportamento.

ClearCollect

Aplica-se a: Aplicativos de tela Aplicativos controlados por modelo

A função ClearCollect elimina todos os registos de uma coleção. E, em seguida, adiciona um conjunto de registos diferente à mesma coleção. Com uma única função, ClearCollect disponibiliza a combinação de Clear e de Collect.

ClearCollect retorna a coleção modificada como uma tabela. ClearCollect só pode ser usado em uma fórmula de comportamento.

Delegação

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.

Sintaxe

Collect( DataSource, Item, ... )

• DataSource – Obrigatório. A origem de dados à qual pretende adicionar dados. Se ainda não existir, será criada uma nova coleção.
• Itens - Obrigatório. Um ou mais registos ou tabelas a adicionar à origem de dados.

Clear( Coleção )

• Coleção – Obrigatório. A coleção que pretende limpar.

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

• Coleção – Obrigatório. A coleção que pretende limpar e, em seguida, adiciona dados.
• Itens - Obrigatório. Um ou mais registos ou tabelas a adicionar à origem de dados.

Exemplos

Limpar e adicionar registos a uma origem de dados

Nestes exemplos, vai apagar e adicionar registos a uma coleção denominada IceCream. A origem de dados começa com estes conteúdos:

Fórmula	Descrição	Resultado
ClearCollect( Sorvete, { Sabor: "Morango", Quantidade: 300 } )	Limpa todos os dados da coleção IceCream e, em seguida, adiciona um registo que inclui uma quantidade de gelado de morango.	A coleção IceCream também foi modificada.
Collect( Sorvete,Sabor { : "Pistache", Quantidade: 40 }, { Sabor: "Laranja", Quantidade: 200 } )	Adiciona dois registos à coleção IceCream, que inclui uma quantidade de gelado de pistácio e laranja.	A coleção IceCream também foi modificada.
Clear( Sorvete )	Remove todos os registos da coleção IceCream.	A coleção IceCream também foi modificada.

Para obter exemplos passo a passo sobre a criação de uma coleção, consulte Criar e atualizar uma coleção.

Registos e tabelas

Estes exemplos examinam como os argumentos de registo e tabela para Collect e ClearCollect são tratados.

Fórmula	Descrição	Resultado
ClearCollect( Sorvete,Sabor { : "Chocolate", Quantidade: 100,Sabor } { : "Baunilha", Quantidade: 200 } )	Limpa todos os dados e, em seguida, adiciona dois registos à coleção IceCream que inclui uma quantidade de gelado de chocolate e baunilha. Os registos a adicionar são fornecidos como argumentos individuais para a função.	A coleção IceCream também foi modificada.
ClearCollect( Sorvete, Mesa( { Sabor: "Chocolate", Quantidade: 100 }, { Sabor: "Baunilha", Quantidade: 200 } )	Igual ao exemplo anterior, exceto que os registos são combinados numa tabela e transmitidos através de um único argumento. O conteúdo da tabela é extraído registo por registo antes de ser adicionado à coleção IceCream.	A coleção IceCream também foi modificada.
ClearCollect( Sorvete, { ClearCollect( IceCream,MyFavorites: Table( { Sabor: "Chocolate", Quantidade: 100 }, { Sabor: "Baunilha", Quantidade: 200 } ) } )	Igual ao exemplo anterior, exceto que a tabela está envolta por um registo. 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.	A coleção IceCream também foi modificada.