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:

ModeMode 說明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.ViewThe 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. SubmitFormRestForm 函式在此模式中都不會作用。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 屬性會設為 Parent.DisplayMode (參考表單),控制項的 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):

ModeMode 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 屬性以顯示 Save,然後將其 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 屬性以顯示 Cancel,然後將其 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 屬性以顯示 New,然後將其 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.