Controles Editar formulário e Exibir de no PowerAppsEdit form and Display form controls in PowerApps

Exiba, edite e crie um registro em uma fonte de dados.Display, edit, and create a record in a data source.

DescriçãoDescription

Se você adicionar um controle Exibir formulário, o usuário poderá exibir todos os campos de um registro ou apenas os campos que você especificar.If you add a Display form control, the user can display all fields of a record or only the fields that you specify. Se você adicionar um controle Editar formulário, o usuário pode editar esses campos, criar um registro e salvar essas alterações em uma fonte de dados.If you add an Edit form control, the user can edit those fields, create a record, and save those changes to a data source.

Exemplo de formulário e controles de exibição de formulário

Se você adicionar um controle Galeria, será possível configurá-lo para exibir uma tabela em uma fonte de dados e, em seguida, configurar um formulário para exibir qualquer registro que o usuário selecionar na galeria.If you add a Gallery control, you can configure it to show a table in a data source and then configure a form to show whichever record the user selects in the gallery. Você também pode adicionar um ou mais controles Button que o usuário pode selecionar para salvar edições, cancelar edições e criar um registro.You can also add one or more Button controls that the user can select to save edits, cancel edits, and create a record. Ao usar controles juntos, você pode criar uma solução completa.By using controls together, you can create a complete solution.

Seleção de registrosRecord selection

Para qualquer tipo de formulário, defina sua propriedade DataSource como uma tabela de registros e defina a propriedade Item do formulário para exibir um registro específico nessa tabela.For either type of form, you set its DataSource property to a table of records, and you set the form's Item property to show a specific record in that table. Por exemplo, você pode definir a propriedade Item de um formulário como a propriedade SelectedItem de um controle Galeria.For example, you can set the Item property of a form to the SelectedItem property of a Gallery control. Quando o usuário seleciona um registro na galeria, o mesmo registro aparecerá no formulário, exceto se o formulário puder exibir mais campos.When the user selects a record in the gallery, the same record appears in the form, except that the form can show more fields. Se o usuário retornar para a galeria e selecionar um registro diferente, a propriedade SelectedItem da galeria será alterada.If the user returns to the gallery and selects a different record, the SelectedItem property of the gallery changes. Essa alteração atualiza a propriedade Item do formulário, que então mostra o registro recém-selecionado.This change updates the Item property of the form, which then shows the newly selected record.

Cada controle de formulário contém um ou mais controles de Cartão.Each form control contains one or more Card controls. Ao definir a propriedade DataField de um cartão, especifique qual campo o cartão mostra e outros detalhes.By setting the DataField property of a card, you specify which field that card shows and other details.

Criar um registroCreate a record

Quando um controle Editar formulário estiver no modo Editar, o usuário pode atualizar o registro especificado na propriedade Item do formulário.When an Edit form control is in Edit mode, the user can update the record that's specified in the form's Item property. Se inspecionada, a propriedade Modo retornará para Editar.If inspected, the Mode property returns Edit.

No entanto, quando um controle Editar formulário estiver no modo Novo, a propriedade Item será ignorada.When an Edit form control is in New mode, however, the Item property is ignored. O formulário não exibe um registro existente. em vez disso, os valores em cada campo correspondem aos valores de padrão da fonte de dados com a qual você configurou o formulário.The form doesn't show an existing record; instead, the values in each field match the default values of the data source with which you configured the form. A função NewForm faz com que um formulário mude para esse modo.The NewForm function causes a form to switch to this mode.

Por exemplo, é possível definir a propriedade de Texto de um botão para exibir Novo e sua propriedade OnSelect como uma fórmula que inclua a função NewForm.For example, you can set the Text property of a button to show New and its OnSelect property to a formula that includes the NewForm function. Se o usuário selecionar esse botão, o formulário mudará para o modo Novo para que o usuário possa criar um registro começando com valores conhecidos.If the user selects that button, the form switches to New mode so that the user can create a record starting with known values.

