Collect, Clear, e ClearCollect funções

Função	Aplica-se a
Clear	Aplicativos de tela Fluxos de área de trabalho Funções do Dataverse da CLI da Power Platform
ClearCollect	Aplicativos de tela Fluxos de área de trabalho CLI da Power Platform
Collect	Aplicativos de tela Fluxos de área de trabalho Aplicativos orientados por modelos Funções do Power Platform CLI Dataverse

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

Collect

A Collect função adiciona registros a uma fonte 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 a fonte de dados modificada como uma tabela. Collect só pode ser usado em uma fórmula de comportamento.

Clear

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

Note-se que Clear opera apenas em coleções e não em outras fontes 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

A ClearCollect função exclui todos os registros de uma coleção. E, em seguida, adiciona um conjunto de registos diferente à mesma coleção. Com uma única função, ClearCollect oferece a combinação de Clear e depois 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( Gelado )	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 registro e tabela para Collect e ClearCollect são tratados.

Fórmula	Descrição	Resultado
ClearCollect( Sorvete, { Sabor: "Chocolate", Quantidade: 100 }, { Sabor: "Baunilha", Quantidade: 200 } )	Clear todos os dados e, em seguida, adiciona dois registros à coleção IceCream que inclui uma quantidade de sorvete 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.