Objeto App no Power Apps

Aplica-se a: Aplicativos de tela Aplicativos baseados em modelo

Fornece informações sobre o aplicativo em execução no momento e o controle sobre o comportamento do aplicativo.

Descrição

Como um controle, o objeto de Aplicativo fornece propriedades que identificam qual tela está sendo exibida e solicitam que o usuário salve as alterações para que não sejam perdidas. Todo aplicativo tem um objeto de Aplicativo.

Você pode escrever fórmulas para algumas propriedades do objeto do Aplicativo. Na parte superior do painel Exibição de árvore, selecione o objeto de Aplicativo como faria com qualquer outro controle ou tela. Visualize e edite uma das propriedades do objeto, selecionando-a na lista suspensa à esquerda da barra de fórmulas.

Propriedade ActiveScreen

A propriedade ActiveScreen identifica a tela que está sendo exibida.

Essa propriedade retorna um objeto de tela. Use-a para fazer referência a propriedades da tela exibida no momento, como o nome com a fórmula App.ActiveScreen.Name. Também é possível comparar essa propriedade com outro objeto de tela, como com a fórmula de comparação App.ActiveScreen = Screen2 para testar se Screen2 é a tela exibida no momento.

Usa a função Back ou Navigate para alterar a tela exibida.

Propriedade BackEnabled

A propriedade BackEnabled muda a forma como o aplicativo responde ao gesto de voltar do dispositivo (deslize ou uso do botão Voltar do hardware nos dispositivos Android, deslize da esquerda em dispositivos iOS) quando executado em aplicativos móveis do Power Apps. Quando ativado, o gesto de voltar do dispositivo navega de volta para a tela exibida mais recentemente, o que é semelhante à fórmula Voltar . Quando desativado, o gesto de voltar do dispositivo retorna o usuário à lista de aplicativos.

Propriedades ConfirmExit

Ninguém quer perder alterações não salvas. Use as propriedades ConfirmExit e ConfirmExitMessage para avisar ao usuário antes de ele fechar o aplicativo

Nota

• A propriedade ConfirmExit não funciona em aplicativos incorporados, por exemplo, Power BI e SharePoint.
• Atualmente, essas propriedades podem referenciar controles somente na primeira tela, se a versão preliminar do recurso Carga atrasada estiver ativada (que é por padrão para novos aplicativos). Se forem feitas referências, o Power Apps Studio não mostrará um erro, mas o aplicativo publicado resultante não será aberto no Power Apps Mobile ou no navegador. Estamos trabalhando ativamente para eliminar essa limitação. Enquanto isso, você pode desligar Carga atrasada em Configurações>Próximos recursos (em Versão preliminar).

ConfirmExit

ConfirmExit é uma propriedade Boolean que quando é definida como true, abre uma caixa de diálogo de confirmação antes de o aplicativo ser fechado. Por padrão, essa propriedade é definida como false e nenhuma caixa de diálogo é exibida.

Em situações em que o usuário pode ter alterações não salvas no aplicativo, use essa propriedade para mostrar uma caixa de diálogo de confirmação antes de sair do aplicativo. Use uma fórmula que possa verificar variáveis e controlar propriedades (por exemplo, a propriedade Unsaved do controle Edit form).

A caixa de diálogo de confirmação aparece em qualquer situação em que os dados possam ser perdidos, como nestes exemplos:

• Executando a função Exit.
• Se o aplicativo estiver sendo executado em um navegador:
  • Fechando o navegador ou a guia do navegador em que o aplicativo está sendo executado.
  • Selecionando o botão voltar do navegador.
  • Executando a função Launch com LaunchTarget de Auto.
• Se o aplicativo estiver em execução no Power Apps Mobile (iOS ou Android):
  • Deslize para mudar para um aplicativo diferente no Power Apps Mobile.
  • Selecionando o botão voltar em um dispositivo Android.
  • Executando a função Launch para iniciar outro aplicativo de tela.

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

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

ConfirmExitMessage

Por padrão, a caixa de diálogo de confirmação mostra uma mensagem genérica, como "Você pode ter alterações não salvas." no idioma do usuário.

Use ConfirmExitMessage para fornecer uma mensagem personalizada na caixa de diálogo de confirmação. Se esta propriedade estiver em branco, o valor padrão será usado. As mensagens personalizadas são truncadas, conforme necessário para caber na caixa de diálogo de confirmação, portanto, mantenha a mensagem em algumas linhas no máximo.

Em um navegador, a caixa de diálogo de confirmação pode aparecer com uma mensagem genérica do navegador.

Nota

O objeto do aplicativo tem mais duas propriedades OnMessage eBackEnabled que são experimentais. Essas propriedades serão eventualmente removidas do objeto do aplicativo. Recomendamos não usar essas propriedades no seu ambiente de produção.

Exemplo