Um formulário voltará para o modo Editar se a função ResetForm for executada ou a função SubmitForm for executada com êxito.A form switches back to Edit mode if either the ResetForm function runs or the SubmitForm function runs successfully.

  • É possível definir a propriedade de Texto de um botão para exibir Cancelar e sua propriedade OnSelect como uma fórmula que inclua a função ResetForm.You can set the Text property of a button to show Cancel and its OnSelect property to a formula that includes the ResetForm function. Se o usuário seleciona esse botão, todas as alterações em andamento são descartadas e os valores no formulário, mais uma vez, correspondem aos valores de padrão da fonte de dados.If the user selects that button, any changes in progress are discarded, and the values in the form, once again, match the default values of the data source.
  • É possível definir a propriedade de Texto de um botão para exibir Salvar alterações e sua propriedade OnSelect como uma fórmula que inclua a função SubmitForm.You can set the Text property of a button to show Save changes and its OnSelect property to a formula that includes the SubmitForm function. Se o usuário selecionar esse botão e a fonte de dados for atualizada, os valores no formulário serão redefinidos para os valores padrão da fonte de dados.If the user selects that button and the data source is updated, the values in the form are reset to the default values of the data source.

Salvar alteraçõesSave changes

Se você criar um botão Salvar alterações conforme descrito na seção anterior, o usuário poderá criar ou atualizar um registro e, em seguida, selecionar esse botão para salvar essas alterações na fonte de dados.If you create a Save changes button as the previous section describes, the user can create or update a record and then select that button to save those changes to the data source. Em vez disso, você pode configurar um controle de Imagem ou algum outro controle para executar a mesma tarefa, desde que configure esse controle com a função SubmitForm.You could, instead, configure an Image control or some other control to perform the same task, as long as you configure that control with the SubmitForm function. Em qualquer caso, as propriedades Erro, ErrorKind, OnSuccess e OnFailure fornecem comentários sobre o resultado.In any case, the Error, ErrorKind, OnSuccess, and OnFailure properties provide feedback on the outcome.

Quando a função SubmitForm é executada, ela primeiro valida os dados que o usuário deseja enviar.When the SubmitForm function runs, it first validates the data that user wants to submit. Se um campo obrigatório não contiver um valor ou se outro valor não estiver em conformidade com alguma outra restrição, as propriedades ErrorKind serão definidas e a fórmula OnFailure será executada.If a required field doesn't contain a value or another value doesn't conform to some other constraint, the ErrorKind properties are set, and the OnFailure formula runs. Você pode configurar o botão Salvar alterações ou outro controle para que o usuário possa selecionar somente se os dados forem válidos (ou seja, se a propriedade Válido do formulário for true).You can configure the Save changes button or other control so that the user can select it only if the data is valid (that is, if the Valid property of the form is true). Observe que o usuário deve não apenas corrigir o problema, mas também selecionar o botão Salvar alterações novamente (ou descartar as alterações, selecionando um botão Cancelar, conforme descrito anteriormente) para redefinir as propriedades Erro e ErrorKind.Note that the user must not only correct the problem but also select the Save changes button again (or discard the changes by selecting a Cancel button, as described earlier) to reset the Error and ErrorKind properties.

Se os dados passarem na validação, SubmitForm os enviará para a fonte de dados, o que poderá levar algum tempo dependendo da latência de rede.If the data passes validation, SubmitForm sends it to the data source, which can take some time depending on network latency.

  • Se o envio for bem-sucedido, a propriedade Erro ficará limpa, a propriedade ErrorKind será definida como ErrorKind.None e a fórmula OnSuccess será executada.If the submission succeeds, the Error property is cleared, the ErrorKind property is set to ErrorKind.None, and the OnSuccess formula runs. Se o usuário criar um registro (ou seja, se o formulário estava anteriormente no modo Novo), o formulário será alternado para o modo Editar para que o usuário possa editar o registro recém-criado ou um diferente.If the user created a record (that is, if the form was previously in New mode), the form is switched to Edit mode so that the user can edit the newly created record or a different one.
  • Se o envio falhar, a propriedade Erro conterá uma mensagem de erro amigável da fonte de dados explicando o problema.If the submission fails, the Error property contains a user-friendly error message from the data source, explaining the problem. A propriedade ErrorKind está definida corretamente, dependendo do problema, e a fórmula OnFailure é executada.The ErrorKind property is set appropriately, depending on the issue, and the OnFailure formula runs.

Algumas fontes de dados podem detectar quando duas pessoas tentam atualizar o mesmo registro ao mesmo tempo. Neste caso, ErrorKind é definido como ErrorKind.Conflict e a solução é atualizar a fonte de dados com as alterações de outros usuários e reaplicar a alteração feita pelo usuário.Some data sources can detect when two people try to update the same record at the same time In this case, ErrorKind is set to ErrorKind.Conflict, and the remedy is to refresh the data source with the other user's changes and reapply the change made by this user.

