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

Exiba, edite ou crie um item, salve o conteúdo e redefina os controles em um controle Editar formulário.View, edit, or create an item, save the contents, and reset the controls in an Edit form control.

Visão geralOverview

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

ModoMode DescriçãoDescription
FormMode.EditFormMode.Edit O formulário é populado com um registro existente e o usuário pode modificar os valores dos campos.The form is populated with an existing record and the user can modify the values of the fields. Uma vez concluído, o usuário pode salvar as alterações no registro.Once complete, the user can save the changes to the record.
FormMode.NewFormMode.New O formulário é populado com valores padrão e o usuário pode modificar os valores dos campos.The form is populates with default values and the user can modify the values of the fields. Uma vez concluído, o usuário pode adicionar o registro à fonte de dados.Once complete, the user can add the record to the data source.
FormMode.ViewFormMode.View O formulário é populado com um registro existente, mas o usuário não 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

Geralmente essas funções são invocadas com a fórmula OnSelect de um controle botão ou imagem, para que os usuários possam salvar edições, abandonar edições ou criar um registro.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. Você pode usar controles e essas funções juntas para criar uma solução completa.You can use controls and these functions together to create a complete solution.

Essas funções não retornam valores.These functions return no values.

SubmitFormSubmitForm

Use a função SubmitForm na propriedade OnSelect de um controle de botão para salvar quaisquer alterações feitas em um controle Formulário da fonte 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 enviar qualquer alteração, essa função verifica problemas de validação em todos os campos marcados como obrigatórios ou que têm uma ou mais restrições em seus valores.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. Essa comportamento corresponde ao da função Validate.This behavior matches that of the Validate function.

A função SubmitForm também verifica a propriedade Valid do formulário, que é uma agregação de todas as propriedades Valid dos controles de cartão que o controle Formulário inclui.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 um problema ocorrer, os dados não serão enviados, e as propriedades Error e ErrorKind do controle Formulário serão definidas de acordo.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, a função SubmitForm enviará a alteração para a fonte de dados.If validation passes, SubmitForm submits the change to the data source.

  • Se a operação for bem-sucedida, o comportamento OnSuccess do formulário será executado, e as propriedades Error e ErrorKind serão apagadas.If successful, the Form's OnSuccess behavior runs, and the Error and ErrorKind properties are cleared. Se o formulário estiver no modo FormMode.New, ele será retornado no modo FormMode.Edit.If the form was in FormMode.New mode, it is returned to FormMode.Edit mode.
  • Se a operação não for bem-sucedida, o comportamento OnFailure do formulário será executado, e as propriedades Error e ErrorKind serão definidas de acordo.If unsuccessful, the Form's OnFailure behavior runs, and the Error and ErrorKind properties are set accordingly. O modo do formulário não é alterado.The mode of the form is unchanged.

EditFormEditForm

A função EditForm altera o modo do controle Formulário para FormMode.Edit.The EditForm function changes the Form control's mode to FormMode.Edit. Nesse modo, o conteúdo da propriedade Item do controle do formulário é usado 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 for executada quando o formulário estiver nesse modo, um registro será alterado, não criado.If the SubmitForm function runs when the form is in this mode, a record is changed, not created. FormMode.Edit é o padrão para o controle Formulário.FormMode.Edit is the default for the Form control.

NewFormNewForm

A função NewForm altera o modo do controle Formulário para FormMode.New.The NewForm function changes the Form control's mode to FormMode.New. Nesse modo, o conteúdo da propriedade Item do controle Formulário é ignorado, e os valores padrão 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 for executada quando o formulário estiver nesse modo, um registro será criado, 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 redefine o conteúdo de um formulário para seus valores iniciais, presentes antes de o usuário fazer 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, ele será redefinido 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 controle Formulário também é executado.The OnReset behavior of the form control also runs. Você também pode redefinir os controles individuais com a função Redefinir, mas apenas de dentro do formulário.You can also reset individual controls with the Reset function but only from within the form.

