Utilizar o controlo Formulário de entidadeUse the Entity form control

Crie aplicações mais rapidamente através do controlo Formulário de entidade para adicionar formulários avançados para uma entidade do Common Data Service.Create apps faster by using the Entity form control to add rich forms for a Common Data Service entity.

Para obter uma introdução ao controlo Formulário de entidade, veja esta mensagem de blogue: New entity form control (experimental feature) for 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.

Importante

Tenha em atenção a natureza experimental do controlo Formulário de entidade, conforme descrito na mensagem de blogue e tenha cuidado ao utilizar o controlo Formulário de entidade em aplicações de produção, pelo menos por agora.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.

Propriedades principaisKey properties

Eis as propriedades chave de um controlo Formulário de entidade.Here are the key properties of an Entity form control.

DataSource – Especifica a origem de dados que contém o(s) registo(s) que pretende apresentar.DataSource – Specifies the data source that contains the record(s) that you want to display.

Nota

De momento, apenas as entidades no Common Data Service são suportadas como origens de dados para o controlo Formulário de entidade.Currently only entities in the Common Data Service are supported as data sources for the Entity form control.

Pattern – Especifica o estilo do formulário que pretende apresentar no controlo Formulário de entidade.Pattern – Specifies the style of the form that you want to display in the Entity form control. Defina esta propriedade através da enumeração FormPattern.Set this property by using the FormPattern enumeration.

  • FormPattern.List – Apresenta uma lista de registos em forma de tabela.FormPattern.List – Displays a tabular list of records.
  • FormPattern.CardList – Apresenta uma lista de registos em forma de cartão.FormPattern.CardList – Displays a card list of records.
  • FormPattern.Details – Apresenta um formulário para ver ou editar os detalhes de um único registo.FormPattern.Details – Displays a form to view or edit the details of a single record.
  • FormPattern.None – Não foi especificado explicitamente um estilo.FormPattern.None – No style has been explicitly specified. A predefinição é List para aplicações de tablet e CardList para aplicações de telemóvel.Defaults to List for tablet apps and CardList for phone apps.

Item – Especifica o registo na origem de dados que o controlo Formulário de entidade deve apresentar.Item – Specifies the record in the data source that the Entity form control should display. Esta propriedade é utilizada apenas quando Pattern está definido como FormPattern.Details.This property is used only when Pattern is set to FormPattern.Details.

Selected – Obtém o registo atualmente selecionado.Selected – Gets the record that’s currently selected.
Exemplo: se o controlo Formulário de entidade apresentar uma lista de registos de ordem de venda, a propriedade Selected irá dar-lhe o registo atualmente selecionado.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. Também pode aceder a um campo dentro de um registo.You can also access a field within a record. (Por exemplo, especifique o valor do campo Conta do registo selecionado como Selected.Account.)(For example, specify the value of the Account field of the selected record as Selected.Account.)

SelectableFields – Especifica os campos que devem ser apresentados como ligações.SelectableFields – Specifies which fields should appear as links. Para definir o valor desta propriedade, utilize esta sintaxe:Set the value of this property by using this syntax:
{Field1Name : true, Field2Name : true}{Field1Name : true, Field2Name : true}
Exemplo: se pretender que os campos SalesOrderId e Conta sejam apresentados como ligações num formulário, defina a propriedade SelectableFields desse formulário com este valor: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 – Determina em que campo clicou ou tocou.SelectedField – Determines which field was clicked or tapped. É aplicável apenas aos campos especificados como SelectableFields.This applies only to the fields specified as SelectableFields.
Exemplo: se definir a propriedade SelectableFields como {SalesOrderId : true, Account : true} e o utilizador clicar ou tocar no campo Conta, SelectedField.Account é definido como 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 – Como uma aplicação responde quando o utilizador clica ou toca num campo.OnFieldSelect – How an app responds when the user clicks or taps a field. É aplicável apenas aos campos especificados como SelectableFields.This applies only to the fields specified as SelectableFields.