Dica: se você oferecer um botão Cancelar no formulário para que o usuário possa abandonar as alterações em andamento, adicione a função ResetForm à propriedade OnSelect do botão mesmo que a propriedade também contenha uma função Navegar para alterar telas.Tip: If you offer a Cancel button on your form so that the user can abandon changes in progress, add the ResetForm function to the button's OnSelect property even that property also contains a Navigate function to change screens. Caso contrário, o formulário manterá as alterações do usuário.Otherwise, the form will retain the user's changes.

LayoutLayout

Por padrão, os cartões são colocados em uma única coluna em aplicativos de telefone e três colunas em aplicativos de tablet.By default, cards are placed in a single column for phone apps and three columns for tablet apps. É possível especificar quantas colunas há em um formulário e se cartões devem se ajustar a elas conforme o formulário é configurado.You can specify how many columns a form has and whether cards should snap to them as you configure the form. Essas configurações não são expostas como propriedades, pois são usadas apenas para definir as propriedades X, Y e Width dos cartões.These settings aren't exposed as properties because they're used only to set the X, Y, and Width properties of the cards.

Para obter mais informações, consulte Entender o layout de formulário de dados.For more information, see Understand data form layout.

Propriedades-chaveKey properties

DataSource – a fonte de dados que contém o registro que o usuário mostrará, editará ou criará.DataSource – The data source that contains the record that the user will show, edit, or create.

  • Se você não definir essa propriedade, o usuário não poderá exibir, editar nem criar um registro e nenhum metadado adicional ou validação serão fornecidos.If you don't set this property, the user can't show, edit, or create a record, and no additional metadata or validation is provided.

DefaultMode – o modo inicial do controle de formulário.DefaultMode - The initial mode of the form control. Consulte a descrição do Modo abaixo para os valores aceitáveis e seus significados.See the description of Mode below for the acceptable values and their meanings.

DisplayMode – o modo de uso para controles e cartões de dados dentro do controle de formulário.DisplayMode - The mode to use for data cards and controls within the form control.

Derivado e com base na propriedade Modo e não pode ser definido de forma independente:Derived from the Mode property based and cannot be set independently:

ModoMode DisplayModeDisplayMode DescriçãoDescription
FormMode.EditFormMode.Edit DisplayMode.EditDisplayMode.Edit Controles e cartões de dados são editáveis e prontos para aceitar alterações em um registro.Data cards and controls are editable, ready to accept changes to a record.
FormMode.NewFormMode.New DisplayMode.EditDisplayMode.Edit Controles e cartões de dados são editáveis e prontos para aceitar um novo registro.Data cards and controls are editable, ready to accept a new record.
FormMode.ViewFormMode.View DisplayMode.ViewDisplayMode.View Controles e cartões de dados não são editáveis e são otimizados para exibição.Data cards and controls are not editable and optimized for viewing.

Erro – uma mensagem de erro amigável a ser exibida para esse formulário quando a função SubmitForm falhar.Error – A user friendly error message to display for this form when the SubmitForm function fails.

  • Essa propriedade se aplica apenas ao controle Editar formulário.This property applies only to the Edit form control.
  • Esta propriedade é alterada somente quando a função SubmitForm, EditForm, ou ResetForm é executada.This property changes only when the SubmitForm, EditForm, or ResetForm function runs.
  • Se nenhum erro ocorrer, essa propriedade ficará em branco e ErrorKind será definido como ErrorKind.None.If no error occurs, this property is blank, and ErrorKind is set to ErrorKind.None.
  • Quando possível, a mensagem de erro retornada estará no idioma do usuário.When possible, the error message returned will be in the user's language. Algumas mensagens de erro são fornecidas diretamente da fonte de dados e podem não estar no idioma do usuário.Some error messages come from the data source directly and may not be in the user's language.

ErrorKind – se ocorrer um erro quando SubmitForm for executado, será o tipo de erro que ocorreu.ErrorKind – If an error occurs when SubmitForm runs, the kind of error that occurred.

  • Aplica-se apenas a um controle Editar formulário.Applies only to an Edit form control.
  • Essa propriedade tem a mesmo enumeração que a função Erros.This property has the same enumeration as the Errors function. Um controle Editar formulário pode retornar estes valores:An Edit form control can return these values:
