Controlos Editar formulário e Apresentar formulário no Power Apps

Apresente, edite e crie um registo numa origem de dados.

Descrição

Se adicionar um controlo Apresentar formulário, o utilizador pode apresentar todos os campos de um registo ou apenas os campos que especificar. Se adicionar um controlo Editar formulário, o utilizador pode editar esses campos, criar um registo e guardar essas alterações numa origem de dados.

Se adicionar um controlo Galeria, pode configurá-lo para mostrar uma tabela numa origem de dados e, em seguida, configurar um formulário para mostrar o registo que o utilizador selecionar na galeria. Também pode adicionar um ou mais controlos de Botão que o utilizador pode selecionar para guardar as edições, cancelar as edições e criar um registo. Ao utilizar os controlos em conjunto, pode criar uma solução completa.

Seleção de registo

Para cada tipo de formulário, define a respetiva propriedade DataSource como uma tabela de registos e define a propriedade Item do formulário para mostrar um registo específico nessa tabela. Por exemplo, pode definir a propriedade Item de um formulário como a propriedade SelectedItem de um controlo Galeria. Quando o utilizador seleciona um registo na galeria, o mesmo registo é apresentado no formulário, embora, neste caso, o formulário possa mostrar mais campos. Se o utilizador voltar à galeria e selecionar um registo diferente, a propriedade SelectedItem da galeria é alterada. Esta alteração atualiza a propriedade Item do formulário, a qual, em seguida, mostra o registo recentemente selecionado.

Também pode definir a propriedade Item de um formulário através de um controlo Lista pendente, como Mostrar, editar ou adicionar um registo descreve ou uma função como Lookup ou First. Por exemplo, pode definir a propriedade Item para qualquer uma destas fórmulas para mostrar a entrada da tabela Contas em Microsoft Dataverse:

First(Accounts)

Lookup(Accounts, "Fabrikam" in name)

Cada controlo de formulário contém um ou mais controlos de Cartão. Ao definir a propriedade DataField de um cartão, especifica o campo que esse cartão mostra e outros detalhes.

Criar um registo

Quando um controlo Editar formulário está no modo Editar, o utilizador pode atualizar o registo especificado na propriedade Item do formulário. Se for inspecionada, a propriedade Mode devolve Editar.

No entanto, quando um controlo Editar formulário está no modo Novo, a propriedade Item é ignorada. O formulário não mostra um registo existente; em vez disso, os valores em cada campo correspondem aos valores predefinidos da origem de dados com a qual configurou o formulário. A função NewForm faz com que um formulário mude para este modo.

Por exemplo, pode definir a propriedade Text de um botão para mostrar Novo e a respetiva propriedade OnSelect como uma fórmula que inclua a função NewForm. Se o utilizador selecionar esse botão, o formulário muda para o modo Novo, para que o utilizador possa criar um registo começando com valores conhecidos.

Um formulário muda novamente para o modo Editar se a função ResetForm for executada ou a função SubmitForm for executada com êxito.

• Pode definir a propriedade Text de um botão para mostrar Cancelar e a respetiva propriedade OnSelect como uma fórmula que inclua a função ResetForm. Se o utilizador selecionar esse botão, todas as alterações em curso são eliminadas e os valores no formulário, mais uma vez, correspondem aos valores predefinidos da origem de dados.
• Pode definir a propriedade Text de um botão para mostrar Guardar alterações e a respetiva propriedade OnSelect como uma fórmula que inclua a função SubmitForm. Se o utilizador selecionar esse botão e a origem de dados for atualizada, os valores no formulário são repostos para os valores predefinidos da origem de dados.

Guardar alterações

Se criar um botão Guardar alterações tal como a secção anterior descreve, o utilizador pode criar ou atualizar um registo e, em seguida, selecionar esse botão para guardar essas alterações na origem de dados. Em alternativa, pode configurar um controlo Imagem ou outro controlo para executar a mesma tarefa, desde que configure esse controlo com a função SubmitForm. Em qualquer um dos casos, as propriedades Error, ErrorKind, OnSuccess e OnFailure dão feedback sobre o resultado.

Quando a função SubmitForm é executada, primeiro valida os dados que o utilizador pretende submeter. Se um campo obrigatório não contiver um valor ou outro valor não estiver em conformidade com outra restrição, as propriedades ErrorKind são definidas e a fórmula OnFailure é executada. Pode configurar o botão Guardar alterações ou outro controlo, para que o utilizador possa o possa selecionar apenas se os dados forem inválidos (ou seja, se a propriedade Valid do formulário for verdadeiro). Tenha em atenção que o utilizador não tem apenas de corrigir o problema, como também de selecionar o botão Guardar alterações novamente (ou eliminar as alterações ao selecionar um botão Cancelar, conforme descrito anteriormente) para repor as propriedades Error e ErrorKind.

