PowerApps 中的 EditForm、NewForm、SubmitForm、ResetForm 和 ViewForm 函数EditForm, NewForm, SubmitForm, ResetForm, and ViewForm functions in PowerApps

查看、编辑或创建一个项,保存内容,以及在编辑表单控件中重置控件。View, edit, or create an item, save the contents, and reset the controls in an Edit form control.

概述Overview

这些函数将更改“编辑表单”控件的状态。These functions change the state of the Edit form control. 表单控件可以采用以下模式之一:The form control can be in one of these modes:

模式Mode 说明Description
FormMode.EditFormMode.Edit 表单使用现有记录填充,用户可以修改字段的值。The form is populated with an existing record and the user can modify the values of the fields. 完成后,用户可以将更改保存到记录中。Once complete, the user can save the changes to the record.
FormMode.NewFormMode.New 表单使用默认值填充,用户可以修改字段的值。The form is populates with default values and the user can modify the values of the fields. 完成后,用户可以将记录添加到数据源。Once complete, the user can add the record to the data source.
FormMode.ViewFormMode.View 表单使用现有记录填充,但用户无法修改字段的值。The form is populated with an existing record but the user cannot modify the values of the fields.

说明Description

这些函数通常从按钮图像控件的 OnSelect 公式中调用,以便用户可以保存编辑、放弃编辑或创建记录。These functions are often invoked from the OnSelect formula of a Button or Image control so that the user can save edits, abandon edits, or create a record. 可通过将控件和这些函数结合使用来创建完整的解决方案。You can use controls and these functions together to create a complete solution.

这些函数不返回任何值。These functions return no values.

SubmitFormSubmitForm

在按钮控件的 OnSelect 属性中使用 SubmitForm 函数可将窗体控件中的任何更改保存到数据源。Use the SubmitForm function in the OnSelect property of a Button control to save any changes in a Form control to the data source.

提交任何更改之前,针对被标记为必需或其值有一个或多个约束的字段,此函数会检查验证问题。Before submitting any changes, this function checks for validation issues with any field that's marked as required or that has one or more constraints on its value. 此行为与 Validate 函数类似。This behavior matches that of the Validate function.

SubmitForm 还会检查窗体的 Valid 属性,这包括窗体控件所包含的卡片控件的所有 Valid 属性。SubmitForm also checks the Valid property of the Form, which is an aggregation of all the Valid properties of the Card controls that the Form control contains. 如果出现问题,数据将不会提交,并且窗体控件的 ErrorErrorKind 属性会进行相应的设置。If a problem occurs, the data isn't submitted, and the Error and ErrorKind properties of the Form control are set accordingly.

如果通过验证,SubmitForm 会将更改提交到数据源。If validation passes, SubmitForm submits the change to the data source.

  • 若成功提交,将运行窗体的 OnSuccess 行为,并清除 ErrorErrorKind 属性。If successful, the Form's OnSuccess behavior runs, and the Error and ErrorKind properties are cleared. 如果窗体之前处于 FormMode.New 模式下,则窗体将返回 FormMode.Edit 模式。If the form was in FormMode.New mode, it is returned to FormMode.Edit mode.
  • 若提交失败,将运行窗体的 OnFailure 行为,并且 ErrorErrorKind 属性会进行相应设置。If unsuccessful, the Form's OnFailure behavior runs, and the Error and ErrorKind properties are set accordingly. 窗体的模式保持不变。The mode of the form is unchanged.

EditFormEditForm

EditForm 函数将窗体控件的模式更改为 FormMode.EditThe EditForm function changes the Form control's mode to FormMode.Edit. 在此模式下,将使用窗体控件的 Item 属性的内容来填充窗体。In this mode, the contents of the Form control's Item property are used to populate the form. 如果在窗体处于此模式下时运行 SubmitForm 函数,则将更改(而非创建)记录。If the SubmitForm function runs when the form is in this mode, a record is changed, not created. FormMode.Edit 是窗体控件的默认模式。FormMode.Edit is the default for the Form control.

NewFormNewForm

NewForm 函数将窗体控件的模式更改为 FormMode.NewThe NewForm function changes the Form control's mode to FormMode.New. 在此模式下,窗体控件的 Item 属性的内容会被忽略,而使用窗体的 DataSource 属性的默认值来填充窗体。In this mode, the contents of the Form control's Item property are ignored, and the default values of the Form's DataSource property populate the form. 如果在窗体处于此模式下时运行 SubmitForm 函数,则将创建(而非更改)记录。If the SubmitForm function runs when the form is in this mode, a record is created, not changed.

ResetFormResetForm

ResetForm 函数将窗体的内容重置为其初始值,即用户进行任何更改之前的值。The ResetForm function resets the contents of a form to their initial values, before the user made any changes. 如果窗体处于 FormMode.New 模式下,则窗体将重置为 FormMode.Edit 模式。If the form is in FormMode.New mode, the form is reset to FormMode.Edit mode. 还将运行窗体控件的 OnReset 行为。The OnReset behavior of the form control also runs. 还可以使用 Reset 函数重置各个控件,但仅可以从表单内进行重置。You can also reset individual controls with the Reset function but only from within the form.

ViewFormViewForm

ViewForm 函数将表单控件的模式更改为 FormMode.View。The ViewForm function changes the Form control's mode to FormMode.View. 在此模式下,将使用窗体控件的 Item 属性的内容来填充窗体。In this mode, the contents of the Form control's Item property are used to populate the form. 在此模式下,SubmitForm 和 RestForm 函数不起作用。The SubmitForm and RestForm functions have no effect when in this mode.

