Objeto App no Power Apps

Fornece informações sobre a aplicação a ser atualmente executada e permite controlar o comportamento da mesma.

Descrição

Tal como um controlo, o objeto da Aplicação fornece propriedades que identificam qual o ecrã que está a ser apresentada e que pedem que o utilizador guarde alterações para que não sejam perdidas. Cada aplicação tem um objeto de Aplicação.

Pode escrever fórmulas para algumas propriedades do objeto de Aplicação. Na parte superior do painel Vista de árvore, selecione o objeto de Aplicação como faria com qualquer outro controlo ou ecrã. Veja e edite uma das propriedades do objeto selecionando-a na lista pendente à esquerda da barra de fórmulas.

Propriedade ActiveScreen

A propriedade ActiveScreen identifica o ecrã que está a ser mostrado.

Esta proprieda devolve um objeto de ecrã, que poderá utilizar para fazer referência a propriedades do ecrã ou comparar com outro ecrã para determinar que ecrã é apresentado. Também pode utilizar a expressão App.ActiveScreen.Name para obter o nome do ecrã que está a ser mostrado.

Utilize a função Back ou Navigate para alterar o ecrã que está a ser mostrado.

Propriedades ConfirmExit

Ninguém quer perder alterações não guardadas. Utilize as propriedades ConfirmExit e ConfirmExitMessage para avisar o utilizador antes de fecharem a sua aplicação.

Nota

• ConfirmExit não funciona em aplicações incorporadas no, por exemplo, Power BI e SharePoint.
• Atualmente, estas propriedades só podem referenciar controlos no primeiro ecrã se a funcionalidade de pré-visualização Carregamento atrasado estiver ativada (o que é predefinido para novas aplicações). Se forem efetuadas referências, o Power Apps Studio não mostra um erro, mas a aplicação publicada resultante não é aberta no Power Apps Mobile ou num browser. Estamos a trabalhar ativamente para levantar esta limitação. Entretanto, pode desativar Carregamento retardado em Definições > Funcionalidades futuras (em Pré-visualização).

ConfirmExit

ConfirmExit é uma propriedade Booleana que, quando true, abre uma caixa de diálogo de confirmação antes da aplicação ser fechada. Por predefinição, esta propriedade é false e não é apresentada qualquer caixa de diálogo.

Utilize esta propriedade para mostrar uma caixa de diálogo de confirmação, caso o utilizador tenha alterado as alterações, mas não as tenha guardado. Utilize uma fórmula que possa verificar variáveis e propriedades de controlo (por exemplo, a propriedade Unsaved do controlo Edit form).

A caixa de diálogo de confirmação é apresentada em qualquer situação na qual haja a possibilidade de perder dados, como nos seguintes exemplos:

• Executar a função Exit.
• Se a aplicação estiver a ser executada num browser:
  • Feche o browser ou o separador do browser no qual a aplicação está a ser executada.
  • Selecionar o botão Anterior do browser.
  • Executar a função Launch com um LaunchTarget de Self.
• Se a aplicação estiver em execução no Power Apps Mobile (iOS ou Android):
  • Passar o dedo para mudar para uma aplicação diferente no Power Apps Mobile.
  • Selecionar o botão Anterior num dispositivo Android.
  • Executar a função Launch para lançar outra aplicação de tela.

A aparência exata da caixa de diálogo de confirmação poderá variar de acordo com os dispositivos e versões do Power Apps.

A caixa de diálogo de confirmação não aparece no Power Apps Studio.

ConfirmExitMessage

Por predefinição, a caixa de diálogo de confirmação mostra uma mensagem genérica, tal como "Poderá ter alterações não guardadas." no idioma do utilizador.

Utilize ConfirmExitMessage para fornecer uma mensagem personalizada na caixa de diálogo de confirmação. Se esta propriedade estiver em branco, é utilizado o valor predefinido. As mensagens personalizadas são truncadas conforme necessário para se ajustarem na caixa de diálogo de confirmação, para manter a mensagem a algumas linhas no máximo.

Num browser, a caixa de diálogo de confirmação poderá ser apresentada com uma mensagem genérica a partir do browser.

Nota

O objeto da aplicação tem mais duas propriedades adicionais OnMessage e BackEnabled que são propriedades experimentais e irão desaparecer do objeto da aplicação no futuro. Recomendamos que não utilize estas propriedades no seu ambiente de produção.

Exemplo

1. Crie uma aplicação que contenha dois controlos de formulário, AccountForm e ContactForm.

2. Defina a propriedade ConfirmExit do objeto da Aplicação para esta expressão:

   AccountForm.Unsaved Or ContactForm.Unsaved
   

   Esta caixa de diálogo é apresentada se o utilizador alterar dados em qualquer um dos formulários e, em seguida, tentar fechar a aplicação sem guardar essas alterações.

   

