Funções Collect, Clear e ClearCollect

Cria e limpa coleções e adiciona registros a qualquer fonte de dados.

Collect

Aplica-se a: Aplicativos Canvas Cartões Dataverse low-code plug-ins Power Platform CLI Fluxos de desktop

A função Collect adiciona registros em uma fonte de dados. Os itens a serem adicionados podem ser:

• Um valor único: o valor é colocado no campo Value de um novo registro. Todas as outras propriedades são deixadas em branco.
• Um registro: cada propriedade nomeada é colocada na propriedade correspondente de um novo registro. Todas as outras propriedades são deixadas em branco.
• Uma tabela: cada registro da tabela é adicionado como um registro separado da fonte de dados, conforme descrito acima. A tabela não é adicionada como uma tabela aninhada em um registro. Para fazer isso, primeiro, encapsule a tabela em um registro.

Quando usado com uma coleção, as colunas adicionais são criadas conforme o necessário. As colunas para outras fontes de dados são fixas pela fonte de dados e não é possível adicionar colunas novas.

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

À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. Os aplicativos de tela são baseados em fórmulas que se recalculam automaticamente conforme a interação do usuário com o aplicativo. As coleções não têm esse benefício e usá-las pode dificultar a criação e compreensão do seu aplicativo. Antes de usar uma coleção dessa maneira, revise como trabalhar com variáveis.

Você também pode usar a função Patch para criar registros em uma fonte de dados.

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

Clear

Aplica-se a: aplicativos Canvas

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

Observe que Clear funciona apenas em coleções e não em outras fontes de dados. Você pode usar RemoveIf( DataSource, true ) para essa finalidade. Tenha cuidado, pois essa função removerá todos os registros do armazenamento da fonte de dados e poderá afetar outros usuários.

Você pode usar a função Remove para selecionar quais registros removerá.

Clear não tem valor de retorno. Ela só pode ser usada em uma fórmula de comportamento.

ClearCollect

Aplica-se a: Aplicativos Canvas Aplicativos baseados em modelos

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

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

Delegação

Quando usadas com uma fonte de dados, estas funções não poderão ser delegadas. Somente a primeira parte da fonte de dados será recuperada e então a função será aplicada. O resultado pode não representar a história completa. Um aviso pode ser exibido no momento da criação para lembrá-lo dessa limitação e para sugerir a troca para alternativas delegáveis sempre que possível. Para obter mais informações, consulte visão geral de delegação.

Sintaxe

Coletar( Fonte de dados, Item, ... )

• DataSource – Obrigatório. A fonte de dados à qual deseja adicionar dados. Se ela ainda não existir, uma nova coleção será criada.
• Itens - Obrigatório. Um ou mais registros ou tabelas a serem adicionados à fonte de dados.

Limpar( Coleção )

• Coleção – Obrigatório. A coleção que você deseja apagar.

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

• Coleção – Obrigatório. A coleção que você deseja apagar e à qual deseja adicionar dados em seguida.
• Itens - Obrigatório. Um ou mais registros ou tabelas a serem adicionados à fonte de dados.

Exemplos

Como apagar e adicionar registros a uma fonte de dados

Nestes exemplos, você apagará e adicionará a uma coleção chamada IceCream. A fonte de dados começa com estes conteúdos:

Fórmula	Descrição	Resultado
ClearCollect( IceCream, { Sabor: "Morango", Quantidade: 300 } )	Apaga todos os dados da coleção IceCream e, em seguida, adiciona um registro que inclui a quantidade de sorvetes de morango.	A coleção IceCream também foi modificada.
Coletar( Sorvete, { Sabor: "Pistache", Quantidade: 40 }, { Sabor: "Laranja", Quantidade: 200 } )	Adiciona dois registros à coleção IceCream, que inclui a quantidade de sorvetes de pistache e de laranja.	A coleção IceCream também foi modificada.
Claro (Sorvete)	Remove todos os registros da coleção IceCream.	A coleção IceCream também foi modificada.

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

Registros e tabelas

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

Fórmula	Descrição	Resultado
ClearCollect( IceCream, { Sabor: "Chocolate", Quantidade: 100 }, { Sabor: "Baunilha", Quantidade: 200 } )	Limpa todos os dados e então adiciona dois registros à coleção IceCream, que inclui uma quantidade de sorvetes de chocolate e baunilha. Os registros a serem adicionados são fornecidos como argumentos individuais para a função.	A coleção IceCream também foi modificada.
ClearCollect( IceCream, Table( { Sabor: "Chocolate", Quantidade: 100 }, { Sabor: "Baunilha", Quantidade: 200 } ) )	Igual ao exemplo anterior, exceto que os registros são combinados em uma tabela e transmitidos por meio de um único argumento. O conteúdo da tabela é extraído registro por registro antes de ser adicionado à coleção IceCream.	A coleção IceCream também foi modificada.
ClearCollect(Sorvete, { MyFavorites: Table( { Flavor: "Chocolate", Quantity: 100 }, { Flavor: "Vanilla", Quantity: 200 } ) } )	Igual ao exemplo anterior, exceto que a tabela está encapsulada em um registro. Os registros da tabela não são extraídos e, em vez disso, a tabela inteira é adicionada como uma célula do registro.	A coleção IceCream também foi modificada.