Modo – Determina o modo do formulário.Mode – Determines the mode of the form. Para alterar o modo, utilize a função ViewForm, EditForm ou NewForm.To change the mode, use the ViewForm, EditForm, or NewForm function. Estas funções só funcionam quando a propriedade Pattern está definida como FormPattern.Details.These functions work only when the Pattern property is set to FormPattern.Details. Defina o valor da propriedade Mode como um valor da enumeração FormMode.Set the value of the Mode property to a value of the FormMode enumeration.

  • FormMode.View – Permite aos utilizadores ver, mas não editar ou adicionar um registo.FormMode.View – Allows users to view but not edit or add a record.
  • FormMode.Edit – Permite aos utilizadores editar um registo.FormMode.Edit – Allows users to edit a record.
  • FormMode.New – Permite aos utilizadores adicionar um registo.FormMode.New – Allows users to add a record.

OnSuccess – Como uma aplicação responde quando uma operação de dados foi bem-sucedida.OnSuccess – How an app responds when a data operation has been successful.

OnFailure – Como uma aplicação responde quando uma operação de dados não foi bem-sucedida.OnFailure - How an app responds when a data operation has been unsuccessful.

Unsaved – Determina se um registo que um utilizador está a editar tem alterações não guardadas.Unsaved – Determines whether a record that a user is editing has unsaved changes.

Pode utilizar estas funções partilhadas com o controlo Formulário de entidade ou com o controlo Editar formulário.You can use these shared functions with either the Entity form control or the Edit form control. Estas funções só funcionam com o controlo Formulário de entidade quando a respetiva propriedade Pattern está definida como FormPattern.Details.These functions work with the Entity form control only when its Pattern property is set to FormPattern.Details.

ViewForm – Define a propriedade Mode de um controlo Formulário de entidade como FormMode.View.ViewForm – Sets the Mode property of an Entity form control to FormMode.View.

EditForm – Define a propriedade Mode de um controlo Formulário de entidade como FormMode.Edit.EditForm- Sets the Mode property of an Entity form control to FormMode.Edit.

NewForm – Define a propriedade Mode de um controlo Formulário de entidade como FormMode.New.NewForm - Sets the Mode property of an Entity form control to FormMode.New.

SubmitForm – Guarda as alterações quando um utilizador edita um registo num controlo Formulário de entidade.SubmitForm - Saves changes when a user edits a record in an Entity form control.

ResetForm – Abandona as alterações não guardadas quando um utilizador edita um registo num controlo Formulário de entidade.ResetForm - Abandons unsaved changes when a user edits a record in an Entity form control.

Agora que tem uma descrição geral das várias propriedades e funções, vamos vê-las em ação.Now that you have an overview of the various properties and functions, let’s look at them in action.

Nota

Se não tiver acesso a uma base de dados do Common Data Service, crie uma antes de começar a seguir estes passos.If you don’t have access to a Common Data Service database, create one before you start to follow these steps.

Apresentar uma lista de registosDisplay a list of records

