使用實體表單控制項Use the Entity form control

使用實體表單控制項新增 Common Data Service 實體的多樣化表單,更快速建立應用程式。Create apps faster by using the Entity form control to add rich forms for a Common Data Service entity.

如需實體表單控制項的簡介,請參閱部落格文章︰Common Data Service 的新實體表單控制項 (實驗性功能)For an introduction to the Entity form control, see this blog post: New entity form control (experimental feature) for Common Data Service.

重要

請注意部落格貼文中所述之「實體表單」的實驗性質,並在生產應用程式中小心使用實體表單控制項,至少目前須如此。Please be aware of the experimental nature of the Entity form control as outlined in the blog post, and be careful about using the Entity form control in production apps, at least for now.

主要屬性Key properties

以下是實體表單控制項的索引鍵屬性。Here are the key properties of an Entity form control.

DataSource - 指定要顯示的記錄包含在其中的資料來源。DataSource – Specifies the data source that contains the record(s) that you want to display.

注意

Common Data Service 中的實體目前僅支援實體表單控制項的資料來源。Currently only entities in the Common Data Service are supported as data sources for the Entity form control.

Pattern – 指定想要在實體表單控制項中顯示的表單樣式。Pattern – Specifies the style of the form that you want to display in the Entity form control. 使用 FormPattern 列舉設定此屬性。Set this property by using the FormPattern enumeration.

  • FormPattern.List – 顯示記錄的表格式清單。FormPattern.List – Displays a tabular list of records.
  • FormPattern.CardList – 顯示記錄的卡片清單。FormPattern.CardList – Displays a card list of records.
  • FormPattern.Details – 顯示檢視或編輯單筆記錄詳細資料的表單。FormPattern.Details – Displays a form to view or edit the details of a single record.
  • FormPattern.None – 未明確指定任何樣式。FormPattern.None – No style has been explicitly specified. 平板電腦應用程式預設為 List,手機應用程式預設為 CardListDefaults to List for tablet apps and CardList for phone apps.

Item – 指定資料來源中實體表單控制項應顯示的記錄。Item – Specifies the record in the data source that the Entity form control should display. Pattern 設為FormPattern.Details 時,才使用這個屬性。This property is used only when Pattern is set to FormPattern.Details.

Selected – 取得目前選取的記錄。Selected – Gets the record that’s currently selected.
範例︰如果實體表單控制項顯示銷售單記錄的清單,則 Selected 屬性將提供目前選取的記錄。Example: If the Entity form control displays a list of sales-order records, the Selected property will give you the record that’s currently selected. 您也可以存取記錄的欄位。You can also access a field within a record. (例如,將所選記錄的 Account 欄位值指定為 Selected.Account。)(For example, specify the value of the Account field of the selected record as Selected.Account.)

SelectableFields – 指定應該顯示為連結的欄位。SelectableFields – Specifies which fields should appear as links. 使用此語法,設定這個屬性的值︰Set the value of this property by using this syntax:
{Field1Name : true, Field2Name : true}{Field1Name : true, Field2Name : true}
範例︰如果要 SalesOrderIdAccount 在表單中顯示為連結,請將該表單的 SelectableFields 屬性設定為下列這個值︰Example: If you want the SalesOrderId and Account fields to appear as links in a form, set the SelectableFields property of that form to this value:
{SalesOrderId : true, Account : true}{SalesOrderId : true, Account : true}

SelectedField – 決定按一下或點選的欄位。SelectedField – Determines which field was clicked or tapped. 這只適用於指定為 SelectableFields 的欄位。This applies only to the fields specified as SelectableFields.
範例︰ 如果您將 SelectableFields 屬性設定為 {SalesOrderId : true, Account : true},而且使用者按一下或點選 Account 欄位,則 SelectedField.Account 會設定為 true。Example: If you set the SelectableFields property to {SalesOrderId : true, Account : true} and the user clicks or taps the Account field, SelectedField.Account is set to true.

OnFieldSelect – 應用程式在使用者按一下或點選欄位時回應的方式。OnFieldSelect – How an app responds when the user clicks or taps a field. 這只適用於指定為 SelectableFields 的欄位。This applies only to the fields specified as SelectableFields.

