Usar o controle Formulário de entidadeUse the Entity form control

Crie aplicativos com mais rapidez usando o controle Formulário de entidade para adicionar formulários mais elaborados a 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 sobre o controle Formulário de entidade, lei esta postagem do blog: Novo controle Formulário de entidade (recurso experimental) para o 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

Esteja ciente da natureza experimental do controle Formulário de entidade, conforme descrito na postagem no blog, e tenha cuidado ao usar o controle Formulário de entidade em aplicativos de produção, pelo menos por enquanto.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-chaveKey properties

Estas são as principais propriedades de um controle Formulário de entidade.Here are the key properties of an Entity form control.

DataSource – especifica a fonte de dados que contém os registros que você deseja exibir.DataSource – Specifies the data source that contains the record(s) that you want to display.

Observação

No momento, somente as entidades no Common Data Service são compatíveis como fontes de dados para o controle 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 você deseja exibir no controle Formulário de entidade.Pattern – Specifies the style of the form that you want to display in the Entity form control. Defina essa propriedade usando a enumeração FormPattern.Set this property by using the FormPattern enumeration.

  • FormPattern.List – exibe uma lista tabular de registros.FormPattern.List – Displays a tabular list of records.
  • FormPattern.CardList – exibe uma lista tabular de registros.FormPattern.CardList – Displays a card list of records.
  • FormPattern.Details – exibe um formulário para mostrar ou editar os detalhes de um único registro.FormPattern.Details – Displays a form to view or edit the details of a single record.
  • FormPattern.None – nenhum estilo foi explicitamente especificado.FormPattern.None – No style has been explicitly specified. O padrão é List para aplicativos de tablet e CardList para aplicativos de celular.Defaults to List for tablet apps and CardList for phone apps.

Item – especifica o registro na fonte de dados a ser exibido pelo controle Formulário de entidade.Item – Specifies the record in the data source that the Entity form control should display. Esta propriedade é usada somente quando Pattern está definido como FormPattern.Details.This property is used only when Pattern is set to FormPattern.Details.

Selected – obtém o registro que está selecionado no momento.Selected – Gets the record that’s currently selected.
Exemplo: se o controle Formulário de entidade exibe uma lista de registros de ordens de venda, a propriedade Selected mostrará o registro que está selecionado no momento.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. Você também pode acessar um campo de um registro.You can also access a field within a record. Por exemplo, você pode especificar o valor do campo Account do registro selecionado como Selected.Account.(For example, specify the value of the Account field of the selected record as Selected.Account.)

SelectableFields – especifica quais campos devem ser exibidos como links.SelectableFields – Specifies which fields should appear as links. Defina o valor dessa propriedade usando esta sintaxe:Set the value of this property by using this syntax:
{Field1Name : true, Field2Name : true}{Field1Name : true, Field2Name : true}
Exemplo: se você quiser que os campos SalesOrderId e Account sejam exibidos como links em um formulário, defina a propriedade SelectableFields propriedade 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 qual campo foi clicado ou tocado.SelectedField – Determines which field was clicked or tapped. Isso se aplica somente aos campos especificados como SelectableFields.This applies only to the fields specified as SelectableFields.
Exemplo: se você definir a propriedade SelectableFields como {SalesOrderId : true, Account : true}, e o usuário clicar ou tocar no campo Account, SelectedField.Account será 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 um aplicativo responde quando o usuário clica ou toca em um campo.OnFieldSelect – How an app responds when the user clicks or taps a field. Isso se aplica somente aos campos especificados como SelectableFields.This applies only to the fields specified as SelectableFields.

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

  • FormMode.View – permite aos usuários exibir, mas não editar ou adicionar um registro.FormMode.View – Allows users to view but not edit or add a record.
  • FormMode.Edit – permite aos usuários editar um registro.FormMode.Edit – Allows users to edit a record.
  • FormMode.New – permite aos usuários adicionar um registro.FormMode.New – Allows users to add a record.

