Editar controles de formulário e Exibir formulário no Power Apps

Exiba, edite e crie um registro em uma fonte de dados.

Description

Se você adicionar um controle de formulário de exibição , o usuário poderá exibir todos os campos de um registro ou somente os campos especificados. Se você adicionar um controle Editar formulário , o usuário poderá editar esses campos, criar um registro e salvar essas alterações em uma fonte de dados.

Se você adicionar um controle Gallery , poderá configurá-lo para mostrar uma tabela em uma fonte de dados e, em seguida, configurar um formulário para mostrar o registro selecionado pelo usuário na galeria. 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. Usando controles juntos, você pode criar uma solução completa.

Limitações

O controle de formulário tem estas limitações:

• Não é possível copiar e colar formulários em cartões de dados. Isso é para evitar que certas combinações de controles sejam criadas e coloquem em risco a estabilidade e o desempenho do aplicativo.

Seleção de registros

Para qualquer tipo de formulário, defina sua propriedade DataSource como uma tabela de registros e defina a propriedade Item do formulário para mostrar um registro específico nessa tabela. Por exemplo, você pode definir a propriedade Item de um formulário como a propriedade SelectedItem de um controle Gallery . Quando o usuário seleciona um registro na galeria, o mesmo registro aparece no formulário, exceto que o formulário pode mostrar mais campos. Se o usuário retornar à galeria e selecionar um registro diferente, a propriedade SelectedItem da galeria será alterada. Essa alteração atualiza a propriedade Item do formulário, que mostra o registro recém-selecionado.

Você também pode definir a propriedade Item de um formulário usando um controle suspenso , como Mostrar, editar ou adicionar um registro descreve, ou uma função como Pesquisa ou Primeiro. Por exemplo, você pode definir a propriedade Item como uma destas fórmulas para mostrar a entrada Fabrikam na tabela Contas no Microsoft Dataverse:

First(Accounts)

Lookup(Accounts, "Fabrikam" in name)

Cada controle de formulário contém um ou mais controles Card . Ao definir a propriedade DataField de um cartão, você especifica qual campo esse cartão mostra e outros detalhes.

Criar um registo

Quando um controle Editar formulário está no modo de Edição , o usuário pode atualizar o registro especificado na propriedade Item do formulário. Se inspecionada, a propriedade Mode retornará Edit.

No entanto, quando um controle Edit form está no modo New , a propriedade Item é ignorada. O formulário não mostra um registro existente; em vez disso, os valores em cada campo correspondem aos valores padrão da fonte de dados com a qual você configurou o formulário. A função NewForm faz com que um formulário alterne para esse modo.

Por exemplo, você pode definir a propriedade Text de um button para mostrar New e sua propriedade OnSelect como uma fórmula que inclua a função NewForm . Se o usuário selecionar esse botão, o formulário alternará para o modo Novo para que o usuário possa criar um registro começando com valores conhecidos.

Um formulário volta para o modo de edição se a função ResetForm for executada ou a função SubmitForm for executada com êxito.

• Você pode definir a propriedade Text de um button para mostrar Cancel e sua propriedade OnSelect como uma fórmula que inclua a função ResetForm . Se o usuário selecionar esse botão, todas as alterações em andamento serão descartadas e os valores no formulário, mais uma vez, corresponderão aos valores padrão da fonte de dados.
• Você pode definir a propriedade Text de um botão para mostrar as alterações Save e sua propriedade OnSelect como uma fórmula que inclua a função SubmitForm . 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.

Guardar alterações

Se você criar um botão Salvar alterações , como 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. Em vez disso, você pode configurar um controle Image ou algum outro controle para executar a mesma tarefa, desde que configure esse controle com a função SubmitForm . Em qualquer caso, as propriedades Error, ErrorKind, OnSuccess e OnFailure fornecem comentários sobre o resultado.