Mode – 決定表單的模式。Mode – Determines the mode of the form. 若要變更模式,請使用 ViewFormEditFormNewForm 函式。To change the mode, use the ViewForm, EditForm, or NewForm function. 只有在 Pattern 屬性是設定為 FormPattern.Details 時,這些函式才會運作。These functions work only when the Pattern property is set to FormPattern.Details. Mode 屬性的值設定為 FormMode 列舉的值。Set the value of the Mode property to a value of the FormMode enumeration.

  • FormMode.View – 可讓使用者檢視記錄,但是無法編輯或新增記錄。FormMode.View – Allows users to view but not edit or add a record.
  • FormMode.Edit – 可讓使用者編輯記錄。FormMode.Edit – Allows users to edit a record.
  • FormMode.New – 可讓使用者新增記錄。FormMode.New – Allows users to add a record.

OnSuccess – 應用程式在資料作業成功時的回應方式。OnSuccess – How an app responds when a data operation has been successful.

OnFailure – 應用程式在資料作業不成功時的回應方式。OnFailure - How an app responds when a data operation has been unsuccessful.

Unsaved – 決定使用者編輯的記錄是否有未儲存的變更。Unsaved – Determines whether a record that a user is editing has unsaved changes.

您可以搭配編輯表單控制項的實體表單控制項來使用這些共用函式。You can use these shared functions with either the Entity form control or the Edit form control. 只有在 Pattern 屬性是設定為 FormPattern.Details 時,這些函式才可搭配實體表單控制項使用。These functions work with the Entity form control only when its Pattern property is set to FormPattern.Details.

ViewForm – 將實體表單控制項的 Mode 屬性設定為 FormMode.ViewViewForm – Sets the Mode property of an Entity form control to FormMode.View.

EditForm – 將實體表單控制項的 Mode 屬性設定為 FormMode.EditEditForm- Sets the Mode property of an Entity form control to FormMode.Edit.

NewForm – 將實體表單控制項的 Mode 屬性設定為 FormMode.NewNewForm - Sets the Mode property of an Entity form control to FormMode.New.

SubmitForm - 使用者編輯實體表單控制項中的記錄時儲存變更。SubmitForm - Saves changes when a user edits a record in an Entity form control.

ResetForm - 使用者編輯實體表單控制項中的記錄時放棄未儲存的變更。ResetForm - Abandons unsaved changes when a user edits a record in an Entity form control.

您已經大致了解各種屬性和函式,讓我們看看這些屬性和函式的實際應用。Now that you have an overview of the various properties and functions, let’s look at them in action.

注意

如果您沒有 Common Data Service 資料庫的存取權,請先建立資料庫,再開始進行下列步驟。If you don’t have access to a Common Data Service database, create one before you start to follow these steps.

顯示記錄清單Display a list of records

後續五個程序提供如何使用實體表單控制項的單一端對端範例。The next five procedures provide a single, end-to-end example of how to use Entity form controls. 在此程序中,新增顯示銷售單清單的表單。In this procedure, add a form that shows a list of sales orders.

  1. 建立空白的平板電腦應用程式。Create a blank tablet app.

  2. 將第一個畫面 SalesOrderListScreen 重新命名。Rename the first screen SalesOrderListScreen.

  3. 在 [插入] 索引標籤上,按一下或點選 [Forms],然後按一下或點選 [實體表單 (實驗性)]。On the Insert tab, click or tap Forms, and then click or tap Entity form (experimental).

    實體表單控制項隨即新增至畫面。An Entity form control is added to the screen.

  4. 實體表單控制項 SalesOrderListForm 重新命名,並調整其大小,以便放大到整個畫面。Rename the Entity form control SalesOrderListForm, and resize it to cover the entire screen.
  5. 在右窗格中,按一下或點選 [未選取任何資料來源] 文字旁邊的資料庫圖示,然後按一下或點選 [新增資料來源]。In the right-hand pane, click or tap the database icon next to the text No data source selected, and then click or tap Add a data source.

  6. 在連線清單中,按一下或點選您資料庫的連線。In the list of connections, click or tap the connection for your database.

  7. 在實體清單中,按一下或點選 [銷售單],然後按一下或點選 [連接]。In the list of entities, click or tap Sales order, and then click or tap Connect.

    隨即建立銷售單實體的資料來源,而且 DataSource 屬性 SalesOrderListForm 會設定為資料來源。A data source for the Sales order entity is created, and the DataSource property of the SalesOrderListForm is set to that data source.

    實體表單控制項會顯示銷售單的清單。The Entity form control shows a list of sales orders. 使用實體表單控制項即可迅速顯示清單表單,完全不需要手動建立。By using the Entity form control, you quickly displayed a list form without having to manually build it.

    您未設定實體表單控制項的 Pattern 屬性,因此它會預設為 List 模式。You didn’t set the Pattern property for the Entity form control, so it defaults to the List pattern. 此外,銷售單實體的 DefaultList 欄位群組用來顯示清單表單。In addition, the DefaultList field group of the Sales order entity is used to display the list form. 表單亦為動態,會自動反映欄位群組中的任何變更。The form is also dynamic and will automatically reflect any change in the field group.

  8. (選擇性) 檢視銷售單實體的 DefaultList 欄位群組:(Optional) View the DefaultList field group of the Sales order entity:

    1. 登入powerapps.com,按一下或點選左方瀏覽窗格中的 Common Data Service,然後按一下或點選 [實體]。Sign in to powerapps.com, click or tap Common Data Service in the left navigation pane, and then click or tap Entities.
    2. 在實體清單中,按一下或點選 [銷售單],並按一下或點選 [欄位群組] 標籤,然後按一下或點選 DefaultList 欄位群組。In the list of entities, click or tap Sales order, click or tap the Field groups tab, and then click or tap the DefaultList field group.

      銷售單清單中的欄位符合此處所列的欄位。The fields in the sales order list match those listed here.

      Common Data Service 中,您可以針對自訂實體修改欄位群組 (而非標準實體) 來變更實體表單控制項顯示之對應表單上出現的欄位。In the Common Data Service, you can modify field groups for custom entities (but not standard entities) to change the fields that appear on the corresponding forms that the Entity form control displays. 特別是,使用實體表單控制項來顯示對應表單的所有應用程式,會自動反映欄位群組的所有變更。Best of all, any change to the field group is automatically reflected in all the apps that use an Entity form control to display the corresponding form.

