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

Используйте функцию Patch, чтобы изменять записи в сложных ситуациях, например при автоматическом выполнении обновлений или при использовании форм, охватывающих несколько экранов.

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

Обзор

Используйте функцию Patch, чтобы изменить одну или несколько записей источника данных. Значения определенных полей изменяются, не затрагивая другие свойства. Например, следующая формула изменяет номер телефона клиента с именем Contoso:

Patch( Customers, First( Filter( Customers, Name = "Contoso" ) ), { Phone: “1-212-555-1234” } )

Используйте функцию Patch с функцией Defaults для создания записей. Используйте это поведение, чтобы настроить единый экран для создания и изменения записей. Например, следующая формула создает запись для клиента с именем Contoso:

Patch( Customers, Defaults( Customer ), { Name: “Contoso” } )

Даже если вы не работаете с источником данных, вы можете использовать функцию Patch, чтобы объединить две записи или более. Например, следующая формула объединяет две записи в одну, которая определяет и номер телефона, и расположение Contoso:

Patch( { Name: "Contoso", Phone: “1-212-555-1234” }, { Name: "Contoso", Location: “Midtown” } )

Описание

Изменение или создание записи в источнике данных

Чтобы использовать эту функцию с источником данных, укажите источник данных, а затем укажите базовую запись.

  • Чтобы изменить запись, базовая запись должна быть частью источника данных. Базовая запись может быть задана через свойство Items коллекции, размещаться в переменной контекста или быть доступна другим образом. Однако у вас должна быть возможность отследить обратный путь базовой записи к источнику данных. Это важно, так как запись будет содержать дополнительные сведения, на основе которых ее можно повторно найти для изменения.

  • Чтобы создать запись, используйте функцию Defaults. С помощью этой функции вы создадите базовую запись со значениями по умолчанию.

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

Возвращаемое значение функции Patch — это запись, которую вы изменили или создали. Если вы создали запись, возвращаемое значение может содержать свойства, созданные источником данных автоматически.

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

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

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

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

Во втором аргументе можно указать целую таблицу базовых записей, вместо того чтобы передавать отдельную базовую запись. В таблице также содержатся записи с изменениями, соответствующие каждой базовой записи. Число записей в каждой таблице с изменениями должно соответствовать числу записей в базовой таблице.

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

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

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

Функция Patch возвращает объединенную запись и не изменяет ее аргументы или записи в каком-либо источнике данных.

Синтаксис

Изменение или создание записи в источнике данных

Patch( DataSource, BaseRecord, ChangeRecord1 [, ChangeRecord2, … ])

  • *DataSource* — обязательный аргумент. Это источник данных, содержащий запись, которую необходимо изменить. Или же тот, который будет содержать запись, которую вы хотите создать.

  • *BaseRecord* — обязательный аргумент. Это запись, которую необходимо изменить или создать. Если запись является частью источника данных, она будет найдена и изменена. Если используется результат функции Defaults, тогда запись создается.

  • ChangeRecord(s)* — обязательный аргумент. Одна или несколько записей, содержащих свойства для изменения в *BaseRecord. Изменения записей обрабатываются от начала и до конца списка аргументов. При этом последние значения свойства переопределяют ранее созданные.

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

Patch( DataSource, BaseRecordsTable, ChageRecordTable1, [, ChangeRecordTable2, … ] )

  • *DataSource* — обязательный аргумент. Это источник данных, содержащий запись, которую необходимо изменить. Или же тот, который будет содержать запись, которую вы хотите создать.

  • *BaseRecordTable* — обязательный аргумент. Таблица записей, которые нужно изменить или создать. Если запись является частью источника данных, она будет найдена и изменена. Если используется результат функции Defaults, тогда запись создается.

  • ChangeRecordTable(s)* — обязательный аргумент. Одна или несколько таблиц записей, содержащих свойства, которые необходимо изменить, для каждой записи в *BaseRecordTable. Изменения записей обрабатываются от начала и до конца списка аргументов. При этом последние значения свойства переопределяют ранее созданные.

Объединение записей

Patch( Record1, Record2 [, …] )

  • *Record(s)* — обязательный аргумент. Необходимо указать как минимум несколько записей для объединения. Записи обрабатываются от начала и до конца списка аргументов. При этом последние значения свойства переопределяют ранее созданные.

Примеры

Изменение или создание записи (в источнике данных)

Из примеров ниже вы узнаете, как изменить или создать запись в источнике данных с именем IceCream. Этот источник содержит данные из таблицы, а также автоматически созданные значения, представленные в столбце ID.

Формула Описание Возвращаемый результат
Patch( IceCream,
First( Filter( IceCream, Flavor = "Chocolate" ) ), { Quantity: 400 } )		 Изменяет запись в источнике данных IceCream.
  • Столбец записи ID, которую необходимо изменить, содержит значение 1. (Это значение задано для записи Chocolate.)
  • Значение в столбце Quantity изменится на 400.
 { ID: 1, Flavor: "Chocolate", Quantity: 400 }

Запись Chocolate в источнике данных IceCream была изменена.
Patch( IceCream, Defaults( IceCream ), { Flavor: “Strawberry” } ) Функция создает запись в источнике данных IceCream.
  • Столбец ID содержит значение 3, которое источник данных создает автоматически.
  • Столбец Quantity содержит значение 0, которое является значением по умолчанию для этого столбца в источнике данных IceCream в соответствии с функцией Defaults.
  • Столбец Flavor содержит значение Strawberry.
 { ID: 3, Flavor: “Strawberry”, Quantity: 0 }

В источнике данных IceCream была создана запись Strawberry.

После вычисления формул выше источник данных получил следующие значения:

Объединение записей (вне источника данных)

Формула Описание Возвращаемый результат
Patch( { Name: "James", Score: 90 }, { Name: "Jim", Passed: true } ) Функция объединяет две записи вне источника данных.
  • Значения в столбце Name для каждой записи не совпадают. Результат содержит значение (Jim) в записи в конце списка аргументов вместо значения (James) в начале этого списка.
  • Первая запись содержит столбец (Score), который отсутствует во второй записи. Результат содержит этот столбец со значением (90).
  • Вторая запись содержит столбец (Passed), который отсутствует в первой записи. Результат содержит этот столбец со значением (true).
 { Name: "Jim", Score: 90, Passed: true }