Quando a função SubmitForm é executada, ela primeiro valida os dados que o usuário deseja enviar. Se um campo obrigatório não contiver um valor ou 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. Você pode configurar o botão Salvar alterações ou outro controle para que o usuário possa selecioná-lo somente se os dados forem válidos (ou seja, se a propriedade Valid do formulário for 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 Error e ErrorKind .

Se os dados passarem na validação, o SubmitForm os enviará para a fonte de dados, o que pode levar algum tempo, dependendo da latência da rede.

• Se o envio for bem-sucedido, a propriedade Error será limpa, a propriedade ErrorKind será definida como ErrorKind.None e a fórmula OnSuccess será executada. Se o usuário criou um registro (ou seja, se o formulário estava anteriormente no modo Novo ), o formulário é alternado para o modo Editar para que o usuário possa editar o registro recém-criado ou um diferente.
• Se o envio falhar, a propriedade Error conterá uma mensagem de erro amigável da fonte de dados, explicando o problema. A propriedade ErrorKind é definida apropriadamente, dependendo do problema, e a fórmula OnFailure é executada.

Algumas fontes de dados podem detetar quando duas pessoas tentam atualizar o mesmo registro ao mesmo tempo Nesse caso, ErrorKind é definido como ErrorKind.Conflict, e a solução é atualizar a fonte de dados com as alterações do outro usuário e reaplicar a alteração feita por esse usuário.

Esquema

Por padrão, os cartões são colocados em uma única coluna para aplicativos de telefone e três colunas para aplicativos de tablet. Você pode especificar quantas colunas um formulário tem e se os cartões devem ser ajustados a elas ao configurar o formulário. Essas configurações não são expostas como propriedades porque são usadas apenas para definir as propriedades X, Y e Width dos cartões.

Para obter mais informações, consulte Compreender o layout do formulário de dados.

Propriedades chave

DataSource – A fonte de dados que contém o registro que o usuário mostrará, editará ou criará.

• Se você não definir essa propriedade, o usuário não poderá mostrar, editar ou criar um registro e nenhum metadados ou validação adicionais serão fornecidos.

DefaultMode - O modo inicial do controle de formulário. Veja a descrição do Modo abaixo para os valores aceitáveis e seus significados.

DisplayMode - O modo a ser usado para cartões de dados e controles dentro do controle de formulário.

Derivado da propriedade Mode com base e não pode ser definido independentemente:

Erro – Uma mensagem de erro amigável para exibir para este formulário quando a função SubmitForm falhar.

• Essa propriedade se aplica somente ao controle Edit form .
• Essa propriedade muda somente quando a função SubmitForm, EditForm ou ResetForm é executada.
• Se nenhum erro ocorrer, essa propriedade estará em branco e ErrorKind será definida como ErrorKind.None.
• Quando possível, a mensagem de erro retornada estará no idioma do usuário. Algumas mensagens de erro vêm diretamente da fonte de dados e podem não estar no idioma do usuário.

ErrorKind – Se ocorrer um erro quando SubmitForm é executado, o tipo de erro que ocorreu.

• Aplica-se somente a um controle Editar formulário .
• Esta propriedade tem a mesma enumeração que a função Errors . Um controle Editar formulário pode retornar estes valores:

Item – O registro na DataSource que o usuário mostrará ou editará.

LastSubmit – O último registro enviado com sucesso, incluindo quaisquer campos gerados pelo servidor.

• Essa propriedade se aplica somente ao controle Edit form .
• Se a fonte de dados gerar ou calcular automaticamente quaisquer campos, como um campo ID com um número exclusivo, a propriedade LastSubmit terá esse novo valor depois que SubmitForm for executado com êxito.
• O valor dessa propriedade está disponível na fórmula OnSuccess .

Modo – O controle está no modo Editar ou Novo .

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

• O formulário é enviado com êxito e um registro é criado. Se a galeria estiver definida para mover automaticamente a seleção para esse novo registro, o formulário estará no modo de edição do registro criado para que o usuário possa fazer alterações adicionais.
• A função EditForm é executada.
• A função ResetForm é executada. Por exemplo, o usuário pode selecionar um botão Cancelar que tenha sido configurado com essa função.

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

• Essa propriedade se aplica somente ao controle Edit form .

OnReset – Ações a serem executadas quando um controle Edit form é redefinido.

• Essa propriedade se aplica somente ao controle Edit form .

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

• Essa propriedade se aplica somente ao controle Edit form .

Não salvo – True se o controle Editar formulário contiver alterações de usuário que não foram salvas.

• Essa propriedade se aplica somente ao controle Edit form .
• Use essa propriedade para avisar o usuário antes que ele perca as alterações não salvas. Para impedir que o usuário selecione um registro diferente em um controle Gallery antes de salvar as alterações no registro 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 a serem gravados de volta na fonte de dados de um registro carregado em um controle de formulário.

• Essa propriedade se aplica somente ao controle Edit form .
• Use essa propriedade para extrair os valores de campo dos cartões dentro do controle. Em seguida, 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. Você não precisa usar essa propriedade se estiver usando a função SubmitForm .
• Essa propriedade retorna um registro de valores. Por exemplo, se o controle de formulário contiver controles de cartão para os campos Nome e Quantidade , e os valores das propriedades Update para esses cartões retornarem "Widget" e 10, respectivamente, a propriedade Updates para o controle de formulário retornará { Name: "Widget", Quantity: 10 }.

Válido – Se um controle de formulário Card ou Edit contém entradas válidas, prontas para serem enviadas à fonte de dados.

• Essa propriedade se aplica somente ao controle Edit form .

• A propriedadeValid de um controle Form agrega as propriedades Valid de todos os controles Card no formulário. A propriedade Valid de um formulário só será verdadeira se os dados em todos os cartões desse formulário forem válidos; caso contrário, a propriedade Valid do formulário será false.

• Para permitir que um botão salve as alterações somente quando os dados em um formulário forem válidos, mas ainda não tiverem sido enviados, defina a propriedade DisplayMode do botão para esta fórmula:

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

Propriedades adicionais

BorderColor – A cor da borda de um controle.

BorderStyle – Se a borda de um controle é Sólida, Tracejada, Pontilhada ou Nenhuma.

BorderThickness – A espessura da borda de um controle.

Preenchimento – A cor de fundo de um controlo.

Altura – A distância entre as bordas superior e inferior de um controle.

Visível – Se um controle aparece ou está oculto.

Largura – A distância entre as bordas esquerda e direita de um controle.

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 visão geral abrangente de como os formulários funcionam, consulte Compreender os formulários de dados.
• Consulte a referência da fórmula Power Fx para EditForm.

Diretrizes de acessibilidade

Suporte a leitor de ecrã

• Considere adicionar um título ao formulário usando um Rótulo.