PowerApps 中的 Patch 函数Patch function in PowerApps

数据源中修改或创建一条或多条记录,或者合并数据源外的记录。Modifies or creates one or more records in a data source, or merges records outside of a data source.

使用 Patch 函数可以在复杂情况(如执行不需要用户交互的更新或使用跨多个屏幕的窗体)下修改记录。Use the Patch function to modify records in complex situations, such as when you perform updates that require no user interaction or use forms that span multiple screens.

在不太复杂的情况下,可以使用编辑窗体控件,更轻松地更新数据源中的记录。In less complex situations, you can use the Edit form control to update records in a data source more easily. 添加编辑窗体控件时,可以向用户提供要填写的窗体,然后将更改保存到数据源中。When you add an Edit form control, you provide users with a form to fill in and then save the changes to a data source. 有关详细信息,请参阅了解数据窗体For more information, see Understand data forms.

概述Overview

使用 Patch 函数可修改数据源的一条或多条记录。Use the Patch function to modify one or more records of a data source. 可以在不影响其他属性的情况下修改特定字段的值。The values of specific fields are modified without affecting other properties. 例如,以下公式更改名为 Contoso 的客户的电话号码:For example, this formula changes the phone number for a customer named Contoso:

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

结合使用 PatchDefaults 函数可创建记录。Use Patch with the Defaults function to create records. 可以利用此行为生成一个屏幕,以供创建和编辑记录。Use this behavior to build a single screen for both creating and editing records. 例如,以下公式为名为 Contoso 的客户创建记录:For example, this formula creates a record for a customer named Contoso:

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

即使不需要使用数据源,也可以使用 Patch 来合并两条或多条记录。Even if you're not working with a data source, you can use Patch to merge two or more records. 例如,以下公式将两个记录合并成一个同时识别 Contoso 的电话号码和位置的记录:For example, this formula merges two records into one that identifies both the phone number and the location for Contoso:

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

说明Description

在数据源中修改或创建记录Modify or create a record in a data source

要在数据源中使用这个函数,请指定数据源,然后指定一条基本记录:To use this function with a data source, specify the data source, and then specify a base record:

  • 要修改记录,基本记录必须来自数据源。To modify a record, the base record needs to have come from a data source. 基本记录可能来自一个库的属性(在上下文变量中),也可能来自其他途径。The base record may have come through a gallery's Items property, been placed in a context variable, or come through some other path. 不管怎样,最终必须能够追溯到基本记录来自数据源。But you should be able to trace the base record back to the data source. 这一点非常重要,因为记录中包含一些额外的信息,可以帮助你重新找到记录,以便进行修改。This is important as the record will include additional information to help find the record again for modification.
  • 要创建记录,请使用 Defaults 函数创建一条包含默认值的基本记录。To create a record, use the Defaults function to create a base record with default values.

然后指定一条或多条更改记录,每条记录都包含用于替代基本记录中属性值的新属性值。Then specify one or more change records, each of which contains new property values that override property values in the base record. 更改记录按照参数列表从头到尾的顺序进行处理,并且使用后者的属性值替换前者的属性值。Change records are processed in order from the beginning of the argument list to the end, with later property values overriding earlier ones.

Patch 的返回值是要修改或创建的记录。The return value of Patch is the record that you modified or created. 如果是创建记录,返回值可能包含数据源自动生成的属性。If you created a record, the return value may include properties that the data source generated automatically.

更新数据源时,可能会产生一个或多个问题。When you update a data source, one or more issues may arise. 使用 Errors 函数可识别和检查问题,如使用数据源所述。Use the Errors function to identify and examine issues, as Working with Data Sources describes.

相关函数包括 Update 函数,它可用于替换整条记录;另外还有 Collect 函数,它可用于创建记录。Related functions include the Update function, which you can use to replace an entire record, and the Collect function, which you can use to create a record. 通过使用 UpdateIf 函数,你可以根据条件来修改多条记录的特定属性。You can use the UpdateIf function to modify specific properties of multiple records based on a condition.

在数据源中修改或创建一组记录Modify or create a set of records in a data source

Patch 还可用于通过一次调用创建或修改多条记录。Patch can also be used to create or modify multiple records with a single call.

它不是传递单条基本记录,而是在第二个参数中提供一个基本记录表。Instead of passing a single base record, a table of base records can be provided in the second argument. 更改记录也是通过表提供,并且与基本记录一一对应。Change records are provided in a table as well, corresponding one-for-one with the base records. 每个更改表中记录的数量必须与基本表中记录的数量完全相等。The number of records in each change table must be the same as the number of records in the base table.

如果以这种方式使用 Patch 函数,结果值也会是一个表,并且其中的记录与基本记录和更改记录也是一一对应的。When using Patch in this manner, the return value is also a table with each record corresponding one-for-one with the base and change records.

合并数据源外部的记录Merge records outside of a data source

指定一条或多条要合并的记录。Specify two or more records that you want to merge. 记录按照参数列表从头到尾的顺序进行处理,并且使用后者的属性值替换前者的属性值。Records are processed in order from the beginning of the argument list to the end, with later property values overriding earlier ones.

Patch 会返回合并的记录,并且不会修改它的参数或任何数据源中的记录。Patch returns the merged record and doesn't modify its arguments or records in any data sources.

语法Syntax