Se os dados passarem na validação, SubmitForm envia-os para a origem de dados, o que pode demorar algum tempo consoante a latência de rede.

• Se a submissão for bem sucedida, a propriedade Error é desmarcada, a propriedade ErrorKind é definida como ErrorKind.None e a fórmula OnSuccess é executada. Se o utilizador tiver criado um registo (ou seja, se o formulário estava anteriormente no modo Novo), o formulário é mudado para o modo Editar para que o utilizador possa editar o registo recentemente criado ou um registo diferente.
• Se a submissão falhar, a propriedade Error contém uma mensagem de erro amigável de utilizador da origem de dados, a explicar o problema. A propriedade ErrorKind é definida adequadamente, consoante o problema, e a fórmula OnFailure é executada.

Algumas origens de dados conseguem detetar quando duas pessoas tentam atualizar o mesmo registo ao mesmo tempo. Neste caso, ErrorKind é definida como ErrorKind.Conflict, e a solução é atualizar a origem de dados com as alterações do outro utilizador e voltar a aplicar a alteração feita por este utilizador.

Gorjeta

Se oferecer um botão Cancelar no formulário, para que o utilizador possa abandonar as alterações em curso, adicione a função ResetForm à propriedade OnSelect do botão, mesmo que a propriedade também contenha uma função Navigate para mudar de ecrã. Caso contrário, o formulário irá manter as alterações do utilizador.

Esquema

Por predefinição, os cartões são colocados numa única coluna para aplicações de telemóvel e em três colunas para aplicações de tablet. Pode especificar o número de colunas que um formulário tem e se os cartões se devem ajustar às mesmas à medida que o formulário configura. Estas definições não são expostas como propriedades porque são utilizadas apenas para definir as propriedades X, Y e Width dos cartões.

Para obter mais informações, veja Compreender o esquema dos formulários de dados.

Propriedades principais

DataSource – A origem de dados que contém o registo que o utilizador irá mostrar, editar ou criar.

• Se não definir esta propriedade, o utilizador não poderá mostrar, editar ou criar um registo, e não são fornecidos metadados ou validações adicionais.

DefaultMode – O modo inicial do controlo de formulário. Veja a descrição de Mode abaixo para obter os valores aceitáveis e os respetivos significados.

DisplayMode – O modo a utilizar para cartões de dados e controlos no controlo de formulário.

Deriva da propriedade Mode e não pode ser definida de forma independente:

Modo	DisplayMode	Descrição
FormMode.Edit	DisplayMode.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.
FormMode.New	DisplayMode.Edit	Os cartões de dados e controlos são editáveis e estão prontos para aceitar um novo registo.
FormMode.View	DisplayMode.View	Os cartões de dados e controlos não são editáveis e otimizados para visualização.

Error – uma mensagem de erro amigável de utilizador a apresentar para este formulário quando a função SubmitForm falhar.

• Esta propriedade é aplicável apenas ao controlo Editar formulário.
• Esta propriedade é alterada apenas quando a função SubmitForm, EditForm ou ResetForm é executada.
• Se não ocorrer nenhum erro, esta propriedade é blank e ErrorKind está definida como ErrorKind.None.
• Sempre que possível, a mensagem de erro devolvida estará no idioma do utilizador. Algumas mensagens de erro vêm diretamente da origem de dados e podem não estar no idioma do utilizador.

ErrorKind – se ocorrer um erro quando SubmitForm for executada, corresponde ao tipo de erro que ocorreu.

• É aplicável apenas a um controlo Editar formulário.
• Esta propriedade tem a mesma enumeração que a função Errors. Um controlo Editar formulário pode devolver estes valores:

ErrorKind	Descrição
ErrorKind.Conflict	Outro utilizador alterou o mesmo registo, resultando num conflito de alteração. Execute a função Refresh para recarregar o registo e tente novamente a alteração.
ErrorKind.None	O erro é de um tipo desconhecido.
ErrorKind.Sync	A origem de dados comunicou um erro. Verifique a propriedade Error para obter mais informações.
ErrorKind.Validation	Foi detetado um problema de validação geral.

Item – o registo na DataSource que o utilizador irá mostrar ou editar.

LastSubmit – O último registo submetido com êxito, incluindo quaisquer campos gerados pelo servidor.

• Esta propriedade é aplicável apenas ao controlo Editar formulário.
• Se a origem de dados gerar ou calcular automaticamente campos, tal como um campo ID com um número exclusivo, a propriedade LastSubmit terá este novo valor depois de SubmitForm ser executada com êxito.
• O valor desta propriedade está disponível na fórmula OnSuccess.

Mode – o controlo está no modo Editar ou Novo.