ErrorKindErrorKind DescriçãoDescription
ErrorKind.ConflictErrorKind.Conflict Outro usuário alterou o mesmo registro, resultando em um conflito de alteração.Another user changed the same record, resulting in a change conflict. Execute a função Renovar para recarregar o registro e tente a alteração novamente.Execute the Refresh function to reload the record, and try the change again.
ErrorKind.NoneErrorKind.None O erro é de um tipo desconhecido.The error is of an unknown kind.
ErrorKind.SyncErrorKind.Sync A fonte de dados relatou um erro.The data source reported an error. Verifique a propriedade Erro para obter mais informações.Check the Error property for more information.
ErrorKind.ValidationErrorKind.Validation Foi detectado um problema de validação geral.A general validation issue was detected.

Item – o registro em DataSource que o usuário mostrará ou editará.Item – The record in the DataSource that the user will show or edit.

LastSubmit – o último registro enviado com êxito, incluindo todos os campos gerados pelo servidor.LastSubmit – The last successfully submitted record, including any server generated fields.

  • Essa propriedade se aplica apenas ao controle Editar formulário.This property applies only to the Edit form control.
  • Se a fonte de dados gerar ou calcular automaticamente todos os campos, como um campo de ID com um número exclusivo, a propriedade LastSubmit terá esse novo valor após SubmitForm ser executado com êxito.If the data source automatically generates or calculates any fields, such as an ID field with a unique number, the LastSubmit property will have this new value after SubmitForm successfully runs.
  • O valor dessa propriedade está disponível na fórmula OnSuccess.The value of this property is available in the OnSuccess formula.

Modo – o controle está no modo Editar ou Novo.Mode – The control is in Edit or New mode.

ModoMode DescriçãoDescription
FormMode.EditFormMode.Edit O usuário pode editar um registro usando o formulário.The user can edit a record by using the form. Os valores nas fichas do formulário são preenchidos previamente com o registro existente, para que o usuário altere.The values in the form's cards are pre-populated with the existing record, for the user to change. Se a função SubmitForm for executada com êxito, um registro existente será modificado.If the SubmitForm function runs successfully, an existing record is modified.
FormMode.NewFormMode.New O usuário pode criar um registro usando o formulário.The user can create a record by using the form. Os valores nos controles do formulário são preenchidos previamente com os padrões de um registro da fonte de dados.The values in the form's controls are pre-popoulated with the defaults for a record of the data source. Se a função SubmitForm for executada com êxito, um registro será criado.If the SubmitForm function runs successfully, an record is created.
FormMode.ViewFormMode.View O usuário pode exibir um registro usando o formulário.The user can view a record by using the form. Os valores nos controles do formulário são preenchidos previamente com os padrões de um registro da fonte de dados.The values in the form's controls are pre-popoulated with the defaults for a record of the data source.

O formulário alterna do modo Novo para o modo Editar quando qualquer uma dessas alterações ocorrer:The form switches from New mode to Edit mode when any of these changes occurs:

  • O formulário é enviado com êxito e um registro é criado.The form is successfully submitted, and a record is created. Se a galeria for definida para mover automaticamente a seleção para este novo registro, o formulário estará no modo Editar para o registro criado para que o usuário possa fazer alterações adicionais.If the gallery is set to automatically move selection to this new record, the form will be in Edit mode for the created record so that the user can make additional changes.
  • A função EditForm é executada.The EditForm function runs.
  • A função ResetForm é executada.The ResetForm function runs. Por exemplo, o usuário pode selecionar um botão Cancelar que foi configurado com essa função.For example, the user might select a Cancel button that's been configured with this function.

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

  • Essa propriedade se aplica apenas ao controle Editar formulário.This property applies only to the Edit form control.

OnReset – como um aplicativo responde quando um controle Editar formulário é redefinido.OnReset – How an app responds when an Edit form control is reset.

  • Essa propriedade se aplica apenas ao controle Editar formulário.This property applies only to the Edit form control.

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.

  • Essa propriedade se aplica apenas ao controle Editar formulário.This property applies only to the Edit form control.