DisplayMode 属性DisplayMode Poperty

可通过 Mode 属性读取当前模式。The current mode can be read through the Mode property. 该模式还可以确定 DisplayMode 属性的值,数据卡和控件可在表单控件中使用该属性。The mode also determines the value of the DisplayMode property which can be used by data cards and controls within the form control. 通常情况下,如操作控件的 DisplayMode 属性(引用数据卡)一样,将数据卡的 DisplayMode 属性设置为 Parent.DisplayMode(引用表单):Often, the data card's DisplayMode property will be set to Parent.DisplayMode (refernceing the form) as will the control's DisplayMode property (referncing the data card):

模式Mode DisplayModeDisplayMode 说明Description
FormMode.EditFormMode.Edit DisplayMode.EditDisplayMode.Edit 数据卡和控件是可编辑的,可以接受对记录的更改。Data cards and controls are editable, ready to accept changes to a record.
FormMode.NewFormMode.New DisplayMode.EditDisplayMode.Edit 数据卡和控件是可编辑的,可以接受对新记录的更改。Data cards and controls are editable, ready to accept a new record.
FormMode.ViewFormMode.View DisplayMode.ViewDisplayMode.View 数据卡和控件不可出于查看目的进行编辑和优化。Data cards and controls are not editable and optimized for viewing.

语法Syntax

SubmitForm( FormName )SubmitForm( FormName )

  • FormName - 必需。FormName - Required. 要提交到数据源的窗体控件。Form control to submit to the data source.

EditForm( FormName )EditForm( FormName )

  • FormName - 必需。FormName - Required. 要切换到 FormMode.Edit 模式的窗体控件。Form control to switch to FormMode.Edit mode.

NewForm( FormName )NewForm( FormName )

  • FormName - 必需。FormName - Required. 要切换到 FormMode.New 模式的窗体控件。Form control to switch to FormMode.New mode.

ResetForm( FormName )ResetForm( FormName )

  • FormName - 必需。FormName - Required. 要重置为初始值的窗体控件。Form control to reset to initial values. 还会将窗体从 FormMode.New 模式切换到 FormMode.Edit 模式。Also switches the form from FormMode.New mode to FormMode.Edit mode.

ViewForm( FormName )ViewForm( FormName )

  • FormName - 必需。FormName - Required. 要切换到 FormMode.View 模式的表单控件。Form control to switch to FormMode.View mode.

示例Examples

请参阅了解数据窗体获取完整示例。See Understand data forms for complete examples.

  1. 添加一个按钮控件,将其 Text 属性设置为显示“保存”,并将其 OnSelect 属性设置为以下公式:Add a Button control, set its Text property to show Save, and set its OnSelect property to this formula:

    SubmitForm( EditForm )SubmitForm( EditForm )

  2. 将窗体控件的 OnFailure 属性设置为空白,将其 OnSuccess 属性设置为以下公式:Set the OnFailure property of a Form control to blank and its OnSuccess property to this formula:

    Back()Back()

  3. 将“标签”控件命名为“ErrorText”,然后将“Text”属性设置为以下公式:Name a Label control ErrorText, and set its Text property to this formula:

    EditForm.ErrorEditForm.Error

    用户选择“保存”按钮后,窗体控件中的任何更改都会提交到基础数据源。When the user selects the Save button, any changes in the Form control are submitted to the underlying data source.

    • 如果提交成功,则会保存所有更改;或者如果窗体控件处于“新建”模式下,则会创建一条记录。If the submission succeeds, any changes are saved or, if the Form control is in New mode, a record is created. ErrorText 为空白,且上一个屏幕再次出现。ErrorText is blank and the previous screen reappears.
    • 如果提交失败,ErrorText 会显示用户友好的错误消息,并且当前屏幕会保持可见,以便用户可以更正问题并重试。If the submission fails, ErrorText shows a user-friendly error message, and the current screen remains visible so that the user can correct the problem and try again.
  4. 添加一个按钮控件,将其 Text 属性设置为显示“取消”,并将其 OnSelect 属性设置为以下公式:Add a Button control, set its Text property to show Cancel, and set its OnSelect property to this formula:

    ResetForm( EditForm ); Back()ResetForm( EditForm ); Back()

    用户选择“取消”按钮后,窗体控件中的值会被重置为用户对其进行编辑之前的值,上一个屏幕将再次出现,并且如果窗体控件之前处于“新建”模式下,则它将返回“编辑”模式。When the user selects the Cancel button, the values in the Form control are reset to what they were before the user started to edit it, the previous screen reappears, and the Form control is returned to Edit mode if it was in New mode.

  5. 添加一个按钮控件,将其 Text 属性设置为显示“新建”,并将其 OnSelect 属性设置为以下公式:Add a Button control, set its Text property to show New, and set its OnSelect property to this formula:

    NewForm( EditForm ); Navigate( EditScreen, None )NewForm( EditForm ); Navigate( EditScreen, None )

    用户选择“新建”按钮后,窗体控件将切换到“新建”模式,窗体控件数据源的默认值将填充该控件,并出现包含该窗体控件的屏幕。When the user selects the New button, the Form control switches to New mode, the default values for the Form control's data source populate that control, and the screen that contains the Form control appears. SubmitForm 函数运行时,将创建(而非更新)记录。When the SubmitForm function runs, a record is created instead of updated.