Collect、Clear 和 ClearCollect 函式

發行項
10/16/2024

Collect

適用於： 畫布應用卡片 Dataverse 低程式碼外掛程式 Power Platform CLI 桌面流

Collect 函數將記錄新增至資料來源。預計新增的項目會是︰

單一值︰值會放在新記錄的 Value 欄位。所有其他屬性會保留空白。
記錄︰每個具名屬性會放在新記錄的對應屬性中。所有其他屬性會保留空白。
Table︰資料表的每筆記錄會新增為資料來源的個別記錄 (如上所述)。資料表不以巢狀資料表新增至記錄。若要這麼做，請先將資料表裝合入記錄中。

當搭配集合物件使用時，將視需要建立其他欄位。資料來源會固定其他資料來源的欄位，且不會新增新欄位。

如果資料來源尚未存在，會建立集合物件。

集合物件有時候會用來保存全域變數或製作資料來源的暫存副本。畫布應用程式是建立在使用者與應用程式互動時自動重新計算的公式基礎上。集合物件不會享有這項好處，且其使用會讓您的應用程式更難建立和理解。以這種方式使用集合物件之前，請檢閱搭配變數使用。

您也可以使用 Patch 函數在資料來源中建立記錄。

Collect 以表的形式返回修改後的資料來源。 Collect 只能在行為公式中使用。

Clear

適用於： 畫布應用

Clear 函數刪除集合物件的所有記錄。集合物件的欄位將會保留。

請注意，Clear 只在集合物件上運作，不會在其他資料來源上運作。您可以為此目的使用 RemoveIf( DataSource, true )。請謹慎小心，因為這將會從資料來源的儲存體移除所有記錄，並影響其他使用者。

您可以使用 Remove 函數選擇性地移除記錄。

Clear 沒有返回值。它只能用於行為公式。

ClearCollect

適用於： 畫布應用模型驅動應用

ClearCollect 函數刪除集合物件的所有記錄。然後將不同的記錄集新增至相同的集合物件。使用單一函數，ClearCollect 提供 Clear 和 Collect 的組合。

ClearCollect 以表的形式返回修改後的集合。 ClearCollect 只能在行為公式中使用。

委派

搭配資料來源使用時，無法委派這些函數。將僅擷取資料來源的第一個部分，然後再套用函式。結果不一定代表完整的全貌。製作期間可能會出現警告，提醒您有此限制並建議盡可能切換至可委派的替代函式。如需詳細資訊，請參閱委派概觀。

語法

Collect（ DataSource，Item ，...）

DataSource –必需。您想要新增資料的資料來源。如果它尚未存在，會建立新集合物件。
Items - 必需。預計新增至資料來源的一個或多個記錄或資料表。

Clear（集合）

collection –必需。您想要清除的集合物件。

ClearCollect（集合，專案...）

collection –必需。您想要清除然後新增資料的集合物件。
Items - 必需。預計新增至資料來源的一個或多個記錄或資料表。

範例

將記錄清除並新增至資料來源

在這些範例中，您將會抹除並新增至名為 IceCream 的集合物件。資料來源以這些內容開始︰

範例資料來源。

公式	描述	結果
ClearCollect（霜淇淋， { 口味：草莓味，數量：300 } ）	從 IceCream 集合物件清除所有資料，然後新增包括草莓冰淇淋數量的記錄。	IceCream 集合物件也已修改。
收集（霜淇淋， { 口味：開心果，數量：40 }， { 口味：柳丁，數量：200 } ）	將兩筆記錄新增至包括開心果及橘色冰淇淋數量的 IceCream 集合物件。	IceCream 集合物件也已修改。
Clear（IceCream）	從 IceCream 集合物件移除所有記錄。	IceCream 集合物件也已修改。

如需了解如何建立集合物件的逐步範例，請參閱建立和更新集合物件。

記錄和資料表

這些範例檢查 Collect 和 ClearCollect 記錄和資料表引數的處理方式。

公式	描述	結果
ClearCollect（霜淇淋， { 口味：“巧克力”，數量：100 }， { 口味：“香草”，數量：200 } ）	清除所有貟料然後新增兩筆記錄至包括草莓冰淇淋數量的 IceCream 集合物件。預計新增的記錄會以函數的個別引數形式提供。	IceCream 集合物件也已修改。
ClearCollect (IceCream，Table（ { 口味：“巧克力”，數量：100 }， { 口味：“香草”，數量：200 } )）	與先前範例相同，不同之處在於記錄會在一個資料表中結合並透過單一引數傳遞。新增至 IceCream 集合物件之前，該資料表的內容會按記錄提取。	IceCream 集合物件也已修改。
ClearCollect（霜淇淋， { MyFavorites: Table( { Flavor: "Chocolate", Quantity: 100 }, { Flavor: "Vanilla", Quantity: 200 } ) } )	與先前的範例相同，不同之處在於資料表是裝入記錄中。不會提取資料表的記錄，而是將整個資料表改新增為記錄的一個儲存格。	IceCream 集合物件也已修改。

共用方式為