Controlos Editar formulário e Mostrar formulário em Power Apps

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

Descrição

Se adicionar um controlo Mostrar 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.

Controlos de exemplo de formulário e vista de formulário

Se adicionar um controlo Gallery, 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 Button 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 Gallery. 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 Pesquisa ou Primeiro. Por exemplo, pode definir a propriedade Item para qualquer uma destas fórmulas para mostrar a entrada da Fabrikam na entidade Contas no Microsoft Dataverse:

First(Accounts)

Lookup(Accounts, "Fabrikam" in name)

Cada controlo de formulário contém um ou mais controlos de Card. 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 Modo 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 Texto 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 Texto 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 Texto 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 Image 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 Erro, 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 Válido 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 Erro 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 Erro é 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 Erro 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.

Dica

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 Navegar 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 Largura 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 Modo 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 Modo 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.

Erro – 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 Atualizar 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 Erro 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.

Modo – 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 – como uma aplicação responde quando uma operação de dados não foi bem-sucedida.

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

OnReset – como uma aplicação responde quando um controlo Editar formulário é reposto.

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

OnSuccess – Como uma aplicação responde quando uma operação de dados foi bem-sucedida.

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

Não guardado – 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 Gallery 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.

Atualizações – 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 Nome e Quantidade e os valores das propriedades Update para esses cartões devolverem as placas devolverem "Widget" e 10, respetivamente, a propriedade Atualizações para o controlo de formulário devolverá { Nome: "Widget", Quantidade: }.

Válido – Se um controlo de Card 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 Válido de um controlo de Formulário agrega as propriedades Válido de todos os controlos de Card no formulário. A propriedade Válido 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 Válido 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.

Preenchimento – a cor de fundo de um controlo.

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

Visível – se um controlo é apresentado ou está oculto.

Largura – 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.

Diretrizes de acessibilidade

Suporte a leitor de ecrã

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