Os cinco procedimentos seguintes fornecem um exemplo único, ponto a ponto, sobre como utilizar os controlos de Formulário de entidade.The next five procedures provide a single, end-to-end example of how to use Entity form controls. Neste procedimento, adicione um formulário que mostra uma lista de ordens de venda.In this procedure, add a form that shows a list of sales orders.

  1. Crie uma aplicação de tablet em branco.Create a blank tablet app.

  2. Mude o nome do primeiro ecrã SalesOrderListScreen.Rename the first screen SalesOrderListScreen.

  3. No separador Inserir, clique ou toque em Formulários e, em seguida, clique ou toque em Formulário de entidade (experimental).On the Insert tab, click or tap Forms, and then click or tap Entity form (experimental).

    Um controlo Formulário de entidade é adicionado ao ecrã.An Entity form control is added to the screen.

  4. Mude o nome do controlo Formulário de entidade SalesOrderListForm e redimensione-o para cobrir o ecrã inteiro.Rename the Entity form control SalesOrderListForm, and resize it to cover the entire screen.
  5. No painel da direita, clique ou toque no ícone de base de dados junto a Nenhuma origem de dados selecionada e, em seguida, clique ou toque em Adicionar uma origem de dados.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. Na lista de ligações, clique ou toque na ligação para a base de dados.In the list of connections, click or tap the connection for your database.

  7. Na lista de entidades, clique ou toque em Ordem de venda e, em seguida, clique ou toque em Ligar.In the list of entities, click or tap Sales order, and then click or tap Connect.

    É criada uma origem de dados para a entidade Ordem de venda e a propriedade DataSource do SalesOrderListForm é definida como essa origem de dados.A data source for the Sales order entity is created, and the DataSource property of the SalesOrderListForm is set to that data source.

    O controlo Formulário de entidade mostra uma lista de ordens de venda.The Entity form control shows a list of sales orders. Ao utilizar o controlo Formulário de entidade, apresentou rapidamente uma lista sem ter de criá-la manualmente.By using the Entity form control, you quickly displayed a list form without having to manually build it.

    Como não definiu a propriedade Pattern para o controlo Formulário de entidade, utiliza a predefinição List.You didn’t set the Pattern property for the Entity form control, so it defaults to the List pattern. Além disso, o grupo de campos DefaultList da entidade Ordem de venda é utilizado para apresentar o formulário de lista.In addition, the DefaultList field group of the Sales order entity is used to display the list form. O formulário é também dinâmico e irá refletir automaticamente qualquer alteração no grupo de campos.The form is also dynamic and will automatically reflect any change in the field group.

  8. (Opcional) Veja o grupo de campos DefaultList da entidade Ordem de venda:(Optional) View the DefaultList field group of the Sales order entity:

    1. Inicie sessão em powerapps.com, clique ou toque em Common Data Service no painel de navegação à esquerda e, em seguida, clique ou toque em Entidades.Sign in to powerapps.com, click or tap Common Data Service in the left navigation pane, and then click or tap Entities.
    2. Na lista de entidades, clique ou toque em Ordem de venda, clique ou toque no separador Grupos de campos e, em seguida, clique ou toque no grupo de campos 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.

      Os campos na lista de ordens de venda correspondem aos campos listados aqui.The fields in the sales order list match those listed here.

      No Common Data Service, pode modificar grupos de campos para entidades personalizadas (mas não para entidades padrão) para alterar os campos que aparecem nos formulários correspondentes que o controlo Formulário de entidade apresenta.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. O melhor de tudo é que qualquer alteração ao grupo de campos é refletida automaticamente em todas as aplicações que utilizam um controlo Formulário de entidade para apresentar o formulário correspondente.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.

Apresentar os detalhes de um registoDisplay the details of a record

Vamos adicionar outro controlo Formulário de entidade para apresentar os detalhes da ordem de venda que está selecionada na lista que criou anteriormente.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. Redimensione o SalesOrderListForm para cobrir metade do ecrã e adicione um segundo controlo Formulário de entidade para cobrir a outra metade do ecrã.Resize SalesOrderListForm to cover half the screen, and add a second Entity form control to cover the other half of the screen.

  2. Mude o nome do segundo controlo Formulário de entidade SalesOrderDetailsForm e ligue-o à origem de dados Ordem de venda que criou anteriormente.Rename the second Entity form control SalesOrderDetailsForm, and connect it to the Sales order data source that you created earlier.

  3. Defina a propriedade Pattern do SalesOrderDetailsForm como FormPattern.Details.Set the Pattern property of SalesOrderDetailsForm to FormPattern.Details.

    O SalesOrderDetailsForm utiliza o grupo de campos DefaultDetails da entidade Ordem de venda para apresentar o formulário.SalesOrderDetailsForm uses the DefaultDetails field group of the Sales order entity to display the form. Tal como acontece com o SalesOrderListForm, pode mostrar rapidamente os detalhes do registo sem ter de criar manualmente um formulário.As with the SalesOrderListForm, you can quickly show record details without having to manually build a form.

  4. Defina a propriedade Item do SalesOrderDetailsForm como SalesOrderListForm.Selected.Set the Item property of SalesOrderDetailsForm to SalesOrderListForm.Selected.

    O SalesOrderDetailsForm apresentará os detalhes do registo em que o utilizador clica ou toca em SalesOrderListForm.SalesOrderDetailsForm will display the details of the record that the user clicks or taps in SalesOrderListForm.

  5. Para pré-visualizar a aplicação, prima F5 e, em seguida, clique ou toque numa ordem de venda na lista à esquerda.Preview the app by pressing F5, and then click or tap a sales order in the list on the left.

    Os detalhes da ordem que selecionou aparecem no lado direito.The details of the order that you selected appear on the right side.