Não Salvo – True se o controle Editar formulário contiver alterações do usuário que não foram salvas.Unsaved – True if the Edit form control contains user changes that have not been saved.

  • Essa propriedade se aplica apenas ao controle Editar formulário.This property applies only to the Edit form control.
  • Use esta propriedade para avisar os usuários antes que percam as alterações não salvas.Use this property to warn the user before they lose any unsaved changes. Para impedir que o usuário selecione um registro diferente em um controle de Galeria antes de salvar as alterações no registro atual, defina a propriedade Desabilitado da galeria como Form.Unsaved e, da mesma forma, desabilite as operações de atualização.To prevent the user from selecting a different record in a Gallery control before saving changes to the current record, set the gallery's Disabled property to Form.Unsaved and, likewise, disable refresh operations.

Atualizações – os valores a se fazer o write-back na fonte de dados para um registro carregado em um controle de formulário.Updates – The values to write back to the data source for a record loaded in a form control.

  • Essa propriedade se aplica apenas ao controle Editar formulário.This property applies only to the Edit form control.
  • Use essa propriedade para extrair os valores do campo de fichas de dentro do controle.Use this property to extract the field values from the cards within the control. Você pode usar esses valores para atualizar manualmente a fonte de dados com uma chamada de função Patch ou outro método exposto por uma conexão.You can then use these values to manually update the data source with a Patch function call or another method exposed by a connection. Você não precisa usar essa propriedade se estiver usando a função SubmitForm.You do not need to use this property if you are using the SubmitForm function.
  • Essa propriedade retorna um registro de valores.This property returns a record of values. Por exemplo, se o controle de formulário contivesse controles de cartão para os campos Nome e Quantidade e os valores das propriedades Atualizar para esses cartões retornassem "Widget" e 10, respectivamente, então, a propriedade Atualizações do controle de formulário retornaria { Name: "Widget", Quantity: 10}.For example, if the form control contains card controls for Name and Quantity fields, and the values of the Update properties for those cards return "Widget" and 10 respectively, then the Updates property for the form control would return { Name: "Widget", Quantity: 10 }.

Válido – especifica se um controle Cartão ou Editar formulário contém entradas válidas, prontas para serem enviadas para a fonte de dados.Valid – Whether a Card or Edit form control contains valid entries, ready to be submitted to the data source.

  • Essa propriedade se aplica apenas ao controle Editar formulário.This property applies only to the Edit form control.
  • No controle de Formulário, a propriedade Válido agrega as propriedades Válido de todos os controle de Cartão no formulário.A Form control's Valid property aggregates the Valid properties of all the Card controls in the form. A propriedade Válido do formulário será true somente se os dados em todas as fichas desse formulário forem válidos; caso contrário, a propriedade Válido do formulário será false.A form's Valid property is true only if the data in all cards in that form is valid; otherwise, the form's Valid property is false.
  • Para habilitar um botão para salvar as alterações somente quando os dados em um formulário forem válidos, mas ainda não tiverem sido enviados, defina o Habilitado do botão como esta fórmula:To enable a button to save changes only when the data in a form is valid but hasn't yet been submitted, set the button's Enabled to this formula:

    SubmitButton.Enabled = IsBlank( Form.Error ) || Form.ValidSubmitButton.Enabled = IsBlank( Form.Error ) || Form.Valid

Propriedades adicionaisAdditional properties

BorderColor – a cor da borda do controle.BorderColor – The color of a control's border.

BorderStyle – se a borda do controle é Solid, Dashed, Dotted ou None.BorderStyle – Whether a control's border is Solid, Dashed, Dotted, or None.

BorderThickness – a espessura da borda do controle.BorderThickness – The thickness of a control's border.

Fill – a cor da tela de fundo de um controle.Fill – The background color of a control.

Height – a distância entre a parte superior do controle e as bordas inferiores.Height – The distance between a control's top and bottom edges.

Visible – se um controle é exibido ou está oculto.Visible – Whether a control appears or is hidden.

Width – a distância entre das bordas esquerda e direita de um controle.Width – The distance between a control's left and right edges.

X – a distância entre a borda esquerda de um controle e a borda esquerda de seu contêiner pai (tela, se não houver contêiner pai).X – The distance between the left edge of a control and the left edge of its parent container (screen if no parent container).

Y – a distância entre a borda superior de um controle e a borda superior de seu contêiner pai (tela, se não houver contêiner pai).Y – The distance between the top edge of a control and the top edge of the parent container (screen if no parent container).

Mais informaçõesMore information

Para obter uma visão abrangente do funcionamento formulários, consulte Entender formulários de dados.For a comprehensive overview of how forms work, see Understand data forms.