1. Crie um aplicativo que contenha dois controles de formulário, AccountForm e ContactForm.

2. Defina a propriedade ConfirmExit do objeto do Aplicativo para esta expressão:

   AccountForm.Unsaved Or ContactForm.Unsaved
   

   Essa caixa de diálogo será exibida se o usuário alterar os dados em um dos formulários e tentar fechar o aplicativo sem salvar essas alterações.

   

3. Defina a propriedade ConfirmExitMessage do objeto do Aplicativo para esta fórmula:

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

   Essa caixa de diálogo será exibida se o usuário alterar os dados no formulário da Conta e tentar fechar o aplicativo sem salvar essas alterações.

   

Propriedade de fórmulas

Use as fórmulas nomeadas, na propriedade do Fórmulas, para definir uma que possa ser reutilizada em todo o seu aplicativo.

No Power Apps, as propriedades de controle são acionadas por fórmulas. Por exemplo, para definir a cor de fundo de forma consistente em um aplicativo, você pode definir a propriedade Preenchimento para cada uma como uma fórmula comum:

Label1.Fill: ColorValue( Param( "BackgroundColor" ) )
Label2.Fill: ColorValue( Param( "BackgroundColor" ) )
Label3.Fill: ColorValue( Param( "BackgroundColor" ) )

Com tantos lugares onde essa fórmula pode aparecer, torna-se entediante e propenso a erros atualizar todas se uma mudança for necessária. Em vez disso, você pode criar uma variável global em OnStart para definir a cor uma vez e, em seguida, reutilizar o valor em todo o aplicativo:

App.OnStart: Set( BGColor, ColorValue( Param( "BackgroundColor" ) ) )
Label1.Fill: BGColor
Label2.Fill: BGColor
Label3.Fill: BGColor

Embora este método seja melhor, ele também depende do OnStart estar em execução antes que o valor para BGColor seja estabelecido. BGColor também pode ser manipulado em algum canto do aplicativo que o criador não esteja ciente, uma alteração feita por outra pessoa, e que possa ser difícil de rastrear.

As fórmulas nomeadas fornecem uma alternativa. Da mesma forma que comumente gravamos control-property = expression, podemos gravar name = expression e depois reutilizar nome em todo o nosso aplicativo para substituir expressão. As definições dessas fórmulas são feitas na propriedade Fórmulas:

App.Formulas: BGColor = ColorValue( Param( "BackgroundColor" ) );
Label1.Fill: BGColor
Label2.Fill: BGColor
Label3.Fill: BGColor

As vantagens de usar fórmulas nomeadas incluem:

• O valor da fórmula está sempre disponível. Não há nenhuma dependência de tempo, nenhum OnStart que deve ser executado antes que o valor seja definido, nenhum momento em que o valor da fórmula esteja incorreto. As fórmulas nomeadas podem fazer referência umas às outras em qualquer ordem, desde que elas não criem uma referência circular. Elas podem ser calculadas em paralelo.
• O valor da fórmula está sempre atualizado. A fórmula pode realizar um cálculo que dependa das propriedades de controle ou de registros do banco de dados e, à medida que mudam, o valor da fórmula é atualizado automaticamente. Você não precisa atualizar manualmente o valor assim como faz com uma variável. E as fórmulas só são recalculadas quando necessário.
• A definição da fórmula é imutável. A definição em Fórmulas é a única fonte de verdade e o valor não pode ser alterado em nenhum outro lugar no aplicativo. Com variáveis, é possível que algum código altere inesperadamente um valor, mas isso não é possível com fórmulas nomeadas.
• O cálculo da fórmula pode ser adiado. Como seu valor é imutável, ele sempre pode ser calculado quando necessário, o que significa que ele não precisa ser calculado até que seja necessário. Os valores de fórmula que não são usados até screen2 de um aplicativo seja exibido não precisam ser calculados até que screen2 fique visível. Adiar esse trabalho pode melhorar o tempo de carregamento do aplicativo. As fórmulas nomeadas são declarativas e fornecem oportunidades para o sistema otimizar como e quando elas são computadas.
• As fórmulas nomeadas são um conceito do Excel. O Power Fx usa conceitos do Excel sempre que possível, pois muitas pessoas conhecem bem o Excel. As fórmulas nomeadas são o equivalente a células nomeadas e fórmulas nomeadas no Excel, gerenciadas com o Gerenciador de Nomes. Eles recalculam automaticamente como uma planilha, da mesma forma como é feito com as propriedades de controle.

As fórmulas nomeadas são definidas, uma após a outra na propriedade Fórmulas, cada uma terminando com um ponto e vírgula. O tipo da fórmula é inferido a partir dos tipos da expressão, que se baseia nos tipos dos elementos dentro na expressão e em como eles são usados juntos. Por exemplo, essas fórmulas nomeadas recuperam informações úteis sobre o usuário atual do Dataverse:

