Objeto App no Power Apps

Aplica-se a: Aplicativos de tela

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

Descrição

Como um controle, o objeto App tem propriedades que identificam qual tela está sendo exibida e solicitam que você salve as alterações para que elas não sejam perdidas. Cada aplicação tem um objeto de Aplicação.

Escreva fórmulas para algumas propriedades do objeto App . Na parte superior do painel Vista de árvore, selecione o objeto de Aplicação como faria com qualquer outro controlo ou ecrã. Para exibir ou editar uma das propriedades do objeto, selecione-a na lista suspensa à esquerda da barra de fórmulas.

Propriedade ActiveScreen

A propriedade ActiveScreen identifica a tela exibida no momento.

Esta propriedade devolve um objeto de ecrã. Use-o para fazer referência às propriedades da tela atual, como o nome com a fórmula App.ActiveScreen.Name. Você também pode comparar essa propriedade com outro objeto de tela, como com a fórmula de comparação App.ActiveScreen = Screen2 para verificar se Screen2 é a tela atual.

Use a função Voltar ou Navegar para alternar a tela exibida.

Propriedade BackEnabled

A propriedade BackEnabled altera a forma como a aplicação responde ao gesto de voltar do dispositivo (percorrer ou utilizar o botão Voltar do hardware em dispositivos Android ou percorrer a partir da esquerda em dispositivos iOS) quando é executado no Power Apps mobile. Quando ativado, o gesto de voltar do dispositivo volta para a tela que foi mostrada mais recentemente, que é semelhante à fórmula Voltar . Quando desativado, o gesto de voltar do dispositivo leva o usuário para a lista de aplicativos.

Propriedades ConfirmExit

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

ConfirmExit

ConfirmExit é uma propriedade booleana que, quando verdadeira, abre uma caixa de diálogo de confirmação antes do fechamento do aplicativo. Por predefinição, esta propriedade é false e não é apresentada qualquer caixa de diálogo.