顯示記錄的詳細資料Display the details of a record

讓我們新增另一個實體表單控制項,顯示您稍早建立的清單中選取之銷售單的詳細資料。Let’s add another Entity form control to display the details of the sales order that’s selected in the list that you created earlier.

  1. 調整 SalesOrderListForm 以涵蓋半個畫面,並新增第二個實體表單控制項來涵蓋另一半畫面。Resize SalesOrderListForm to cover half the screen, and add a second Entity form control to cover the other half of the screen.

  2. 將第二個實體表單控制項重新命名為 SalesOrderDetailsForm,並將其連接到您稍早建立的 [銷售單] 資料來源。Rename the second Entity form control SalesOrderDetailsForm, and connect it to the Sales order data source that you created earlier.

  3. SalesOrderDetailsFormPattern 屬性設定為 FormPattern.DetailsSet the Pattern property of SalesOrderDetailsForm to FormPattern.Details.

    SalesOrderDetailsForm 使用銷售單實體的 DefaultDetails 欄位群組來顯示表單。SalesOrderDetailsForm uses the DefaultDetails field group of the Sales order entity to display the form. SalesOrderListForm 一樣,可以迅速顯示記錄詳細資料,完全不需要手動建立表單。As with the SalesOrderListForm, you can quickly show record details without having to manually build a form.

  4. SalesOrderDetailsFormItem 屬性設定為 SalesOrderListForm.SelectedSet the Item property of SalesOrderDetailsForm to SalesOrderListForm.Selected.

    SalesOrderDetailsForm 將對於使用者在 SalesOrderListForm 中按一下或點選的記錄顯示詳細資料。SalesOrderDetailsForm will display the details of the record that the user clicks or taps in SalesOrderListForm.

  5. 按下 F5 鍵以預覽應用程式,然後按一下或點選左側清單中的銷售單。Preview the app by pressing F5, and then click or tap a sales order in the list on the left.

    您選取之訂單的詳細資料會出現在右側。The details of the order that you selected appear on the right side.

設定欄位,以便巡覽至其他畫面Configure a field to navigate to another screen