在数据源中修改或创建记录Modify or create a record in a data source

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

  • DataSource – 必需。DataSource – Required. 包含要修改的记录或用于包含要创建的记录的数据源。The data source that contains the record that you want to modify or will contain the record that you want to create.
  • BaseRecord – 必需。BaseRecord – Required. 要修改或创建的记录。The record to modify or create. 如果记录来自数据源,则会找到记录并进行修改。If the record came from a data source, the record is found and modified. 如果使用 Defaults 函数的结果,则会创建记录。If the result of Defaults is used, a record is created.
  • ChangeRecord(s) – 必需。ChangeRecord(s) – Required. 一条或多条记录,其中包含要在 BaseRecord 中修改的属性。One or more records that contain properties to modify in the BaseRecord. 更改记录按照参数列表从头到尾的顺序进行处理,并且使用后者的属性值替换前者的属性值。Change records are processed in order from the beginning of the argument list to the end, with later property values overriding earlier ones.

在数据源中修改或创建一组记录Modify or create a set of records in a data source

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

  • DataSource – 必需。DataSource – Required. 包含要修改的记录或用于包含要创建的记录的数据源。The data source that contains the records that you want to modify or will contain the records that you want to create.
  • BaseRecordTable – 必需。BaseRecordTable – Required. 要修改或创建的记录的表。A table of records to modify or create. 如果记录来自数据源,则会找到记录并进行修改。If the record came from a data source, the record is found and modified. 如果使用 Defaults 函数的结果,则会创建记录。If the result of Defaults is used, a record is created.
  • ChangeRecordTable(s) – 必需。ChangeRecordTable(s) – Required. 记录的一个或多个表,其中包含在 BaseRecordTable 中要修改的每条记录的属性。One or more tables of records that contain properties to modify for each record of the BaseRecordTable. 更改记录按照参数列表从头到尾的顺序进行处理,并且使用后者的属性值替换前者的属性值。Change records are processed in order from the beginning of the argument list to the end, with later property values overriding earlier ones.

合并记录Merge records

Patch( Record1, Record2 [, …] )Patch( Record1, Record2 [, …] )

  • Record - 必需。Record(s) - Required. 至少要有两条要合并的记录。At least two records that you want to merge. 记录按照参数列表从头到尾的顺序进行处理,并且使用后者的属性值替换前者的属性值。Records are processed in order from the beginning of the argument list to the end, with later property values overriding earlier ones.

示例Examples

在数据源中修改或创建记录Modify or create a record (in a data source)

在以下示例中,你会在名为 IceCream 的数据源中修改或创建一条记录。该数据源包含这个中的数据,并且会在 ID 中自动生成相应的值:In these examples, you'll modify or create a record in a data source, named IceCream, that contains the data in this table and automatically generates the values in the ID column:

公式Formula 说明Description 结果Result
Patch( IceCream,
First( Filter( IceCream, Flavor = "Chocolate" ) ), { Quantity: 400 } )
Patch( IceCream,
First( Filter( IceCream, Flavor = "Chocolate" ) ), { Quantity: 400 } )
修改 IceCream 数据源中的记录:Modifies a record in the IceCream data source:
  • 要修改的记录的 ID 列的值为 1The ID column of the record to modify contains the value of 1. (这个 ID 的记录为 Chocolate。)(The Chocolate record has that ID.)
  • Quantity 列的值更改为 400The value in the Quantity column changes to 400.
{ ID: 1, Flavor: "Chocolate", Quantity: 400 }{ ID: 1, Flavor: "Chocolate", Quantity: 400 }

已修改 IceCream 数据源中的 Chocolate 条目。The Chocolate entry in the IceCream data source has been modified.
Patch( IceCream, Defaults( IceCream ), { Flavor: “Strawberry” } )Patch( IceCream, Defaults( IceCream ), { Flavor: “Strawberry” } ) IceCream 数据源中创建一条记录。Creates a record in the IceCream data source:
  • ID 列包含的值为 3,这是数据源自动生成的。The ID column contains the value 3, which the data source generates automatically.
  • Quantity 列的值为 0,在 IceCream 数据源中,这是该列的默认值,由 Defaults 函数指定。The Quantity column contains 0, which is the default value for that column in the IceCream data source, as the Defaults function specifies.
  • Flavor 列的值为 StrawberryThe Flavor column contains the value of Strawberry.
{ ID: 3, Flavor: “Strawberry”, Quantity: 0 }{ ID: 3, Flavor: “Strawberry”, Quantity: 0 }

已在 IceCream 数据源中创建 Strawberry 条目。The Strawberry entry in the IceCream data source has been created.

对上面的公式进行计算后,数据源最终会产生以下值:After the previous formulas have been evaluated, the data source ends with these values:

合并数据源外的记录Merge records (outside of a data source)

公式Formula 说明Description 结果Result
Patch( { Name: "James", Score: 90 }, { Name: "Jim", Passed: true } )Patch( { Name: "James", Score: 90 }, { Name: "Jim", Passed: true } ) 合并数据源外的两条记录:Merges two records outside of a data source:
  • 两条记录的 Name 列中的值不相同。The values in the Name column of each record don't match. 结果包含离参数列表的末尾更近的记录中的值 (Jim),而不是离开头更近的记录中的值 (James)。The result contains the value (Jim) in the record that's closer to the end of the argument list instead of the value (James) in the record that's closer to the start.
  • 第一条记录包含第二条记录中不存在的一列 (Score)。The first record contains a column (Score) that doesn't exist in the second record. 结果包含这一列及其值 (90)。The result contains that column with its value (90).
  • 第二条记录包含第一条记录中不存在的一列 (Passed)。The second record contains a column (Passed) that doesn't exist in the first record. 结果包含这一列及其值 (true)。The result contains that column with its value (true).
{ Name: "Jim", Score: 90, Passed: true }{ Name: "Jim", Score: 90, Passed: true }