Funções EditForm, NewForm, SubmitForm, ResetForm e ViewForm nos PowerAppsEditForm, NewForm, SubmitForm, ResetForm, and ViewForm functions in PowerApps

Ver, editar, ou criar um item, guardar o conteúdo e os controlos num controlo Editar formulário.View, edit, or create an item, save the contents, and reset the controls in an Edit form control.

Descrição geralOverview

Estas funções alteram o estado do controlo Editar formulário.These functions change the state of the Edit form control. O controlo de formulário pode ser um destes modos:The form control can be in one of these modes:

ModoMode DescriçãoDescription
FormMode.EditFormMode.Edit O formulário é preenchido com um registo existente e o utilizador pode modificar os valores dos campos.The form is populated with an existing record and the user can modify the values of the fields. Depois de concluído, o utilizador pode guardar as alterações no registo.Once complete, the user can save the changes to the record.
FormMode.NewFormMode.New O formulário é preenchido com os valores predefinidos e o utilizador pode modificar os valores dos campos.The form is populates with default values and the user can modify the values of the fields. Depois de concluído, o utilizador pode adicionar o registo à origem de dados.Once complete, the user can add the record to the data source.
FormMode.ViewFormMode.View O formulário é preenchido com um registo existente, mas o utilizador pode modificar os valores dos campos.The form is populated with an existing record but the user cannot modify the values of the fields.

DescriçãoDescription

Estas funções são, muitas vezes, invocadas a partir da fórmula OnSelect de um controlo Botão ou Imagem para que o utilizador possa guardar as edições, abandonar edições ou criar um registo.These functions are often invoked from the OnSelect formula of a Button or Image control so that the user can save edits, abandon edits, or create a record. Pode utilizar controlos e estas funções e controlos em conjunto para criar uma solução completa.You can use controls and these functions together to create a complete solution.

Estas funções não devolvem valores.These functions return no values.

SubmitFormSubmitForm

Utilize a função SubmitForm na propriedade OnSelect de um controlo Botão para guardar quaisquer alterações num controlo de Formulário na origem de dados.Use the SubmitForm function in the OnSelect property of a Button control to save any changes in a Form control to the data source.

Antes de submeter quaisquer alterações, esta função verifica a existência de problemas de validação com qualquer campo assinalado como necessário ou que tenha um ou mais restrições no respetivo valor.Before submitting any changes, this function checks for validation issues with any field that's marked as required or that has one or more constraints on its value. Este comportamento corresponde ao da função Validar.This behavior matches that of the Validate function.

SubmitForm também verifica a propriedade Válido do Formulário, que é uma agregação de todas as propriedades Válido dos controlos Cartão que contém o controlo de Formulário.SubmitForm also checks the Valid property of the Form, which is an aggregation of all the Valid properties of the Card controls that the Form control contains. Se ocorrer um problema, os dados não são submetidos e as propriedades Erro e ErrorKind do controlo de Formulário são definidos em conformidade.If a problem occurs, the data isn't submitted, and the Error and ErrorKind properties of the Form control are set accordingly.

Se a validação for aprovada, SubmitForm submete a alteração à origem de dados.If validation passes, SubmitForm submits the change to the data source.

  • Se for bem-sucedido, o comportamento OnSuccess do Formulário é executado e as propriedades Erro e ErrorKind são eliminadas.If successful, the Form's OnSuccess behavior runs, and the Error and ErrorKind properties are cleared. Se o formulário estava no modo FormMode.New, é devolvido para o modo FormMode.Edit.If the form was in FormMode.New mode, it is returned to FormMode.Edit mode.
  • Se não for bem-sucedido, o comportamento OnFailure do Formulário é executado e as propriedades Erro e ErrorKind são definidas em conformidade.If unsuccessful, the Form's OnFailure behavior runs, and the Error and ErrorKind properties are set accordingly. O modo do formulário permanece inalterado.The mode of the form is unchanged.

EditFormEditForm

A função EditForm altera o modo de controlo de Formulário para FormMode.Edit.The EditForm function changes the Form control's mode to FormMode.Edit. Neste modo, o conteúdo da propriedade Item do controlo de Formulário é utilizado para preencher o formulário.In this mode, the contents of the Form control's Item property are used to populate the form. Se a função SubmitForm é executada quando o formulário está neste modo, um registo é alterado e não é criado.If the SubmitForm function runs when the form is in this mode, a record is changed, not created. FormMode.Edit é a predefinição para o controlo de Formulário.FormMode.Edit is the default for the Form control.

NewFormNewForm

A função NewForm altera o modo de controlo de Formulário para FormMode.New.The NewForm function changes the Form control's mode to FormMode.New. Neste modo, o conteúdo da propriedade Item do controlo de Formulário é ignorado e os valores predefinidos da propriedade DataSource do Formulário preenchem o formulário.In this mode, the contents of the Form control's Item property are ignored, and the default values of the Form's DataSource property populate the form. Se a função SubmitForm é executada quando o formulário está neste modo, um registo é criado e não é alterado.If the SubmitForm function runs when the form is in this mode, a record is created, not changed.

ResetFormResetForm

A função ResetForm repõe o conteúdo de um formulário para os valores iniciais, antes do utilizador efetuar quaisquer alterações.The ResetForm function resets the contents of a form to their initial values, before the user made any changes. Se o formulário estiver no modo FormMode.New, o formulário é reposto para o modo FormMode.Edit.If the form is in FormMode.New mode, the form is reset to FormMode.Edit mode. O comportamento OnReset do controlo de formulário também é executado.The OnReset behavior of the form control also runs. Pode também repor os controlos individuais com a função Repor, mas apenas a partir do formulário.You can also reset individual controls with the Reset function but only from within the form.