Quando o usuário puder 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 verifique variáveis e propriedades de controle (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:

• Execute a função Exit (Sair ).
• Se o aplicativo for executado em um navegador:
  • Feche o navegador ou a guia do navegador onde o aplicativo é executado.
  • Selecione o botão Voltar do navegador.
  • Execute a função Launch com um LaunchTarget of Self.
• Se a aplicação for executada no Power Apps Mobile (iOS ou Android):
  • Passe o dedo para alternar para um aplicativo diferente no Power Apps Mobile.
  • Selecione o botão Voltar em um dispositivo Android.
  • Execute 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 é exibida 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 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 mostrar uma mensagem genérica do navegador.

Exemplo

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

   AccountForm.Unsaved Or ContactForm.Unsaved
   

   A caixa de diálogo mostra se o usuário altera os dados em qualquer um dos formulários e, em seguida, tenta fechar o aplicativo sem salvar essas alterações.e o usuário altera os dados em qualquer um dos formulários e, em seguida, tenta fechar o aplicativo sem salvar essas alterações.

   [!div clas1. 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."
   )
   

   A caixa de diálogo mostra se o usuário altera dados no formulário Conta e tenta fechar o aplicativo sem salvar essas alterações.

   

Configurar a cadeia de conexão para o Application Insights

Para exportar logs de aplicativos gerados pelo sistema para o Application Insights, configure a cadeia de conexão para seu aplicativo 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. Insira a Cadeia de conexão no painel de propriedades.

Se os dados não forem enviados para o Application Insights, entre em contato com o administrador da Power Platform e verifique se o App Insights está desativado no nível do locatário.

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 fórmulas determinam o valor das propriedades de controlo. 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. BGColor também pode ser manipulado em algum canto da aplicação do qual o criador não está ciente, uma alteração efetuada por outra pessoa e que pode ser difícil de localizar.

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 altere inesperadamente um valor, mas esta situação difícil de depurar 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, tal como as células de uma folha de cálculo e 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 dos elementos dentro da fórmula e como são usados 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.

Funções definidas pelo utilizador

O Power Fx inclui uma longa lista de funções incorporadas, como If, Text e Set. As funções definidas pelo utilizador permitem que escreva as suas próprias funções que usam parâmetros e devolvem um valor, assim como as funções incorporadas. Pode pensar em funções definidas pelo utilizador como uma extensão para fórmulas nomeadas que adiciona parâmetros e oferece suporte a fórmulas de comportamento.

Por exemplo, pode definir uma fórmula nomeada que devolve livros de ficção de uma biblioteca:

Library = [ { Title: "The Hobbit", Author: "J. R. R. Tolkien", Genre: "Fiction" },
            { Title: "Oxford English Dictionary", Author: "Oxford University", Genre: "Reference" } ];

LibraryFiction = Filter( Library, Genre = "Fiction" );

Sem parâmetros, precisaríamos de definir fórmulas nomeadas separadas para cada género. Mas, em vez disso, vamos parametrizar a nossa fórmula nomeada:

LibraryType := Type( [ { Title: Text, Author: Text, Genre: Text } ] );

LibraryGenre( SelectedGenre: Text ): LibraryType = Filter( Library, Genre = SelectedGenre );

Agora, podemos chamar LibraryGenre( "Fiction" ), LibraryGenre( "Reference" ) ou filtrar em outros géneros com uma única função definida pelo utilizador.

A sintaxe é:

FunctionName( [ ParameterName1: ParameterType1 [ , ParameterName2: ParameterType2 ... ] ] ) : Fórmula ReturnType = ;

• FunctionName — Obrigatório. O nome da função definida pelo utilizador.
• ParameterName(s) – Opcional. O nome de um parâmetro da função.
• ParameterType(s) — Opcional. O nome de um tipo, seja um nome de tipo de dados incorporado, um nome de origem de dados ou um tipo definido com a função Type.
• ReturnType — Obrigatório. O tipo do valor de devolução da função.
• Formula – Obrigatório. A fórmula que calcula o valor da função com base nos parâmetros.

Cada parâmetro e a saída da função definida pelo utilizador têm de ser digitados. Neste exemplo, SelectedGenre: Text define o primeiro parâmetro para que a nossa função seja do tipo Text e SelectedGenre é o nome do parâmetro usado no corpo para a operação Filtrar. Consulte Tipos de dados para obter os nomes de tipo suportados. A função Type é usada para criar um tipo agregado para a nossa biblioteca, para que possamos devolver uma tabela de livros da nossa função.

Definimos LibraryType como uma tabela plural do tipo de registos. Se quisermos passar um único livro para uma função, podemos extrair o tipo de registo para esta tabela com a função RecordOf:

BookType := Type( RecordOf( LibraryType ) );

IsGenre( Book: BookType, SelectedGenre: Text ): Boolean = (Book.Genre = SelectedGenre);

A correspondência de registos para parâmetros de função é mais apertada do que em outras partes do Power Fx. Os campos de um valor de registo têm de ser um subconjunto adequado da definição de tipo e não podem incluir campos adicionais. Por exemplo, IsGenre( { Title: "My Book", Published: 2001 }, "Fiction" ) resultará num erro.

Observe que a recursão ainda não é suportada por funções definidas pelo utilizador.

Funções de comportamento definidas pelo utilizador

As fórmulas nomeadas e a maioria das funções definidas pelo utilizador não suportam funções de comportamento com efeitos secundários, tais como Set ou Notify. Em geral, é melhor evitar a atualização do estado, se possível, confiando, em vez disso, em padrões de programação funcionais e permitindo que o Power Fx recalcule fórmulas automaticamente conforme necessário. Mas, há casos em que é inevitável. Para incluir a lógica de comportamento numa função definida pelo utilizador, envolva o corpo em chavetas:

Spend( Amount: Number ) : Void = {
    If( Amount > Savings, 
        Error( $"{Amount} is more than available savings" ),
        Set( Savings, Savings - Amount );
        Set( Spent, Spent + Amount) 
    );
}

Agora, podemos chamar o Spend( 12 ) para verificar se temos 12 na nossa Poupanças e, em caso afirmativo, debitá-la por 12 e adicionar 12 à variável Gastos. O tipo de devolução desta função é Void, pois não devolve um valor.

A sintaxe de uma função de comportamento definida pelo utilizador é:

FunctionName( [ ParameterName1: ParameterType1 [ , ParameterName2: ParameterType2 ... ] ] ) : ReturnType = { Formula1 [ ; Fórmula 2 ... ] };

• FunctionName — Obrigatório. O nome da função definida pelo utilizador.
• ParameterName(s) – Opcional. O nome de um parâmetro da função.
• ParameterType(s) — Opcional. O nome de um tipo, seja um nome de tipo de dados incorporado, um nome de origem de dados ou um tipo definido com a função Type.
• ReturnType — Obrigatório. O tipo do valor de devolução da função. Use Void se a função não devolver um valor.
• Fórmula(s) – Obrigatório. A fórmula que calcula o valor da função com base nos parâmetros.

Tal como acontece com todas as fórmulas do Power Fx, a execução não termina quando um erro é encontrado. Depois de a função Error ter sido chamada, a função If impede que as alterações em Poupança e Gastos aconteçam. A função IfError também pode ser usada para impedir a execução adicional após um erro. Mesmo que devolva Void, a fórmula ainda pode devolver um erro se houver um problema.

Tipos definidos pelo utilizador

As fórmulas nomeadas podem ser usadas com a função Type para criar tipos definidos pelo utilizador. Use := em vez de = para definir um tipo definido pelo utilizador, por exemplo Book := Type( { Title: Text, Author: Text } ). Consulte a função Type para obter mais informações e exemplos.

Propriedade OnError

Use OnError para agir quando ocorrer um erro em qualquer lugar da aplicação. 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.

Em Aplicações de tela, o resultado da avaliação de cada fórmula é verificado para detetar erros. Se encontrar um erro, OnError é avaliado com as mesmas variáveis de âmbito FirstError e AllErrors que teriam sido usados se a fórmula completa tivesse sido moldada numa função IfError.

Se OnError estiver vazio, um banner de erro padrão mostrará o FirstError.Message do erro. A definição de uma fórmula OnError substitui esse comportamento, para que o criador possa lidar com o relatório de erros conforme necessário. Você pode solicitar o comportamento padrão em OnError relançando o erro com a função Erro. Use a abordagem de relançamento se quiser filtrar ou lidar com alguns erros de forma diferente, mas deixe que outros passem.

OnError não pode substituir um erro nos cálculos da mesma forma que IfError. Se OnError for invocado, o erro já ocorreu e já foi processado através de cálculos de fórmulas, como IfError; só relatório de erros de controlo OnError.

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 você definir uma variável global na parte superior de um OnError e lê-la posteriormente na mesma fórmula, o valor pode ter mudado. 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, o banner de erro padrão pode não aparecer para cada erro individualmente. Para evitar que sejam apresentadas demasiadas faixas de erro ao mesmo tempo, a mesmo faixa de erro não será apresentada novamente 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 necessário, você também pode alterar a fórmula para Label1.Text = IfError( 1/Slider1.Value, 0 ). Usar IfError significa que não há nenhum erro ou banner de erro. Não é possível alterar o valor de um erro de OnError porque o erro já aconteceu — OnError controla apenas como ele é relatado.

Se você adicionar um manipulador OnError , isso não afetará as etapas anteriores à etapa 5, mas alterará a forma como o erro é relatado:

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

Com esse manipulador OnError , o usuário do aplicativo não vê nenhum erro. Mas o erro é adicionado ao rastreamento do Monitor, incluindo a fonte das informações de erro de FirstError:

Se você também quiser mostrar o banner de erro padrão junto com o rastreamento, lance novamente o erro com a função Error após a chamada Trace , como se o Trace não estivesse lá:

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

Propriedade OnStart

A propriedade OnStart é executada quando o utilizador inicia a aplicação. Esta propriedade é frequentemente utilizada para:

• Recupere e armazene dados em cache em coleções usando a função Collect .
• Configure variáveis globais com a função Set.

Esta fórmula é executada 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. Mas você pode passar variáveis de contexto com a função Navegar .

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

Propriedade StartScreen

A propriedade StartScreen define qual tela mostra primeiro. Ele é avaliado uma vez quando o aplicativo carrega e retorna o objeto de tela a ser exibido. Por padrão, essa propriedade está vazia e a primeira tela no modo de exibição Árvore do Studio é exibida 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. Use estas funções e sinais para decidir qual tela 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.
• Chamadas de API através de um conector. Certifique-se de que a chamada retorna rapidamente.
• Sinais como Ligação, Bússola e Aplicação.

Se o StartScreen retornar um erro, a primeira tela no modo de exibição Árvore do Studio mostrará como se o StartScreen não estivesse definido. Use a função IfError para detetar erros e redirecionar para uma tela de erro.

Depois de alterar o StartScreen no Studio, teste-o passando o mouse sobre o objeto App no painel deexibição Árvore , selecionando as reticências (...) e, em seguida, selecionando Navegar até o StartScreen. A tela muda como se o aplicativo tivesse acabado de ser carregado.

Exemplos

Screen9

Screen9 mostra primeiro sempre que o aplicativo é iniciado.

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

Verifica se o "modo admin" do Param está definido e usa-o para decidir se HomeScreen ou AdminScreen é exibido primeiro.

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

Verifica se um participante é um membro da equipe e o direciona para a tela correta na inicialização.

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, o aplicativo será usado ErrorScreen .

Propriedade StudioVersion

Use a propriedade StudioVersion para mostrar ou registrar a versão do Power Apps Studio usada para publicar um aplicativo. Essa propriedade ajuda quando você está depurando e verificando se seu aplicativo foi republicado com uma versão recente do Power Apps Studio.

StudioVersion retorna texto. O formato deste texto pode mudar ao longo do tempo, por isso trate-o como um todo e não extraia partes individuais.