3. Defina a propriedade ConfirmExitMessage do objeto da Aplicação para esta fórmula:

   If( AccountsForm.Unsaved,
       "Accounts form has unsaved changes.",
       "Contacts form has unsaved changes."
   )
   

   Esta caixa de diálogo é apresentada se o utilizador alterar dados no formulário de conta e, em seguida, tentar fechar a aplicação sem guardar essas alterações.

   

Propriedade OnError

Nota

• OnError faz parte de uma funcionalidade experimental e poderá estar sujeita a alterações. Mais informações: Compreender as funcionalidades experimentais, pré-visualização e preterido no Power Apps.
• O comportamento que este artigo descreve só está disponível quando a funcionalidade experimental de gestão de erros ao nível da fórmula em Definições > Funcionalidades futuras > Experimentais está ativada (desativada por predefinição).
• Os seu comentários são muito importantes para nós. Dê-nos a sua opinião nos fóruns da comunidade do Power Apps.

Utilize OnError para agir depois de um erro ter sido detetado. Fornece uma oportunidade global para intercetar uma faixa de erro antes de ser apresentada ao utilizador final. Também pode ser utilizada para registar um erro com a função Trace ou escrever numa base de dados ou serviço Web.

O resultado da avaliação de cada fórmula é verificado para detetar erros. Se houver um erro, OnError será avaliado com as mesmas variáveis de âmbito FirstError e AllErrors que estariam presentes se a fórmula completa tivesse sido moldada numa função IfError.

Se OnError estiver vazio, é apresentada uma faixa de erro predefinda com a FirstError.Message do erro. A definição de uma fórmula OnError substitui este comportamento, o que permite ao criador tratar o relatório de erros conforme achar adequado. O comportamento predefinido pode ser solicitado em OnError, relançando o erro com a função Error. Isto é útil se alguns erros devem ser filtrados ou tratados de um modo diferente, enquanto outros devem ser transmitidos.

OnError não pode substituir um erro nos cálculos da mesma forma que IfError. No momento em OnError que é invocado, o erro já ocorreu e já foi processado através de cálculos de fórmulas. *OnError* controla apenas o relatório de erros.

As fórmulas OnError são avaliadas em simultâneo e é possível que a avaliação das mesmas possa sobrepor-se ao processamento de outros erros. Por exemplo, se definir uma variável global para além de OnError e a ler posteriormente na mesma fórmula, o valor poderá ter sido alterado. Utilize a função With para criar um valor nomeado que seja local para a fórmula.

Embora cada erro seja processado individualmente por OnError, a faixa de erro predefinida poderá não aparecer para cada erro individualmente. Para evitar que sejam apresentadas demasiadas faixas de erro ao mesmo tempo, o mesmo erro não acionará uma nova faixa de erro se tiver sido apresentada recentemente.

Exemplo

Considere um controlo Label e Slider que são mutuamente dependentes através da fórmula:

Label1.Text = 1/Slider1.Value

A predefinição do slider é 50. Se o slider for movido para 0, Label1 não mostrará nenhum valor e é apresentada uma faixa de erro:

Vamos ver o que ocorreu em detalhe:

1. O utilizador moveu o slide para a esquerda e a propriedade Slide1.Value foi alterada para 0.
2. Label1.Text foi novamente avaliado automaticamente. Ocorreu uma divisão por zero, gerando um erro.
3. Não existe IfError nesta fórmula. O erro de divisão por zero é devolvido pela avaliação da fórmula.
4. Label1.Text não pode mostrar nada para este erro, pelo que mostra um estado em branco.
5. OnError é invocado. Visto que não existe nenhum processador, a faixa de erro padrão é mostrada com a informação do erro.

Se for necessário, também podemos modificar a fórmula para Label1.Text = IfError( 1/Slider1.Value, 0 ). Tal não iria resultar num erro ou faixa de erro. Não podemos alterar o valor de um erro a partir de OnError, uma vez que nesse momento o erro já ocorreu, é apenas uma questão de como será reportado.

Se adicionarmos um processador OnError, este não terá impacto antes do passo 5, mas poderá afetar o forma como o erro é reportado:

Trace( $"Error {FirstError.Message} in {FirstError.Source}" )

Com esta opção ativada, a partir da perspetiva do utilizador da aplicação, não ocorre nenhum erro. No entanto, o erro será adicionado ao rastreio da monitorização com a origem das informações de erro de FirstError:

Se também quiser que a mesma faixa de erro predefinida seja apresentada para além do rastreio, podemos relançar o erro com a função Error após a chamada Trace tal como se Trace não estivesse presente:

Trace( $"Error {FirstError.Message} in {FirstError.Source}" );
Error( FirstError )

Propriedade OnStart

Nota

