Funções Collect, Clear e ClearCollect no Power Apps

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

Descrição

Collect

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, molde 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 devolve a origem de dados modificada como uma tabela. Só pode utilizar a função Collect numa fórmula de comportamento.

Clear

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 devolve nenhum valor. Esta função só pode ser utilizada numa fórmula de comportamento.

ClearCollect

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 devolve a coleção modificada como uma tabela. ClearCollect só pode ser utilizada numa 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.
  • Item(ns) – Obrigatório. Um ou mais registos ou tabelas a adicionar à origem de dados.

Clear( Collection )

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

ClearCollect( Collection, Item, ... )

  • Collection – Obrigatório. A coleção que pretende limpar e, em seguida, adiciona dados.
  • Item(ns) – 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 Gelado. A origem de dados começa com estes conteúdos:

Origem de dados de exemplo

Fórmula Descrição Resultado
ClearCollect( IceCream, { Sabor: "Morango", Quantidade: 300 } ) Limpa todos os dados da coleção Gelado e, em seguida, adiciona um registo que inclui uma quantidade de gelado de morango. Tabela com um registo

A coleção Gelado também foi modificada.
Collect( IceCream, { Sabor: "Pistácio", Quantidade: 40 }, { Sabor: "Laranja", Quantidade: 200 } ) Adiciona dois registos à coleção Gelado, que inclui uma quantidade de gelado de pistácio e laranja. Tabela com dois registos

A coleção Gelado também foi modificada.
Clear( IceCream ) Remove todos os registos da coleção Gelado. Tabela vazia

A coleção Gelado 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( IceCream, { Sabor: "Chocolate", Quantidade: 100 }, { Sabor: "Baunilha", Quantidade: 200 } ) Limpa todos os dados e, em seguida, adiciona dois registos à coleção Gelado que inclui uma quantidade de gelado de chocolate e baunilha. Os registos a adicionar são fornecidos como argumentos individuais para a função. Os registos de Chocolate e Baunilha são adicionados à coleção

A coleção Gelado também foi modificada.
ClearCollect( IceCream, Table( { 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 Gelado. Os registos de Chocolate e Baunilha são adicionados à coleção

A coleção Gelado também foi modificada.
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. Os registos de Chocolate e Baunilha são adicionados à coleção

A coleção Gelado também foi modificada.

Nota

Pode indicar-nos as suas preferências no que se refere ao idioma da documentação? Responda a um breve inquérito. (tenha em atenção que o inquérito está em inglês)

O inquérito irá demorar cerca de sete minutos. Não são recolhidos dados pessoais (declaração de privacidade).