Configurar um campo para navegar para outro ecrãConfigure a field to navigate to another screen

Em seguida, vamos adicionar mais ecrãs à nossa aplicação e configurar os campos num controlo Formulário de entidade para navegar para outro ecrã na aplicação quando o utilizador clica ou toca num campo.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. Adicione um segundo ecrã à aplicação e mude o nome do ecrã SalesOrderDetailsScreen.Add a second screen to the app, and rename the screen SalesOrderDetailsScreen.
  2. Corte o SalesOrderDetailsForm, cole-o no SalesOrderDetailsScreen e redimensione o formulário para cobrir a maior parte do ecrã, deixando espaço suficiente para um ícone na parte superior.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. Adicione um ícone de seta para trás junto ao canto superior esquerdo do SalesOrderDetailsScreen.Add a back-arrow icon near the upper-left corner of SalesOrderDetailsScreen.
  4. Defina a propriedade OnSelect do ícone de seta para trás como a função Anterior.Set the OnSelect property of the back-arrow icon to the Back function.

  5. No SalesOrderListScreen, redimensione o SalesOrderListForm para cobrir o ecrã inteiro.On the SalesOrderListScreen, resize the SalesOrderListForm to cover the entire screen.
  6. Clique ou toque no SalesOrderListForm para selecioná-lo.Click or tap the SalesOrderListForm to select it.
  7. No painel da direita, em Campos, defina SalesOrderId para navegar para o SalesOrderDetailsScreen.In the right-hand pane, under Fields, set SalesOrderId to navigate to the SalesOrderDetailsScreen.

    O controlo Formulário de entidade apresenta os valores do campo SalesOrderId (a primeira coluna na lista) como ligações.The Entity form control displays the values in the SalesOrderId field (the first column in the list) as links.

  8. Para pré-visualizar a aplicação, prima F5 e, em seguida, clique ou toque numa ligação na lista de ordens de venda.Preview the app by pressing F5, and then click or tap a link in the list of sales orders.

    O segundo ecrã abre e apresenta os detalhes da ordem de venda que especificou.The second screen opens and displays the details of the sales order that you specified.

    Para apresentar os detalhes de uma ordem de venda diferente, clique ou toque na seta para trás para navegar novamente até à lista e, em seguida, clique ou toque na ligação da ordem para a qual pretende mostrar os detalhes.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.

A propriedade Item do SalesOrderDetailsForm está definida como SalesOrderListForm.Selected para que o SalesOrderDetailsForm mostre detalhes sobre o registo que o utilizador seleciona no 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. Também pode obter o contexto do registo selecionado através da variável de contexto NavigationContext, que é criada automaticamente quando utilizar o painel de personalização do formulário para configurar um campo para navegar.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. Defina a propriedade Item do SalesOrderDetailsForm como NavigationContext.Set the Item property of SalesOrderDetailsForm to NavigationContext.

  2. Para pré-visualizar a aplicação, prima F5 e, em seguida, clique ou toque numa ligação na lista de ordens de venda.Preview the app by pressing F5, and then click or tap a link in the list of sales orders.

    A aplicação abre o SalesOrderDetailsScreen e apresenta os detalhes da ordem de venda que especificou.The app opens SalesOrderDetailsScreen and displays the details of the sales order that you specified.

Vamos aprofundar a forma como o painel de personalização do formulário configura a navegação e o contexto.Let’s dig into how the form-customization pane sets up the navigation and context for us.

A propriedade SelectableFields do SalesOrderListForm especifica SalesOrderId como um campo selecionável.The SelectableFields property of the SalesOrderListForm specifies SalesOrderId as a selectable field.

Isto foi configurado automaticamente quando utilizámos o painel de personalização do formulário para fazer com que o campo SalesOrderId navegue até ao SalesOrderDetailsScreen.This was set up automatically when we used the form-customization pane to make the SalesOrderId field navigate to the SalesOrderDetailsScreen. Por isso, os valores existentes no campo SalesOrderId são apresentados como ligações.Therefore, the values in the SalesOrderId field appear as links.

