EditForm、NewForm、SubmitForm、ResetForm 和 ViewForm 函式

適用於: 畫布應用程式

Edit form 控制項中檢視、編輯或建立項目、儲存內容及重設控制項。

概觀

這些函式會變更 Edit form 控制項的狀態。 Form 控制項可以是以下其中一個模式:

模式 描述
FormMode.Edit 表單中會填入現有記錄,且使用者可修改欄位的值。 完成後,使用者可以將變更儲存至記錄。
FormMode.New 表單中會填入預設值,且使用者可修改欄位的值。 完成後,使用者可以將記錄新增至資料來源。
FormMode.View 表單中會填入現有記錄,但使用者無法修改欄位的值。

描述

通常會從ButtonImage控制項的 OnSelect公式叫用這些函式,讓使用者可以儲存編輯、放棄編輯,或建立一筆記錄。 您可以一起使用控制項和這些函式來建立完整的解決方案。

這些函式不會傳回任何值。

您可以只在 行為公式 內使用這些函式。

SubmitForm

使用 Button 控制項的 OnSelect 屬性中的 SubmitForm 函式,將 Form 控制項中的任何變更儲存至資料來源。

提交任何變更之前,此函式會檢查任何標示為必要,或其值具有一個或多個條件約束之欄位的驗證問題。 此行為與 Validate 函式的相符。

SubmitForm 也會檢查表單的 Valid 屬性,其為 Form 控制項包含的 Card 控制項之所有 Valid 屬性的彙總。 如果發生問題時,不會提交資料,且會據以設定 Form 控制項的 ErrorErrorKind 屬性。

如果驗證通過,SubmitForm 會將變更提交至資料來源。

  • 如果成功,會執行表單的 OnSuccess 行為,並且會清除 ErrorErrorKind 屬性。 如果表單是在 FormMode.New 模式中,它會傳回至 FormMode.Edit 模式。
  • 如果不成功,會執行表單的 OnFailure 行為,並且會據以設定 ErrorErrorKind 屬性。 表單的模式不變。

EditForm

EditForm 函式會將 Form 控制項的模式變更為 FormMode.Edit。 在此模式中, Form 控制項的 Item 屬性之內容會用來填入表單。 如果表單在此模式中時執行 SubmitForm 函式,則會變更而非建立記錄。 FormMode.Edit 是 Form 控制項的預設值。

注意

當表單處於編輯模式且項目為 Null 時,不會評估資料卡屬性,而會傳回預設值。

NewForm

NewForm 函式會將 Form 控制項的模式變更為 FormMode.New。 在此模式中,會忽略 Form 控制項 Item 屬性的內容,表單的 DataSource 屬性預設值會填入表單。 如果表單在此模式中時執行 SubmitForm 函式,則會建立而非變更記錄。

ResetForm

ResetForm 函式會在使用者進行任何變更之前將表單的內容重設為其初始值。 如果表單是在 FormMode.New 模式中,表單會重設為 FormMode.Edit 模式。 還會執行 Form 控制項的 OnReset 行為。 您也可透過 Reset 函式重設個別控制項,但只能從表單內進行。

ViewForm

ViewForm 函式會將 Form 控制項的模式變更為 FormMode.View。 在此模式中, Form 控制項的 Item 屬性之內容會用來填入表單。 SubmitFormResetForm 函式在此模式中都不會作用。

DisplayMode 屬性

目前的模式可透過 Mode 屬性閱讀。 模式也會決定 DisplayMode 屬性的值,其可供 Form 控制項內的資料卡和控制項使用。 通常,資料卡的 DisplayMode 屬性會設為 Parent.DisplayMode (引用表單),控制項的 DisplayMode 屬性也是 (引用資料卡):

模式 DisplayMode 描述
FormMode.Edit DisplayMode.Edit 資料卡片和控制項可以編輯,且準備好接受記錄的變更。
FormMode.New DisplayMode.Edit 資料卡片和控制項可以編輯,且準備好接受新記錄。
FormMode.View DisplayMode.View 資料卡和控制項無法編輯和最佳化以供檢視。

語法

SubmitForm( FormName )

  • FormName - 必要項目。 要提交至資料來源的 Form 控制項。

EditForm (FormName)

  • FormName - 必要項目。 要切換至 FormMode.Edit 模式的 Form 控制項。

NewForm (FormName)

  • FormName - 必要項目。 要切換至 FormMode.New 模式的 Form 控制項。

ResetForm (FormName)

  • FormName - 必要項目。 要重設為初始值的 Form 控制項。 還會將表單從 FormMode.New 模式切換為 FormMode.Edit 模式。

ViewForm (FormName)

  • FormName - 必要項目。 要切換至 FormMode.View 模式的 Form 控制項。

範例

如需完整的範例,請參閱了解資料形式

  1. 新增 Button 控制項、設定其 Text 屬性以顯示 Save,然後將其 OnSelect 屬性設為以下公式:

    SubmitForm( EditForm )

  2. 將 Form 控制項的 OnFailure 屬性設為空白,並將其 OnSuccess 屬性設為此公式︰

    Back()

  3. Label 控制項命名為 ErrorText,並將其Text屬性設定為下列公式:

    EditForm.Error

    當使用者選取 Save 按鈕時, Form 控制項中的任何變更會提交至基礎資料來源。

    • 如果提交成功,會儲存任何變更,或如果 Form 控制項是在新增模式中,則會建立一筆資料。 ErrorTextblank,且會再次出現前一個畫面。
    • 如果提交失敗,ErrorText 會顯示使用者易記的錯誤訊息,且目前螢幕保持可見狀態,讓使用者能夠更正問題並再試一次。
  4. 新增一個 Button 控制項、設定其 Text 屬性以顯示 Cancel,然後將其 OnSelect 屬性設為以下公式:

    ResetForm( EditForm ); Back()

    當使用者選取 Cancel 按鈕時, Form 控制項中的值會重設為使用者開始進行編輯它之前的值、上一個畫面會再次出現,且 Form 控制項會傳回至 Edit 模式,如果它是在 New 模式中。

  5. 新增 Button 控制項,並設定其 Text 屬性以顯示 New,然後將其 OnSelect 屬性設為以下公式:

    NewForm( EditForm ); Navigate( EditScreen, None )

    當使用者選取 New 按鈕時, Form 控制項會切換至 New 模式, Form 控制項資料來源的預設值會填入該控制項,並會顯示包含 Form 控制項的畫面。 當 SubmitForm 函式執行時,會建立而不是更新記錄。