Функции Collect, Clear и ClearCollect

Создание и удаление коллекций и добавление записей в любом источнике данных.

Collect

Применимо к: приложениям на основе холста карточкам Dataverse малокодовым подключаемым модулям интерфейс командной строки Power Platform

Функция Collect добавляет записи в источник данных. Возможно добавление следующих элементов:

• Одно значение: значение помещается в поле Value новой записи. Поля всех остальных свойств остаются пустыми.
• Запись: каждое именованное свойство помещается в соответствующее свойство новой записи. Поля всех остальных свойств остаются пустыми.
• Таблица: каждая запись таблицы добавляется в виде отдельной записи в источнике данных, как описано выше. Таблица не добавляется в запись в виде вложенной таблицы. Для выполнения этой задачи сначала заключите таблицу в запись.

При использовании вместе с коллекцией будут созданы дополнительные столбцы, если это необходимо. Столбцы для других источников данных зафиксированы источником данных, и новые столбцы добавить нельзя.

Если источник данных еще не существует, создается коллекция.

Коллекции иногда используются для хранения глобальных переменных или создания временной копии источника данных. Приложения на основе холста основываются на формулах, которые автоматически вычисляются при взаимодействии пользователя с приложением. Для коллекций эта возможность недоступна, а их использование может усложнить как процесс создания, так и структуру самого приложения. Прежде чем использовать коллекцию таким образом, просмотрите раздел о работе с переменными.

Можно также использовать функцию Patch для создания записей в источнике данных.

Функция Collect возвращает измененный источник данных в виде таблицы. Функция Collect может использоваться только в формуле поведения.

Clear

Применимо к: приложениям на основе холста

Функция Clear удаляет все записи из коллекции. Столбцы в коллекции остаются.

Обратите внимание, что функция Clear работает только с коллекциями и не работает с источниками данных другого типа. Для этой цели можно использовать формулу RemoveIf( DataSource, true ). Будьте осторожны, так как это приведет к удалению всех записей из хранилища источника данных и может повлиять на других пользователей.

Можно использовать функцию Remove для выборочного удаления записей.

Функция Clear не возвращает никакого значения. Ее можно использовать только в формуле поведения.

ClearCollect

Применимо к: приложениям на основе холста приложениям на основе модели

Функция ClearCollect удаляет все записи из коллекции. А затем добавляет другой набор записей в ту же коллекцию. Функция ClearCollect сочетает в себе возможности функций Clear и затем Collect.

Функция ClearCollect возвращает измененную коллекцию в виде таблицы. Функцию ClearCollect можно использовать только в формуле поведения.

Делегирование

При использовании с источником данных эти функции невозможно делегировать. Будет извлечена только первая часть источника данных, затем будет применена функция. Результат может не отражать ситуацию в целом. Во время разработки может отобразиться предупреждение, чтобы напомнить об этом ограничении и предложить по возможности переключиться на подлежащие делегированию альтернативы. Дополнительные сведения см. в обзоре делегирования.

Синтаксис

Collect( DataSource, Item, ... )

• DataSource — обязательный аргумент. Это источник данных, в который необходимо добавить данные. Если он еще не существует, создается новая коллекция.
• Item(s) — обязательный аргумент. Одна или несколько записей или таблиц, которые необходимо добавить в источник данных.

Clear( Collection )

• Collection — обязательный аргумент. Коллекция, которую необходимо очистить.

ClearCollect( Collection, Item, ... )

• Collection — обязательный аргумент. Коллекция, которую необходимо очистить, а затем добавить в нее данные.
• Item(s) — обязательный аргумент. Одна или несколько записей или таблиц, которые необходимо добавить в источник данных.

Примеры

Удаление и добавление записей в источнике данных

В этих примерах показано удаление и добавление данных в коллекции под названием IceCream. В источнике данных содержится следующее:

Формула	Описание	Результат
ClearCollect( IceCream, { Flavor: "Strawberry", Quantity: 300 } )	Выполняется удаление всех данных из коллекции IceCream и добавляется запись, в которой указано количестве клубничного мороженого.	Коллекция IceCream также была изменена.
Collect( IceCream, { Flavor: "Pistachio", Quantity: 40 }, { Flavor: "Orange", Quantity: 200 } )	Выполняется добавление двух записей в коллекцию IceCream, в которой указано количество фисташкового и апельсинового мороженого.	Коллекция IceCream также была изменена.
Clear( IceCream )	Выполняется удаление всех записей из коллекции IceCream.	Коллекция IceCream также была изменена.

Пошаговые примеры создания коллекции см. в разделе Создание и обновление коллекции.

Записи и таблицы

Эти примеры показывают, как обрабатываются аргументы записи и таблицы для Collect и ClearCollect.

Формула	Описание	Результат
ClearCollect( IceCream, { Flavor: "Chocolate", Quantity: 100 }, { Flavor: "Vanilla", Quantity: 200 } )	Удаление всех данных из коллекции IceCream, затем добавление в нее двух записей, в которой указано количестве шоколадного и ванильного мороженого. Добавляемые записи предоставляются в качестве отдельных аргументов функции.	Коллекция IceCream также была изменена.
ClearCollect( IceCream, Table( { Flavor: "Chocolate", Quantity: 100 }, { Flavor: "Vanilla", Quantity: 200 } ) )	То же, что и в предыдущем примере, за исключением того, что записи объединяются в таблицу и передаются через один аргумент. Содержимое таблицы извлекается запись за записью перед добавлением в коллекцию IceCream.	Коллекция IceCream также была изменена.
ClearCollect( IceCream, { MyFavorites: Table( { Flavor: "Chocolate", Quantity: 100 }, { Flavor: "Vanilla", Quantity: 200 } ) } )	То же, что и в предыдущем примере, за исключением того, что таблица упакована в запись. Записи таблицы не извлекаются, а вместо этого вся таблица добавляется как ячейка записи.	Коллекция IceCream также была изменена.