UserEmail = User().Email;
UserInfo = LookUp( Users, 'Primary Email' = User().Email );
UserTitle = UserInfo.Title;
UserPhone = Switch( UserInfo.'Preferred Phone', 
                    'Preferred Phone (Users)'.'Mobile Phone', UserInfo.'Mobile Phone',
                    UserInfo.'Main Phone' );

Se a fórmula para UserTitle precisar ser atualizado, isso poderá ser feito facilmente neste local. Se UserPhone não for necessário no aplicativo, essas chamadas para a tabela Usuários no Dataverse não serão feitas. Não há nenhuma penalidade por incluir uma definição de fórmula que não seja usada.

Algumas limitações das fórmulas nomeadas:

• Elas não podem usar funções de comportamento ou causar efeitos colaterais no aplicativo.
• Elas não podem criar uma referência circular. Ter a = b; e b = a; no mesmo aplicativo não é permitido.

Propriedade OnError

Use OnError para agir após a detecção de um erro. Ela oferece uma oportunidade global de interceptar um banner de erro antes que ele seja exibido ao usuário final. Também pode ser usado para registrar um erro com a função Trace ou gravar em um banco de dados ou serviço Web.

O resultado de cada avaliação de fórmula é verificado em busca de erros. Se for um erro, OnError será avaliado com as mesmas variáveis de escopo FirstError e AllErrors que estariam presentes se a fórmula inteira fosse encapsulada em uma função IfError.

Se OnError estiver vazio, um banner de erro padrão será mostrado com a FirstError.Message do erro. A definição de uma fórmula OnError substitui esse comportamento, permitindo que o criador lide com o relatório de erros como achar melhor. O comportamento padrão pode ser solicitado em OnError ao gerar novamente o erro com a função Error. Isso será útil se alguns erros tiverem de ser filtrados ou tratados de uma maneira diferente, enquanto outros devem ser passados.

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

As fórmulas OnError são avaliadas simultaneamente e é possível que sua avaliação se sobreponha ao processamento de outros erros. Por exemplo, se você definir uma variável global em cima de um OnError e a ler posteriormente na mesma fórmula, o valor poderá ter mudado. Use a função With para criar um valor nomeado que seja local para a fórmula.

Embora cada erro seja processado individualmente por OnError, o banner de erro padrão pode não aparecer para cada erro individualmente. Para evitar ter muitos banners de erro exibidos ao mesmo tempo, o mesmo erro não desencadeará um novo banner de erro se ele tiver sido exibido recentemente.

Exemplo

Considere um controle Label e um controle Slider que estejam ligados pela fórmula:

Label1.Text = 1/Slider1.Value

O controle Slider usa 50 como padrão. Se o controle deslizante for movido para 0, Label1 não mostrará nenhum valor e um banner de erro será exibido:

Vejamos detalhadamente o que aconteceu:

1. O usuário moveu o controle Slider para a esquerda e a propriedade Slide1.Value foi alterada para 0.
2. Label1.Text foi reavaliado automaticamente. Ocorreu divisão por zero, gerando um erro.
3. Não há IfError nesta fórmula. A divisão por erro zero é retornada pela avaliação da fórmula.
4. Label1.Text não pode mostrar nada por este erro, então ele mostra um estado em branco.
5. OnError é invocado. Como não há nenhum manipulador, o banner de erro padrão é exibido com informações de erro.

Se necessário, também podemos modificar a fórmula para Label1.Text = IfError( 1/Slider1.Value, 0 ). Isso resultaria em nenhum erro ou banner de erro. Não podemos alterar o valor de um erro de OnError, já que, nesse ponto, como o erro já aconteceu, é apenas uma questão de como ele será relatado.

Se adicionarmos um manipulador de OnError, ele não terá impacto antes da etapa 5, mas poderá afetar a forma como o erro é relatado:

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

Com isso, do ponto de vista do usuário do aplicativo, não haverá nenhum erro. Mas o erro será adicionado ao rastreamento do Monitor, completo com a fonte das informações do erro de FirstError:

Se também quisermos ter o mesmo banner de erro padrão exibido além do rastreamento, podemos gerar novamente o erro com a função Error após a chamada Trace assim como aconteceria se Trace não existisse:

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

Propriedade OnStart

Nota

O uso da propriedade OnStart pode causar problemas de desempenho ao carregar um aplicativo. Estamos em processo de criação de alternativas para os dois principais motivos para o uso de propriedades: armazenamento de dados em cache e configuração de variáveis globais. Já criamos uma alternativa para definir a primeira tela a ser exibida com Navigate. Dependendo do contexto, esta propriedade pode ser desabilitada por padrão. Se você não a encontrar e precisar usá-la, verifique as configurações avançadas do aplicativo em busca de uma opção para ativá-la. A propriedade OnVisible de uma tela também pode ser usada.