A propriedade OnFieldSelect do SalesOrderListForm é definida como uma função If, que determina se o utilizador clica ou toca no campo ID da ordem de venda: SalesOrderListForm.SelectedField.SalesOrderId = true.The 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.

Se a função for avaliada como true, o SalesOrderDetailsScreen abre com a variável de contexto denominada NavigationContext que utilizámos anteriormente.If the function is evaluated as true, the SalesOrderDetailsScreen opens with the context variable named NavigationContext that we used earlier.

Tudo isto também foi configurado automaticamente quando utilizámos o painel de personalização do formulário para fazer com que o campo SalesOrderId navegue até ao SalesOrderDetailsScreen.All this was also set up automatically when we used the form-customization pane to make the SalesOrderId field navigate to the SalesOrderDetailsScreen.

Por isso, quando o utilizador clica ou toca num campo de ID de ordem de vendas, a função If é avaliada como true e a função Navigate é chamada com o contexto correspondente, abrindo o ecrã de detalhes.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.

Nota

Quando utiliza o painel de personalização do formulário, o NavigationContext é determinado de forma inteligente.When you use the form-customization pane, the NavigationContext is intelligently determined for you. Quando o utilizador clica ou toca em SalesOrderId, o NavigationContext é definido como SalesOrderListForm.Selected, como mostra a fórmula anterior.When the user clicks or taps SalesOrderId, NavigationContext is set to SalesOrderListForm.Selected, as the earlier formula shows. Se, em alternativa, tivéssemos especificado o campo Conta para a navegação, o NavigationContext teria sido definido como SalesOrderListForm.Selected.Account, garantindo que é transmitido o contexto correto.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. No entanto, para consumir esse contexto, precisaria de um controlo Formulário de entidade ligado à entidade Conta no 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.

Editar e guardar um registoEdit and save a record

Por fim, vamos ver como podemos editar e guardar um registo num controlo Formulário de entidade.Finally let’s look at how we can edit and save a record in an Entity form control.

  1. No SalesOrderDetailsScreen, adicione um ícone de edição e, em seguida, defina a respetiva propriedade OnSelect como esta fórmula:On the SalesOrderDetailsScreen, add an edit icon, and then set its OnSelect property to this formula:
    EditForm(SalesOrderDetailsForm)EditForm(SalesOrderDetailsForm)

  2. Adicione um ícone de marca de verificação junto ao ícone de edição e, em seguida, defina a propriedade OnSelect do ícone de marca de verificação como esta fórmula: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. Para pré-visualizar a aplicação, prima F5, clique ou toque numa ligação ID da ordem de venda para ver os detalhes de uma ordem de venda e, em seguida, clique ou toque no ícone de edição.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.

    O Modo do controlo Formulário de entidade está definido como FormMode.Edit para que possa editar o registo.The Mode of the Entity form control is set to FormMode.Edit so that you can edit the record.

  4. Atualize o Estado da encomenda para Fatura.Update the Order status to Invoice.

  5. Atualize o Vendedor para WRK014.Update the Sales person to WRK014.

    Para o ajudar a escolher o Vendedor, o controlo Formulário de entidade compõe automaticamente uma pesquisa detalhada avançada.To help you pick the Sales person, the Entity form control automatically renders a rich detailed lookup. Para gerar e apresentar esta pesquisa, o controlo utiliza o grupo de campos DefaultLookup da entidade Trabalhador no Common Data Service.To generate and display this lookup, the control uses the DefaultLookup field group of the Worker entity in the Common Data Service. A entidade Trabalhador é utilizada porque o campo Vendedor é do tipo Trabalhador.The Worker entity is used because the Sales person field is of type Worker.

  6. Clique ou toque no ícone de marca de verificação para guardar as alterações.Click or tap the checkmark icon to save your changes.

Este passo conclui este artigo sobre como utilizar o controlo Formulário de entidade nas suas aplicações.This step concludes this article on how to use the Entity form control in your apps. Esperamos que considere as informações aqui abrangidas úteis para começar a utilizar o controlo Formulário de entidade.We hope that you find the information covered here useful to get started using the Entity form control. Estamos ansiosos por saber a sua opinião sobre o controlo Formulário de entidade e o nosso esforço geral no sentido de o ajudar a adicionar rapidamente formulários avançados às suas aplicações.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.