Modo	Descrição
FormMode.Edit	O utilizador pode editar um registo utilizando o formulário. Os valores nos cartões do formulário são pré-preenchidos com o registo existente, para o utilizador alterar. Se a função SubmitForm for executada com êxito, um registo existente é modificado.
FormMode.New	O utilizador pode criar um registo utilizando o formulário. Os valores nos controlos do formulário são pré-preenchidos com as predefinições para um registo da origem de dados. Se a função SubmitForm for executada com êxito, é criado um registo.
FormMode.View	O utilizador pode ver um registo utilizando o formulário. Os valores nos controlos do formulário são pré-preenchidos com as predefinições para um registo da origem de dados.

O formulário passa do modo Novo para o modo Editar quando qualquer uma destas alterações ocorrer:

• O formulário é submetido com êxito e é criado um registo. Se a galeria estiver definida para mover automaticamente a seleção para este novo registo, o formulário estará no modo Editar para o registo criado, para que o utilizador possa fazer alterações adicionais.
• A função EditForm é executada.
• A função ResetForm é executada. Por exemplo, o utilizador poderá selecionar um botão Cancelar que tenha sido configurado com esta função.

OnFailure – Ações a executar quando uma operação de dados não foi bem sucedida.

• Esta propriedade é aplicável apenas ao controlo Editar formulário.

OnReset – Ações a executar quando um controlo de Editar formulário é reiniciado.

• Esta propriedade é aplicável apenas ao controlo Editar formulário.

OnSuccess – Ações a executar quando uma operação de dados foi bem sucedida.

• Esta propriedade é aplicável apenas ao controlo Editar formulário.

Unsaved – verdadeiro se o controlo Editar formulário contiver alterações do utilizador que não tenham sido guardadas.

• Esta propriedade é aplicável apenas ao controlo Editar formulário.
• Utilize esta propriedade para avisar o utilizador antes de perder alterações não guardadas. Para evitar que o utilizador selecione um registo diferente num controlo Galeria antes de guardar as alterações ao registo atual, defina a propriedade Disabled da galeria como Form.Unsaved e, da mesma forma, desative as operações de atualização.

Updates – os valores para voltar a escrever na origem de dados para um registo carregado num controlo de formulário.

• Esta propriedade é aplicável apenas ao controlo Editar formulário.
• Utilize esta propriedade para extrair os valores dos campos dos cartões no controlo. Em seguida, pode utilizar estes valores para atualizar manualmente a origem de dados com uma chamada de função Patch ou outro método exposto através de uma ligação. Não é necessário utilizar esta propriedade se estiver a utilizar a função SubmitForm.
• Esta propriedade devolve um registo de valores. Por exemplo, se o controlo de formulário contiver controlos de cartão para os campos Name e Quantidade e os valores das propriedades Update para esses cartões devolverem as placas devolverem "Widget" e 10, respetivamente, a propriedade Updates para o controlo de formulário devolverá { Name: "Widget", Quantidade: }.

Valid – Se um controlo de Cartão ou Editar formulário contiver entradas válidas, prontas para serem submetidas para a origem de dados.

• Esta propriedade é aplicável apenas ao controlo Editar formulário.

• A propriedade Valid de um controlo Formulário agrega as propriedades Valid de todos os controlos de Cartão no formulário. A propriedade Valid de um formulário apenas é verdadeira se os dados em todos os cartões nesse formulário forem válidos; caso contrário, a propriedade Valid do formulário é falsa.

• Para ativar um botão para guardar as alterações apenas quando os dados num formulário são válidos, mas ainda não foram submetidos, defina a propriedade DisplayMode do botão para esta fórmula:

  SubmitButton.DisplayMode = If(IsBlank( Form.Error ) || Form.Valid, DisplayMode.Edit, DisplayMode.Disabled)

Propriedades adicionais

BorderColor – a cor do limite de um controlo.

BorderStyle – se o limite do controlo é Sólido, Tracejado, Com pontos ou Nenhum.

BorderThickness – a espessura do limite de um controlo.

Fill – a cor de fundo de um controlo.

Height – a distância entre as margens superiores e inferiores de um controlo.

Visible – se um controlo é apresentado ou está oculto.

Width – a distância entre as margens esquerda e direita de um controlo.

X – a distância entre o limite esquerdo de um controlo e o limite esquerdo do respetivo recipiente principal (do ecrã, se não existir um recipiente principal).

Y – a distância entre o limite superior de um controlo e o limite superior do recipiente principal (do ecrã, se não existir um recipiente principal).

Mais informações

• Para obter uma descrição geral completa do funcionamento dos formulários, veja Compreender os formulários de dados.
• Consulte, consulte a referência de fórmula do Power Fx para EditForm.

Diretrizes de acessibilidade

Suporte a leitor de ecrã

• Considere adicionar um cabeçalho ao formulário através de uma Etiqueta.

Nota

Pode indicar-nos as suas preferências no que se refere ao idioma da documentação? Responda a um breve inquérito. (tenha em atenção que o inquérito está em inglês)

O inquérito irá demorar cerca de sete minutos. Não são recolhidos dados pessoais (declaração de privacidade).