ViewFormViewForm

A função ViewForm altera o modo do controle Formulário para FormMode.View.The ViewForm function changes the Form control's mode to FormMode.View. Nesse modo, o conteúdo da propriedade Item do controle do formulário é usado 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 nenhum efeito quando nesse modo.The SubmitForm and RestForm functions have no effect when in this mode.

Propriedade DisplayModeDisplayMode Poperty

O modo atual pode ser lido por meio 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 usada por cartões de dados e controles dentro do controle 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. Geralmente, a propriedade DisplayMode do cartão de dados será definida como Parent.DisplayMode (referenciando o formato), assim como ocorrerá com a propriedade DisplayMode do controle (referenciando o 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 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.

SintaxeSyntax

SubmitForm( FormName )SubmitForm( FormName )

  • FormName - Obrigatório.FormName - Required. O controle Formulário a ser enviado para a fonte de dados.Form control to submit to the data source.

EditForm( FormName )EditForm( FormName )

  • FormName - Obrigatório.FormName - Required. O controle Formulário para alternar para o modo FormMode.Edit.Form control to switch to FormMode.Edit mode.

NewForm( FormName )NewForm( FormName )

  • FormName - Obrigatório.FormName - Required. O controle Formulário para alternar para o modo FormMode.New.Form control to switch to FormMode.New mode.

ResetForm( FormName )ResetForm( FormName )

  • FormName - Obrigatório.FormName - Required. O controle Formulário para redefinir o formulário para seus 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 - Obrigatório.FormName - Required. O controle Formulário para mudar para o modo FormMode.View.Form control to switch to FormMode.View mode.

ExemplosExamples

Consulte Entender os formulários de dados para obter exemplos completos.See Understand data forms for complete examples.

  1. Adicione um controle de botão, defina sua propriedade Text para mostrar Salvar e defina sua propriedade OnSelect com 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 controle Formulário para ficar em branco e sua propriedade OnSuccess com esta fórmula:Set the OnFailure property of a Form control to blank and its OnSuccess property to this formula:

    Back()Back()

  3. Nomeie um controle Rótulo ErrorText e defina sua propriedade Text com esta fórmula:Name a Label control ErrorText, and set its Text property to this formula:

    EditForm.ErrorEditForm.Error

    Quando o usuário seleciona o botão Salvar, qualquer alteração no controle Formulário será enviada à fonte 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, todas as alterações serão salvas ou, se o controle Formulário estiver no modo New, um registro será criado.If the submission succeeds, any changes are saved or, if the Form control is in New mode, a record is created. ErrorText está definida como blank, e a tela anterior é re-exibida.ErrorText is blank and the previous screen reappears.
    • Se o envio falhar, ErrorText mostra uma mensagem de erro amigável e a tela atual permanece visível para que o usuário possa corrigir o problema e tente 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 controle Botão, defina sua propriedade Text para mostrar Cancelar e defina sua propriedade OnSelect com a seguinte fórmula:Add a Button control, set its Text property to show Cancel, and set its OnSelect property to this formula:

    ResetForm( EditForm1 ); Back()ResetForm( EditForm ); Back()

    Quando o usuário selecionar o botão Cancelar, os valores no controle Formulário serão redefinidos para os valores definidos antes de o usuário iniciar a edição, a tela anterior será exibida novamente e o controle Formulário voltará para o modo Edit, caso ele esteja no modo New.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 controle de botão, defina sua propriedade Text para mostrar Novo e defina sua propriedade OnSelect com esta fórmula:Add a Button control, set its Text property to show New, and set its OnSelect property to this formula:

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

    Quando o usuário selecionar o botão New, o controle Formulário mudará para o modo New, os valores padrão da fonte de dados do controle Formulário preencherão esse controle, e a tela que apresenta o controle Formulário será exibida.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 registro é criado, em vez de atualizado.When the SubmitForm function runs, a record is created instead of updated.