OnSuccess – como um aplicativo responderá quando uma operação de dados tiver sido bem-sucedida.OnSuccess – How an app responds when a data operation has been successful.

OnFailure - como um aplicativo responderá quando uma operação de dados não tiver sido bem-sucedida.OnFailure - How an app responds when a data operation has been unsuccessful.

Unsaved – determina se um registro editado por um usuário tem alterações não salvas.Unsaved – Determines whether a record that a user is editing has unsaved changes.

Você pode usar essas funções compartilhadas com o controle Formulário de entidade ou com o controle Editar formulário.You can use these shared functions with either the Entity form control or the Edit form control. Essas funções só poderão ser usadas com o controle Formulário de entidade quando sua propriedade Pattern estiver 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 controle 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 controle 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 controle Formulário de entidade como FormMode.New.NewForm - Sets the Mode property of an Entity form control to FormMode.New.

SubmitForm – salva as alterações quando um usuário edita um registro em um controle 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 salvas quando um usuário edita um registro em um controle Formulário de entidade.ResetForm - Abandons unsaved changes when a user edits a record in an Entity form control.

Agora que você tem uma visã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.

Observação

Se você não tiver acesso a um banco de dados do Common Data Service, crie um antes de começar a seguir estas etapas.If you don’t have access to a Common Data Service database, create one before you start to follow these steps.

Exibir uma lista de registrosDisplay a list of records

Os próximos cinco procedimentos fornecem um exemplo simples e completo de como usar os controles 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 mostre uma lista das ordens de venda.In this procedure, add a form that shows a list of sales orders.

  1. Crie um aplicativo de tablet em branco.Create a blank tablet app.

  2. Renomeie a primeira tela SalesOrderListScreen.Rename the first screen SalesOrderListScreen.

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

    Um controle Formulário de entidade é adicionado à tela.An Entity form control is added to the screen.

  4. Renomeie o controle Formulário de entidade SalesOrderListForm e redimensione-o para que ele ocupe toda a tela.Rename the Entity form control SalesOrderListForm, and resize it to cover the entire screen.
  5. No painel à direita, clique ou toque no ícone de banco de dados ao lado do texto Nenhuma fonte de dados selecionada e clique ou toque em Adicionar uma fonte 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 conexões, clique ou toque na conexão do banco 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 Conectar.In the list of entities, click or tap Sales order, and then click or tap Connect.

    Uma fonte de dados para a entidade Ordem de venda é criada, e a propriedade DataSource de SalesOrderListForm é definida para essa fonte 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 controle Formulário de entidade mostra uma lista de ordens de venda.The Entity form control shows a list of sales orders. Usando o controle Formulário de entidade, você rapidamente exibiu uma lista sem precisar criá-la manualmente.By using the Entity form control, you quickly displayed a list form without having to manually build it.

    Como você não definiu a propriedade Pattern para o controle Formulário de entidade, o padrão List será usado.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 em DefaultList da entidade Ordem de venda é usado para exibir 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 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) Exibir o grupo de campos DefaultList da entidade Ordem de venda:(Optional) View the DefaultList field group of the Sales order entity:

    1. Entre no site do powerapps.com, clique ou toque em Common Data Service, no painel de navegação à esquerda, e 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, na guia Grupos de campos e 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 da ordem de venda correspondem aos exibidos aqui.The fields in the sales order list match those listed here.

      No Common Data Service, você pode modificar grupos de campos de entidades personalizadas (mas não de entidades padrão) para mudar os campos exibidos nos formulários correspondentes que o controle Formulário de entidade mostra.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. E o melhor: quaisquer alterações feitas no grupo de campos serão automaticamente refletidas em todos os aplicativos que usam um controle Formulário de entidade para exibir 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.

Exibir os detalhes de um registroDisplay the details of a record