ViewFormViewForm

A função NewForm altera o modo de controlo de Formulário para FormMode.View.The ViewForm function changes the Form control's mode to FormMode.View. Neste modo, o conteúdo da propriedade Item do controlo de Formulário é utilizado para preencher o formulário.In this mode, the contents of the Form control's Item property are used to populate the form. As funções SubmitForm e RestForm não têm qualquer efeito neste modo.The SubmitForm and RestForm functions have no effect when in this mode.

Propriedade DisplayModeDisplayMode Poperty

O modo atual pode ser lido através da propriedade Modo.The current mode can be read through the Mode property. O modo também determina o valor da propriedade DisplayMode, que pode ser utilizada por cartões de dados e controlos dentro do controlo de formulário.The mode also determines the value of the DisplayMode property which can be used by data cards and controls within the form control. Muitas vezes, a propriedade DisplayMode do cartão de dados é definida para Parent.DisplayMode (com uma referência ao formulário) como a propriedade DisplayMode do controlo (com referência ao cartão de dados):Often, the data card's DisplayMode property will be set to Parent.DisplayMode (refernceing the form) as will the control's DisplayMode property (referncing the data card):

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

SintaxeSyntax

SubmitForm( FormName )SubmitForm( FormName )

  • FormName - Necessário.FormName - Required. Controlo de formulário para enviar à origem de dados.Form control to submit to the data source.

EditForm( FormName )EditForm( FormName )

  • FormName - Necessário.FormName - Required. Formulário de controlo para mudar para o modo FormMode.Edit.Form control to switch to FormMode.Edit mode.

NewForm( FormName )NewForm( FormName )

  • FormName - Necessário.FormName - Required. Formulário de controlo para mudar para o modo FormMode.New.Form control to switch to FormMode.New mode.

ResetForm( FormName )ResetForm( FormName )

  • FormName - Necessário.FormName - Required. Controlo de formulário para repor os valores iniciais.Form control to reset to initial values. Também muda o formulário do modo FormMode.New para o modo FormMode.Edit.Also switches the form from FormMode.New mode to FormMode.Edit mode.

ViewForm( FormName )ViewForm( FormName )

  • FormName - Necessário.FormName - Required. Formulário de controlo para mudar para o modo FormMode.View.Form control to switch to FormMode.View mode.

ExemplosExamples

Consulte Compreender os formulários de dados para obter exemplos de conclusão.See Understand data forms for complete examples.

  1. Adicione um controlo de botão, defina a respetiva propriedade Texto para mostrar Guardar e guardar a respetiva propriedade OnSelect para esta fórmula:Add a Button control, set its Text property to show Save, and set its OnSelect property to this formula:

    SubmitForm( EditForm )SubmitForm( EditForm )

  2. Defina a propriedade OnFailure de um controlo de Formulário para vazio e a respetiva propriedade OnSuccess para esta fórmula:Set the OnFailure property of a Form control to blank and its OnSuccess property to this formula:

    Anterior()Back()

  3. Atribua um controlo Etiqueta ErrorText e defina a respetiva propriedade Texto para esta fórmula:Name a Label control ErrorText, and set its Text property to this formula:

    EditForm.ErrorEditForm.Error

    Quando o utilizador seleciona o botão Guardar, quaisquer alterações no controlo de Formulário são enviadas para a origem de dados subjacente.When the user selects the Save button, any changes in the Form control are submitted to the underlying data source.

    • Se o envio for bem-sucedido, quaisquer alterações são guardadas ou, se o controlo de Formulário estiver no modo Novo, é criado um registo.If the submission succeeds, any changes are saved or, if the Form control is in New mode, a record is created. ErrorText é em branco e é apresentado o ecrã anterior.ErrorText is blank and the previous screen reappears.
    • Se o envio não for bem-sucedido, ErrorText mostra uma mensagem de erro amigável de utilizador e o ecrã atual permanece visível para que o utilizador possa corrigir o problema e tentar novamente.If the submission fails, ErrorText shows a user-friendly error message, and the current screen remains visible so that the user can correct the problem and try again.
  4. Adicione um controlo de Botão, defina a respetiva propriedade Texto para mostrar Cancelar e defina a respetiva propriedade OnSelect para esta fórmula:Add a Button control, set its Text property to show Cancel, and set its OnSelect property to this formula:

    ResetForm( EditForm ); Anterior()ResetForm( EditForm ); Back()

    Quando o utilizador seleciona o botão Cancelar, os valores no controlo de Formulário são repostos para o que eram antes do utilizador começar a editá-los, o ecrã anterior é apresentado de novo e o controlo de Formulário volta para o modo Editar, se estava no modo Novo.When the user selects the Cancel button, the values in the Form control are reset to what they were before the user started to edit it, the previous screen reappears, and the Form control is returned to Edit mode if it was in New mode.

  5. Adicione um controlo de Botão, defina a respetiva propriedade Texto para mostrar Novo e defina a respetiva propriedade OnSelect para esta fórmula:Add a Button control, set its Text property to show New, and set its OnSelect property to this formula:

    NewForm( EditForm ); Navegar ( EditScreen, Nenhum )NewForm( EditForm ); Navigate( EditScreen, None )

    Quando o utilizador seleciona o botão Novo, o controlo de Formulário muda para o modo Novo, os valores predefinidos da origem de dados do controlo de Formulário preenchem esse controlo e é apresentado o ecrã que contém o controlo de Formulário.When the user selects the New button, the Form control switches to New mode, the default values for the Form control's data source populate that control, and the screen that contains the Form control appears. Quando a função SubmitForm é executada, um registo é criado em vez de atualizado.When the SubmitForm function runs, a record is created instead of updated.