A utilização da propriedade OnStart pode causar problemas de desempenho ao carregar uma aplicação. Estamos no processo de criar alternativas para as duas principais razões para usar dados de caching de propriedade—e criar variáveis globais. Já criámos uma alternativa para definir o primeiro ecrã a ser mostrado com Navigate. Dependendo do seu contexto, esta propriedade pode ser desativada por predefinição. Se não a vir e precisar de a utilizar, ative as definições Avançadas da aplicação para a ativar. A propriedade OnVisible de um ecrã também pode ser usada.

A propriedade OnStart é executada quando o utilizador inicia a aplicação. Esta propriedade é frequentemente usada para executar as seguintes tarefas:

• Obter e armazenar em cache dados em coleções utilizando a função Collect.
• Configure variáveis globais com a função Set.

Esta fórmula é avaliada antes de aparecer o primeiro ecrã. Não é carregado nenhum ecrã, pelo que não é possível definir variáveis de contexto com a função UpdateContext. No entanto, pode transmitir variáveis de contexto com a função Navigate.

Depois de alterar a propriedade OnStart, teste-a passando com o rato por cima do objeto Aplicação no painel Vista de árvore, selecionando reticências (...), e depois Executar OnStart. Ao contrário de quando a aplicação é carregada pela primeira vez, as coleções e variáveis existentes já estarão definidas. Para começar com coleções vazias, utilize a função ClearCollect em vez da função Collect.

Nota

• A utilização da função Navigate na propriedade OnStart foi retirada. As aplicações existentes continuarão a funcionar. Durante um tempo limitado, ainda a pode ativar nas definições da aplicação (disponível em Desativado). No entanto, a utilização de Navigate desta forma pode levar a atrasos no carregamento da aplicação, uma vez que obriga o sistema a concluir a avaliação do OnStart antes de exibir o primeiro ecrã. Utilize a propriedade StartScreen para calcular o primeiro ecrã apresentado.
• O interruptor Desativado será desligado nas aplicações criadas antes de março de 2021, onde adicionou Navigate ao OnStart entre março de 2021 e este momento. Quando editar essas aplicações Power Apps Studio, poderá ver um erro. Rode o interruptor Desativado acima mencionado para limpar este erro.

Propriedade StartScreen

Nota

A propriedade StartScreen não será apresentada na lista de propriedades quando a opção extinta Barra de fórmulas melhorada estiver ativada. Para desativar a Barra de fórmulas melhorada, vá para Definições > Próximas funcionalidades > Extinta > desative o interruptor Barra de fórmulas melhorada quando quiser utilizar a propriedade StartScreen.

A propriedade StartScreen determina qual o ecrã que será apresentado primeiro. É avaliado uma vez quando a aplicação é carregada e devolve o objeto do ecrã a ser exibido. Por predefinição, esta propriedade ficará vazia e o primeiro ecrã na vista Studio Tree é apresentado primeiro.

O StartScreen é uma propriedade do fluxo de dados que não pode conter funções de comportamento. Todas as funções de fluxo de dados estão disponíveis, em particular, utilizar estas funções e sinais para determinar qual o ecrã a mostrar primeiro:

• Função Param para ler parâmetros usados para iniciar a aplicação.
• Função User para ler informações sobre o utilizador atual.
• LookUp, Filter, CountRows, Max, e outras funções que se leem a partir de uma origem de dados.
• Qualquer API chama através de um conector, mas tenha cuidado para que volte rapidamente.
• Sinais como Ligação, Bússola e Aplicação.

Nota

Variáveis e coleções globais, incluindo as criadas no OnStart não estão disponíveis no StartScreen. Há alternativas declarativas para o fazer que estão a caminho. Para os seus comentários sobre esta restrição, aceda ao Fórum Community do Power Apps.

Se o StartScreen devolver um erro, o primeiro ecrã na vista Studio Tree será apresentado como se o StartScreen não tivesse sido definido. Utilize a função IfError para apanhar quaisquer erros e redirecione para um ecrã de erro apropriado.

Depois de alterar o StartScreen no Studio, teste-o passando com o rato por cima do objeto Aplicação no painel Vista de árvore, selecionando as reticências (...), e depois Navigar para StartScreen. O ecrã mudará como se a aplicação tivesse sido carregada.

Exemplos

Screen9

Indica que o Screen9 deve ser mostrado primeiro sempre que a aplicação começa.

If( Param( "admin-mode" ) = 1, HomeScreen, AdminScreen )

Verifica se o "modo de administração" Param foi definido pelo utilizador e utiliza-o para decidir se o HomeScreen ou o AdminScreen devem ser apresentados primeiro.

If( LookUp( Attendees, User = User().Email ).Staff, StaffPortal, HomeScreen )

Verifica se um participante numa conferência é membro do staff e direciona-o para o ecrã adequado no arranque.

IfError( If( CustomConnector.APICall() = "Forest", 
             ForestScreen, 
             OceanScreen 
         ), 
         ErrorScreen 
)

Direciona a aplicação com base numa chamada à API para o ForestScreen ou o OceanScreen. Se a API falhar por qualquer motivo, é utilizado o ErrorScreen.

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).