Vamos adicionar outro controle Formulário de entidade para exibir os detalhes da ordem de venda selecionada na lista que você 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 SalesOrderListForm para ocupar uma metade da tela e adicione um segundo controle Formulário de entidade para ocupar a outra metade da tela.Resize SalesOrderListForm to cover half the screen, and add a second Entity form control to cover the other half of the screen.

  2. Renomeie o segundo controle Formulário de entidade como SalesOrderDetailsForm e conecte-o à fonte de dados Ordem de vendas que você 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 de SalesOrderDetailsForm como FormPattern.Details.Set the Pattern property of SalesOrderDetailsForm to FormPattern.Details.

    SalesOrderDetailsForm usa o grupo de campos DefaultDetails da entidade Ordem de venda para exibir o formulário.SalesOrderDetailsForm uses the DefaultDetails field group of the Sales order entity to display the form. Assim como acontece com SalesOrderListForm, você pode mostrar detalhes do registro com rapidez sem precisar 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 de SalesOrderDetailsForm como SalesOrderListForm.Selected.Set the Item property of SalesOrderDetailsForm to SalesOrderListForm.Selected.

    SalesOrderDetailsForm exibirá os detalhes do registro no qual o usuário clicou ou tocou em SalesOrderListForm.SalesOrderDetailsForm will display the details of the record that the user clicks or taps in SalesOrderListForm.

  5. Visualize o aplicativo pressionando F5 e clique ou toque em uma 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 do pedido selecionado aparecem no lado direito.The details of the order that you selected appear on the right side.

Configurar um campo para navegar para outra telaConfigure a field to navigate to another screen

Agora, vamos adicionar mais telas ao nosso aplicativo e, em seguida, configurar campos em um controle Formulário de entidade para navegar para outra tela do aplicativo quando o usuário clicar ou tocar em um 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 uma segunda tela para o aplicativo e renomeie a tela SalesOrderDetailsScreen.Add a second screen to the app, and rename the screen SalesOrderDetailsScreen.
  2. Recorte a entidade SalesOrderDetailsForm, cole-a em SalesOrderDetailsScreen e redimensione o formulário para ocupar a maior parte da tela, 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 invertida ao lado do canto superior esquerdo de SalesOrderDetailsScreen.Add a back-arrow icon near the upper-left corner of SalesOrderDetailsScreen.
  4. Defina a propriedade OnSelect do ícone de seta para voltar como a função Back.Set the OnSelect property of the back-arrow icon to the Back function.

  5. Em SalesOrderListScreen, redimensione SalesOrderListForm para ocupar toda a tela.On the SalesOrderListScreen, resize the SalesOrderListForm to cover the entire screen.
  6. Clique ou toque em SalesOrderListForm para selecioná-la.Click or tap the SalesOrderListForm to select it.
  7. No painel direito, em Campos, defina SalesOrderId para navegar até SalesOrderDetailsScreen.In the right-hand pane, under Fields, set SalesOrderId to navigate to the SalesOrderDetailsScreen.

    O controle Formulário de entidade exibe os valores no campo SalesOrderId (a primeira coluna na lista) como links.The Entity form control displays the values in the SalesOrderId field (the first column in the list) as links.

  8. Visualize o aplicativo pressionando F5 e clique ou toque em um link 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 segunda tela abre e exibe os detalhes da ordem de venda que você especificou.The second screen opens and displays the details of the sales order that you specified.

    Para exibir os detalhes de uma ordem de venda diferente, clique ou toque na seta para voltar para retornar à lista e, em seguida, clique ou toque no link da ordem para exibir as informações que ela contém.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 de SalesOrderDetailsForm está definida como SalesOrderListForm.Selected para que SalesOrderDetailsForm mostre os detalhes do registro que o usuário selecionar em 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. Você também pode obter o contexto do registro selecionado usando a variável de contexto NavigationContext, que é criada automaticamente quando você usa o painel de personalização de formulário para definir um campo para o qual 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 de SalesOrderDetailsForm para NavigationContext.Set the Item property of SalesOrderDetailsForm to NavigationContext.

  2. Visualize o aplicativo pressionando F5 e clique ou toque em um link 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 aplicativo abre SalesOrderDetailsScreen e exibe os detalhes da ordem de vendas que você especificou.The app opens SalesOrderDetailsScreen and displays the details of the sales order that you specified.

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

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

