Objeto App no Power Apps

Aplica-se a: Aplicativos de tela Aplicativos controlados por modelo

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 propriedade devolve um objeto de ecrã. Utilize-a para consultar propriedades do ecrã atualmente apresentado, como o nome com a fórmula App.ActiveScreen.Name. Também pode comparar esta propriedade com outro objeto de ecrã, tal como com a fórmula de comparação App.ActiveScreen = Screen2 para testar se Screen2 é o ecrã atualmente apresentado.

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

Propriedade BackEnabled

A propriedade BackEnabled muda a forma como a aplicação responde ao gesto de voltar do dispositivo (deslizar ou usar o botão Voltar do hardware em dispositivos Android, deslize da esquerda em dispositivos iOS) quando executado no Power Apps Mobile. Quando ativado, o gesto de voltar do dispositivo navega de volta para o ecrã que foi apresentado mais recentemente, o que é semelhante à fórmula Voltar. Quando desativado, o gesto de voltar do dispositivo retorna o utilizador para a lista de aplicações.

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 aplicativos incorporados, 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 booleano que, quando true, abre uma caixa de diálogo de confirmação antes que o aplicativo seja fechado. Por predefinição, esta propriedade é false e não é apresentada qualquer caixa de diálogo.

Em situações em que o utilizador pode ter alterações não guardadas na aplicação, utilize esta propriedade para mostrar uma caixa de diálogo de confirmação antes de sair da aplicação. 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, OnMessagee BackEnabled, que são experimentais. Estas propriedades serão removidas eventualmente do objeto da aplicação. 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.

   

Configurar Chave de Instrumentação para Application Insights

Para exportar os registos de aplicação gerados pelo sistema para o Application Insights, é necessário configurar a Chave de Instrumentação para a sua aplicação de tela.

1. Abra a sua aplicação para edição no Power Apps Studio.
2. Selecione o objeto da Aplicação na vista de árvore na navegação esquerda.
3. Introduza a Chave de Instrumentação no painel de propriedades.

Se os dados não forem enviados para o App Insights, contacte o seu administrador do Power Platform e verifique se o App Insights está desativado a nível do inquilino.

Propriedade de fórmulas

Utilize fórmulas nomeadas, na propriedade Formulas, para definir uma fórmula que pode ser reutilizada em toda a aplicação.

No Power Apps, as propriedades de controlo são condicionadas por fórmulas. Por exemplo, para definir a cor de fundo de forma consistente numa aplicação, poderá definir a propriedade Fill para cada uma com uma fórmula comum:

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

Com muitos locais onde esta fórmula pode aparecer, torna-se chato e dado a erros atualizá-los a todos se for necessária uma alteração. Em vez disso, pode criar uma variável global em OnStart para definir a cor uma vez e, em seguida, reutilizar o valor em toda a aplicação:

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

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

As fórmulas nomeadas fornecem uma alternativa. Da mesma forma que escrevemos normalmente controlo-propriedade = expressão, podemos escrever nome = expressão e, em seguida, reutilizar o nome na nossa aplicação para substituir a expressão. As definições destas fórmulas são efetuadas na propriedade Formulas:

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

As vantagens de utilizar fórmulas nomeadas incluem:

• O valor da fórmula está sempre disponível. Não existe dependência de tempo, nenhum OnStart que tenha de ser executado primeiro, antes de o valor ser definido, sem tempo em que o valor da fórmula seja incorreto. As fórmulas nomeadas podem referenciar-se umas às outras por qualquer ordem, desde que não criem uma referência circular. Podem ser calculadas em paralelo.
• O valor da fórmula está sempre atualizado. A fórmula pode efetuar um cálculo que dependa das propriedades de controlo ou dos registos da base de dados e, à medida que se altera, o valor da fórmula é atualizado automaticamente. Não necessita de atualizar manualmente o valor como faria com uma variável. E as fórmulas só serão recalculadas quando necessário.
• A definição da fórmula é imutável. A definição em Formulas é a única origem da verdade e o valor não pode ser alterado em qualquer outro local na aplicação. Com variáveis, é possível que algum código mude inesperadamente um valor, mas isto não é possível com fórmulas nomeadas.
• É possível diferir o cálculo da fórmula. Uma vez que o seu valor é imutável, pode sempre ser calculado quando necessário, o que significa que não tem de ser calculado até que seja necessário. Os valores de fórmula que não são utilizados até que o ecrã2 de uma aplicação seja apresentado não precisam de ser calculados até que o ecrã2 seja visível. Adiar este trabalho pode melhorar o tempo de carregamento da aplicação. As fórmulas nomeadas são declarativas e fornecem oportunidades para o sistema otimizar como e quando são calculadas.
• As fórmulas nomeadas é um conceito do Excel. O Power Fx utiliza conceitos do Excel onde possível, uma vez que muitas pessoas conhecem bem o Excel. As fórmulas nomeadas são o equivalente a células nomeadas e fórmulas nomeadas no Excel, geridas com o Gestor de Nomes. Recalculam automaticamente como uma folha de cálculo, tal como as propriedades de controlo.

São definidas fórmulas nomeadas, uma após a outra na propriedade Formulas, cada uma a terminar com um ponto e vírgula. O tipo de fórmula é inferido a partir dos tipos da expressão, que se baseia nos tipos de elementos da expressão e na forma como são utilizados em conjunto. Por exemplo, estas fórmulas nomeadas podem obter informações úteis sobre o utilizador atual a partir 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 de ser atualizada, pode ser feito facilmente nesta localização. Se UserPhone não for necessário na aplicação, estas chamadas para a tabela Utilizadores no Dataverse não são feitas. Não existe penalização por incluir uma definição de fórmula que não esteja utilizada.

Algumas limitações de fórmulas nomeadas:

• Não podem utilizar funções de comportamento, nem causar efeitos colaterais na aplicação.
• Não podem criar uma referência circular. Não é permitido ter a = b; e b = a; na mesma aplicação.

Propriedade OnError

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 maneira que IfError pode. 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 simultaneamente e é possível que a sua avaliação se sobreponha 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 automaticamente reavaliado. 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, por isso 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 configurar 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.
• A opção desativada será desativada para aplicativos criados antes de março de 2021, onde você adicionou Navegar ao OnStart entre março de 2021 e agora. 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 aparecerá na lista de propriedades quando a opção desativada Barra de fórmulas aprimorada estiver ativada. Para desativar a Barra de fórmulas avançada, aceda a Definições>Próximas caraterísticas>Extinta> desative o comutador Barra de fórmulas avançada 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.

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, em particular, utilizar estas funções e sinais para determinar qual o ecrã a mostrar primeiro:

• Função Param para ler os parâmetros usados para iniciar o aplicativo.
• Função de utente para ler informações sobre o utente atual.
• LookUp, Filter, CountRows, Max e outras funções que leem de um 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.

Propriedade StudioVersion

Use a propriedade StudioVersion para apresentar ou registar a versão do Power Apps Studio que foi usada para publicar uma aplicação. Isto pode ser útil ao depurar e para garantir que a sua aplicação foi republicada 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.