PowerApps 中的 Collect、Clear 和 ClearCollect 函数Collect, Clear, and ClearCollect functions in PowerApps

创建和清除集合,以及将记录添加到任意数据源Creates and clears collections and adds records to any data source.

说明Description

CollectCollect

Collect 函数将记录添加到数据源。The Collect function adds records to a data source. 可添加的项包括:The items to be added can be:

  • 单个值:该值置于新记录的 Value 字段中。A single value: The value is placed in the Value field of a new record. 所有其他属性保留为空白All other properties are left blank.
  • 记录:每个命名属性都置于新记录的对应属性中。A record: Each named property is placed in the corresponding property of a new record. 所有其他属性保留为空白。All other properties are left blank.
  • :如上所述,表中的每条记录将作为数据源的单个记录添加。A table: Each record of the table is added as a separate record of the data source as described above. 表不是以嵌套表形式添加到记录。The table is not added as a nested table to a record. 为实现此目的,需首先将表包装在记录中。To accomplish this, wrap the table in a record first.

当用于集合时,将根据需要创建额外的When used with a collection, additional columns will be created as needed. 该数据源将固定其他数据源的列,且无法添加新列。The columns for other data sources are fixed by the data source and new columns cannot be added.

如果数据源尚不存在,则会创建一个集合。If the data source doesn't already exist, a collection is created.

集合有时可用于保留全局变量或作为数据源的临时副本。Collections are sometimes used to hold global variables or make a temporary copy of a data source. PowerApps 以公式为基础,这些公式会在用户与应用交互时自动重新计算。PowerApps are based on formulas that automatically recalculate as the user interacts with an app. 集合不具有此优势,并且使用这些集合可能会让应用更加难以进行创建和理解。Collections do not enjoy this benefit and their use can make your app harder to create and understand. 以此方式使用集合前,请查看使用变量Before using a collection in this manner, review working with variables.

还可使用 Patch 函数在数据源中创建记录。You can also use the Patch function to create records in a data source.

Collect 以表格形式返回修改后的数据源。Collect returns the modified data source as a table. Collect 只能在行为公式中使用。Collect can only be used in a behavior formula.

ClearClear

Clear 函数删除集合的所有记录。The Clear function deletes all the records of a collection. 集合的列将保留。The columns of the collection will remain.

请注意,Clear 仅对集合执行运算,而不包括其他数据源。Note that Clear only operates on collections and not other data sources. 鉴于此,可以使用 RemoveIf( DataSource, true )You can use RemoveIf( DataSource, true ) for this purpose. 此函数将删除数据源存储中的所有记录并影响其他用户,请谨慎使用。Use caution as this will remove all records from the data source's storage and can affect other users.

可使用 Remove 函数选择性地删除记录。You can use the Remove function to selectively remove records.

Clear 没有返回值。Clear has no return value. 只能在行为公式中使用。It can only be used in a behavior formula.

ClearCollectClearCollect

ClearCollect 函数删除集合中的所有记录,并向同一集合添加一组不同的记录。The ClearCollect function deletes all the records from a collection and then adds a different set of records to the same collection. ClearCollect 这单个函数可提供 ClearCollect 的组合功能。With a single function, ClearCollect offers the combination of Clear and then Collect.

ClearCollect 以表格形式返回修改后的集合。ClearCollect returns the modified collection as a table. ClearCollect 只能在行为公式中使用。ClearCollect can only be used in a behavior formula.

语法Syntax

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

  • DataSource – 必需。DataSource – Required. 要向其添加数据的数据源。The data source that you want to add data to. 如果尚不存在,将创建一个新的集合。If it does not already exist, a new collection is created.
  • Item(s) - 必需。Item(s) - Required. 要添加到数据源的一个或多个记录或表。One or more records or tables to add to the data source.

Clear( Collection )Clear( Collection )

  • Collection - 必需。Collection – Required. 要清除的集合。The collection that you want to clear.

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

  • Collection - 必需。Collection – Required. 要清除然后向其添加数据的集合。The collection that you want to clear and then add data to.
  • Item(s) - 必需。Item(s) - Required. 要添加到数据源的一个或多个记录或表。One or more records or tables to add to the data source.

示例Examples

清除并将记录添加到数据源Clearing and adding records to a data source

在以下示例中,将擦除名为 IceCream 的集合并向其进行添加。In these examples, you'll erase and add to a collection that's named IceCream. 数据源以下列内容开始:The data source begins with these contents:

公式Formula 说明Description 结果Result
ClearCollect( IceCream, { Flavor: "Strawberry", Quantity: 300 } )ClearCollect( IceCream, { Flavor: "Strawberry", Quantity: 300 } ) 清除 IceCream 集合中的所有数据,然后添加包含草莓冰淇淋数量的记录。Clears all data from the IceCream collection and then adds a record that includes a quantity of strawberry ice cream.

IceCream 数据源也已得到修改。The IceCream data source has also been modified.
Collect( IceCream, { Flavor: "Pistachio", Quantity: 40 }, { Flavor: "Orange", Quantity: 200 } )Collect( IceCream, { Flavor: "Pistachio", Quantity: 40 }, { Flavor: "Orange", Quantity: 200 } ) IceCream 集合添加两条记录,其中包括开心果味冰淇淋和橙子味冰淇淋的数量。Adds two records to the IceCream collection that includes a quantity of pistachio and Orange ice cream.

IceCream 数据源也已得到修改。The IceCream data source has also been modified.
Clear( IceCream )Clear( IceCream ) 删除 IceCream 集合中的所有记录。Removes all records from the IceCream collection.

IceCream 数据源也已得到修改。The IceCream data source has also been modified.

分步操作Step by step

  1. 添加一个按钮,并将其 OnSelect 属性设置为以下函数:Add a button, and set its OnSelect property to this function:
    Collect(Products, "Europa", "Ganymede", "Callisto")Collect(Products, "Europa", "Ganymede", "Callisto")

    此函数创建名为 Products 的集合,其中包含对应每一个(共三个)产品名的行。This function creates a collection that's named Products that contains a row for each of three product names.

  2. 按 F5,单击按钮,然后按 Esc 键返回设计工作区。Press F5, click the button, and then press the Esc key to return to the design workspace.
  3. (可选)若要显示所创建集合的预览,请单击“内容”选项卡上的“集合”。(optional) To display a preview of the collection that you created, click Collections on the Content tab.