Essa configuração foi definida automaticamente quando usamos o painel de personalização de formulário para que o campo SalesOrderId navegasse para SalesOrderDetailsScreen.This was set up automatically when we used the form-customization pane to make the SalesOrderId field navigate to the SalesOrderDetailsScreen. Portanto, os valores no campo SalesOrderId aparecem como links.Therefore, the values in the SalesOrderId field appear as links.

A propriedade OnFieldSelect de SalesOrderListForm está configurada com uma função If, que determina se o usuário clicou ou tocou 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 estiver avaliada como verdadeira, SalesOrderDetailsScreen é aberta com a variável de contexto NavigationContext que usamos anteriormente.If the function is evaluated as true, the SalesOrderDetailsScreen opens with the context variable named NavigationContext that we used earlier.

Tudo isso foi configurado automaticamente quando usamos o painel de personalização de formulário para que o campo SalesOrderId navegasse para SalesOrderDetailsScreen.All this was also set up automatically when we used the form-customization pane to make the SalesOrderId field navigate to the SalesOrderDetailsScreen.

Portanto, quando o usuário clica ou toca em um campo de ID de ordem de venda, a função If é avaliada como verdadeira, e a função Navigate é chamada com o contexto correspondente, abrindo a tela 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.

Observação

Quando você usa o painel de personalização de formulário, NavigationContext é inteligentemente determinada para você.When you use the form-customization pane, the NavigationContext is intelligently determined for you. Quando o usuário clica ou toca em SalesOrderId, NavigationContext é definida como SalesOrderListForm.Selected, conforme mostrado pela fórmula anterior.When the user clicks or taps SalesOrderId, NavigationContext is set to SalesOrderListForm.Selected, as the earlier formula shows. Se tivéssemos especificado o campo Account para a navegação, NavigationContext seria definida como SalesOrderListForm.Selected.Account, garantindo que o contexto correto seja transmitido.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 acessar esse contexto, você precisa conectar um controle Formulário de entidade à entidade Account 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 salvar um registroEdit and save a record

Por fim, veremos como editar e salvar um registro em um controle Formulário de entidade.Finally let’s look at how we can edit and save a record in an Entity form control.

  1. Em SalesOrderDetailsScreen, adicione um ícone Editar e, em seguida, defina sua propriedade OnSelect com a seguinte 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 seleção ao lado do ícone Editar e defina a propriedade OnSelect do ícone de marca de seleção com a seguinte 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. Pressione F5 para visualizar o aplicativo, clique ou toque em um link de ID da ordem de venda para exibir os detalhes de uma ordem de venda e clique ou toque no ícone Editar.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.

    A propriedade Mode do controle Formulário de entidade é definida como FormMode.Edit para que você possa editar o registro.The Mode of the Entity form control is set to FormMode.Edit so that you can edit the record.

  4. Atualize Status da ordem para Fatura.Update the Order status to Invoice.

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

    Para ajudá-lo a escolher o Vendedor, o controle Formulário de entidade automaticamente renderiza 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 exibir essa pesquisa, o controle usa o grupo de campos DefaultLookup da entidade Worker 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 Worker é usada porque o campo Vendedor é do tipo Worker.The Worker entity is used because the Sales person field is of type Worker.

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

Esta etapa conclui este artigo sobre como usar o controle Formulário de entidade em seus aplicativos.This step concludes this article on how to use the Entity form control in your apps. Esperamos que as informações fornecidas aqui tenham sido úteis para você começar a usar o controle Formulário de entidade.We hope that you find the information covered here useful to get started using the Entity form control. Estamos ansiosos para ouvir sua opinião sobre o controle Formulário de entidade e como ajudamos você a rapidamente adicionar formulários avançados aos seus aplicativos.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.