接著我們將更多畫面新增至我們的應用程式,然後設定實體表單控制項中的欄位在使用者按一下或點選欄位時巡覽至應用程式中的其他畫面。Next let’s add more screens to our app and then configure fields in an Entity form control to navigate to another screen in the app when the user clicks or taps a field.

  1. 將第二個畫面新增至應用程式,並將畫面 SalesOrderDetailsScreen 重新命名。Add a second screen to the app, and rename the screen SalesOrderDetailsScreen.
  2. 剪下 SalesOrderDetailsForm 並將其貼至 SalesOrderDetailsScreen 上,然後調整表單以涵蓋大部分畫面,在最上方留下足以顯示圖示的空間。Cut the SalesOrderDetailsForm, paste it on the SalesOrderDetailsScreen, and resize the form to cover most of the screen, leaving enough space for an icon at the top.
  3. SalesOrderDetailsScreen 的左上角附近新增上一步箭頭圖示。Add a back-arrow icon near the upper-left corner of SalesOrderDetailsScreen.
  4. 將上一步箭頭圖示的 OnSelect 屬性設定為 Back 函式。Set the OnSelect property of the back-arrow icon to the Back function.

  5. SalesOrderListScreen 上,調整 SalesOrderListForm 以涵蓋整個畫面。On the SalesOrderListScreen, resize the SalesOrderListForm to cover the entire screen.
  6. 按一下或點選 SalesOrderListForm 加以選取。Click or tap the SalesOrderListForm to select it.
  7. 在右窗格的 Fields 下,設定 SalesOrderId 以巡覽至 SalesOrderDetailsScreenIn the right-hand pane, under Fields, set SalesOrderId to navigate to the SalesOrderDetailsScreen.

    實體表單控制項會將 SalesOrderId 欄位 (清單中第一個資料行) 中的值顯示為連結。The Entity form control displays the values in the SalesOrderId field (the first column in the list) as links.

  8. 按下 F5 鍵以預覽應用程式,然後按一下或點選銷售單清單中的連結。Preview the app by pressing F5, and then click or tap a link in the list of sales orders.

    第二個畫面會開啟並顯示您指定之銷售單的詳細資料。The second screen opens and displays the details of the sales order that you specified.

    若要顯示不同銷售單的詳細資料,請按一下或點選上一步箭頭來返回清單,然後按一下或點選要顯示詳細資料的訂單連結。To display the details of a different sales order, click or tap the back arrow to navigate back to the list, and then click or tap the link of the order for which you want to show details.

SalesOrderDetailsFormItem 屬性設定為 SalesOrderListForm.Selected,因此 SalesOrderDetailsForm 會顯示使用者在 SalesOrderListForm 中選取之記錄的詳細資料。The Item property of the SalesOrderDetailsForm is set to SalesOrderListForm.Selected so that SalesOrderDetailsForm shows details about the record that the user selects in SalesOrderListForm. 您也可以使用您使用表單自訂窗格來設定要巡覽之欄位時所自動建立的 NavigationContext 內容變數,取得所選記錄的內容。You can also get the context of the selected record by using the NavigationContext context variable, which gets automatically created when you use the form-customization pane to configure a field to navigate.

  1. SalesOrderDetailsFormItem 屬性設定為 NavigationContextSet the Item property of SalesOrderDetailsForm to NavigationContext.

  2. 按下 F5 鍵以預覽應用程式,然後按一下或點選銷售單清單中的連結。Preview the app by pressing F5, and then click or tap a link in the list of sales orders.

    應用程式會開啟 SalesOrderDetailsScreen,並顯示您指定之銷售單的詳細資料。The app opens SalesOrderDetailsScreen and displays the details of the sales order that you specified.

讓我們深入了解表單自訂窗格如何設定導覽和內容。Let’s dig into how the form-customization pane sets up the navigation and context for us.

SalesOrderListFormSelectableFields 屬性會將 SalesOrderId 指定為可選取的欄位。The SelectableFields property of the SalesOrderListForm specifies SalesOrderId as a selectable field.

我們使用表單自訂窗格設定 SalesOrderId 欄位巡覽至 SalesOrderDetailsScreen 時,這會自動設定。This was set up automatically when we used the form-customization pane to make the SalesOrderId field navigate to the SalesOrderDetailsScreen. 因此,SalesOrderId 欄位的值會顯示為連結。Therefore, the values in the SalesOrderId field appear as links.

SalesOrderListFormOnFieldSelect 屬性將設定為 If 函式,這將決定使用者是否按一下或點選 [銷售單識別碼] 欄位:SalesOrderListForm.SelectedField.SalesOrderId = trueThe OnFieldSelect property of the SalesOrderListForm is set to an If function, which determines whether the user clicks or taps the Sales order ID field: SalesOrderListForm.SelectedField.SalesOrderId = true.