A propriedade OnStart é executada quando o usuário inicia o aplicativo. Essa propriedade costuma ser usada para realizar as seguintes tarefas:

• Recuperar e armazenar em cache dados em coleções usando a função Collect.
• Configurar variáveis globais usando a função Set.

Essa fórmula é avaliada antes que a primeira tela apareça. Nenhuma tela é carregada; portanto, você não pode definir variáveis de contexto com a função UpdateContext. No entanto, você pode informar variáveis de contexto com a função Navigate.

Depois de alterar a propriedade OnStart, teste-a passando o mouse sobre o objeto Aplicativo no painel Exibição em árvore, selecionando as reticências (...) e, em seguida, selecionando Executar OnStart. Diferentemente de quando o aplicativo é carregado pela primeira vez, as coleções e variáveis existentes já estarão definidas. Para começar com coleções vazias, use a função ClearCollect, em vez da função Collect.

Observação

• O uso da função Navigate na propriedade OnStart foi desativado. Os aplicativos existentes continuarão funcionando. Por um tempo limitado, você ainda pode ativá-lo nas configurações do aplicativo (disponível em Desativado). No entanto, usar Navigate dessa maneira pode causar atrasos no carregamento do aplicativo, pois força o sistema a concluir a avaliação de OnStart antes de exibir a primeira tela. Use a propriedade StartScreen em vez de calcular a primeira tela exibida.
• A opção Desativado será desativada para aplicativos criados antes de março de 2021, nos quais você adicionou Navegar a OnStart entre o período de março de 2021 até agora. Quando você edita esses aplicativos no Power Apps Studio, é possível ver um erro. Alterne a opção Desativado mencionada acima para limpar este erro.

Propriedade StartScreen

Nota

A propriedade StartScreen não aparecerá na lista de propriedades quando a opção desativada Barra de fórmula aprimorada estiver ativada. Para desativar a Barra de fórmula aprimorada, vá para Configurações>Próximos recursos>Desativado> desative a opção Barra de fórmula aprimorada quando quiser usar a propriedade StartScreen.

A propriedade StartScreen determina qual tela será exibida primeiro. Ela é avaliada uma vez quando o aplicativo é carregado e retorna o objeto de tela a ser exibido. Por padrão, esta propriedade estará vazia, e a primeira tela na exibição em árvore do Studio é mostrada primeiro.

StartScreen é uma propriedade de fluxo de dados que não pode conter funções de comportamento. Todas as funções de fluxo de dados estão disponíveis. Especificamente, use estas funções e sinais para determinar qual tela mostrar primeiro:

• Função Param para ler os parâmetros usados para iniciar o aplicativo.
• Função User para ler informações sobre o usuário atual.
• LookUp, Filter, CountRows, Max e outras funções que leem de uma fonte de dados.
• Qualquer API chama por meio de um conector, mas atente-se para que o retorno seja rápido.
• Sinais como Conexão, Bússola e Aplicativo.

Nota

Variáveis globais e coleções, incluindo aquelas criadas em OnStart, não estão disponíveis em StartScreen. Em breve haverá alternativas declarativas para fazer isso. Para comentários sobre esta restrição, acesse Fórum da Comunidade do Power Apps.

Se StartScreen retorna um erro, a primeira tela na exibição em árvore do Studio será mostrada como se a propriedade StartScreen não tivesse sido definida. Use a função IfError para detectar quaisquer erros e redirecionar para uma tela de erro apropriada.

Depois de alterar a propriedade StartScreen no Studio, teste-a passando o mouse sobre o objeto Aplicativo no painel Exibição em árvore, selecionando as reticências (...) e, em seguida, selecionando Navegar para StartScreen. A tela mudará como se o aplicativo tivesse sido carregado.

Exemplos

Screen9

Indica que Screen9 deve ser mostrada primeiro sempre que o aplicativo é iniciado.

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

Verifica se o parâmetro "modo admin" foi definido pelo usuário e o usa para decidir se HomeScreen ou AdminScreen deve ser exibida primeiro.

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

Verifica se um participante de uma conferência é um membro da equipe e o direciona para a tela apropriada na inicialização.

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

Direciona o aplicativo com base em uma chamada de API para ForestScreen ou OceanScreen. Se a API falhar por qualquer motivo, a ErrorScreen é usada em seu lugar.

Propriedade StudioVersion

Use a propriedade StudioVersion para exibir ou registrar a versão do Power Apps Studio que foi usada para publicar um aplicativo. Isso pode ser útil ao depurar e garantir que seu aplicativo tenha sido republicado com uma versão recente do Power Apps Studio.

StudioVersion é retornado como texto. O formato do texto pode mudar ao longo do tempo e deve ser tratado como um todo; evite extrair porções individuais.