如果函式評估為 true,將以先前所用名為 NavigationContext 的內容變數來開啟 SalesOrderDetailsScreenIf the function is evaluated as true, the SalesOrderDetailsScreen opens with the context variable named NavigationContext that we used earlier.

我們使用表單自訂窗格來設定 SalesOrderId 欄位巡覽至 SalesOrderDetailsScreen 時,也會自動設定所有這些項目。All this was also set up automatically when we used the form-customization pane to make the SalesOrderId field navigate to the SalesOrderDetailsScreen.

因此,使用者按一下或點選 [銷售單識別碼] 欄位時,If 函式會評估為 true,而且將以對應的內容呼叫 Navigate 函式,開啟詳細資料畫面。Therefore, when the user clicks or taps a sales order ID field, the If function evaluates to true, and the Navigate function is called with the corresponding context, opening the details screen.

注意

您使用表單自訂窗格時,系統以智慧方式為您決定 NavigationContextWhen you use the form-customization pane, the NavigationContext is intelligently determined for you. 使用者按一下或點選 SalesOrderId 時,NavigationContext 將設定為 SalesOrderListForm.Selected,如先前公式所示。When the user clicks or taps SalesOrderId, NavigationContext is set to SalesOrderListForm.Selected, as the earlier formula shows. 如果我們已指定將巡覽 Account 欄位,則 NavigationContext 會設定為 SalesOrderListForm.Selected.Account,確保傳遞正確的內容。If we had specified the Account field for navigation instead, NavigationContext would have been set to SalesOrderListForm.Selected.Account, ensuring that the correct context is passed. 不過,若要使用該內容,您會需要實體表單控制項以連接到 Common Data Service 的帳戶實體。However, to consume that context, you would need an Entity form control connected to the Account entity in the Common Data Service.

編輯和儲存記錄Edit and save a record

最後讓我們看看如何編輯並儲存實體表單控制項中的記錄。Finally let’s look at how we can edit and save a record in an Entity form control.

  1. SalesOrderDetailsScreen 上,新增編輯圖示,然後將其 OnSelect 屬性設定為此公式︰On the SalesOrderDetailsScreen, add an edit icon, and then set its OnSelect property to this formula:
    EditForm(SalesOrderDetailsForm)EditForm(SalesOrderDetailsForm)

  2. 在編輯圖示旁新增核取記號圖示,然後將核取記號圖示的 OnSelect 屬性設定為此公式︰Add a checkmark icon next to the edit icon, and then set the OnSelect property of the checkmark icon to this formula:
    SubmitForm(SalesOrderDetailsForm)SubmitForm(SalesOrderDetailsForm)

  3. 按下 F5 鍵以預覽應用程式、按一下或點選 [銷售單識別碼] 的連結來檢視銷售單的詳細資料,然後按一下或點選編輯圖示。Preview the app by pressing F5, click or tap a Sales order ID link to view the details of a sales order, and then click or tap the edit icon.

    實體表單控制項的 Mode 設定為 FormMode.Edit,因此您可以編輯記錄。The Mode of the Entity form control is set to FormMode.Edit so that you can edit the record.

  4. 將 [訂單狀態] 更新為 [發票]。Update the Order status to Invoice.

  5. 將 [銷售員] 更新為 [WRK014]。Update the Sales person to WRK014.

    為了協助您挑選銷售員實體表單控制項會自動呈現多樣化的詳細查閱。To help you pick the Sales person, the Entity form control automatically renders a rich detailed lookup. 若要產生並顯示此查閱,控制項將使用 Common Data Service 的背景工作角色實體之中的 DefaultLookup 欄位群組。To generate and display this lookup, the control uses the DefaultLookup field group of the Worker entity in the Common Data Service. 這將使用背景工作角色實體,因為 [銷售員] 欄位是 Worker 類型。The Worker entity is used because the Sales person field is of type Worker.

  6. 按一下或點選核取記號圖示,以便儲存變更。Click or tap the checkmark icon to save your changes.

此步驟是這篇關於如何在應用程式中使用實體表單控制項文章的最後一個步驟。This step concludes this article on how to use the Entity form control in your apps. 我們期盼您覺得本文所包含之開始使用實體表單控制項的資訊很實用。We hope that you find the information covered here useful to get started using the Entity form control. 我們期待您提出實體表單控制項的看法,我們將全力協助您將多樣化的表單快速新增至您的應用程式。We look forward to hearing what you think about the Entity form control and our overall push toward helping you quickly add rich forms to your apps.