Objeto App no Power Apps

Aplica-se a: aplicativos Canvas

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. Todo aplicativo tem um objeto de Aplicativo.

Escreva fórmulas para algumas propriedades do objeto App . Na parte superior do painel Exibição de árvore, selecione o objeto de Aplicativo como faria com qualquer outro controle ou tela. 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.

Essa propriedade retorna um objeto de tela. 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 o aplicativo responde ao gesto de voltar do dispositivo (deslize o dedo ou use o botão voltar do hardware em dispositivos Android ou deslize o dedo da esquerda em dispositivos iOS) ao executar no power apps móvel. Quando habilitado, o gesto de voltar do dispositivo volta para a tela que foi mostrada mais recentemente, que é semelhante à fórmula Back . Quando desabilitado, 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 salvas. Use as propriedades ConfirmExit e ConfirmExitMessage para avisar o usuário antes de fechar seu aplicativo.

ConfirmExit

ConfirmExit é uma propriedade booliana que, quando verdadeira, abre uma caixa de diálogo de confirmação antes do fechamento do aplicativo. Por padrão, essa propriedade é definida como false e nenhuma caixa de diálogo é exibida.

Quando 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 verifica variáveis e propriedades de controle (por exemplo, a propriedade Não salva do controle Editar formulário ).

A caixa de diálogo de confirmação é exibida em qualquer situação em que os dados podem ser perdidos, como:

• Execute a função Exit .
• Se o aplicativo for executado em um navegador:
  • Feche o navegador ou a guia do navegador em que o aplicativo é executado.
  • Selecione o botão voltar do navegador.
  • Execute a função Inicialização com um LaunchTarget of Self.
• Se o aplicativo for executado no Power Apps Mobile (iOS ou Android):
  • Deslize 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 Inicializar 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 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 dentro da 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 do Aplicativo 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 tenta fechar o aplicativo sem salvar essas alterações.e o usuário altera os dados em qualquer um dos formulários e tenta fechar o aplicativo sem salvar essas alterações.

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

   A caixa de diálogo mostra se o usuário altera os 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 o aplicativo para edição no Power Apps Studio.
2. Selecione o objeto Aplicativo na exibição de árvore na navegação à esquerda.
3. Insira a cadeia de conexão no painel propriedades.

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

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.

Em Power Apps, as fórmulas determinam o valor das propriedades de controle. 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 essa situação difícil de depurar 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. Elas recalculam automaticamente como as células de uma planilha e as propriedades de controle fazem.

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 dos elementos dentro da fórmula e 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.

Funções definidas pelo usuário

O Power Fx inclui uma longa lista de funções internas, como If, Text e Set. As funções definidas pelo usuário permitem que você escreva suas próprias funções que usam parâmetros e retornam um valor, assim como as funções internas. Você pode pensar em funções definidas pelo usuário como uma extensão para fórmulas nomeadas que adiciona parâmetros e oferece suporte a fórmulas de comportamento.

Por exemplo, você pode definir uma fórmula nomeada que retorna 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 definir fórmulas nomeadas separadas para cada gênero. Mas, em vez disso, vamos parametrizar 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 outros gêneros com uma única função definida pelo usuário.

A sintaxe é:

FunctionName( [ ParameterName1: ParameterType1 [ , ParameterName2: ParameterType2 ... ] ] ) : ReturnType = Formula;

• FunctionName – Obrigatório. O nome da função definida pelo usuário.
• ParameterName(s) – Opcional. O nome de um parâmetro de função.
• ParameterType(s) – Opcional. O nome de um tipo, um nome do tipo de dados, um nome da fonte de dados ou um tipo definido com a função Type.
• ReturnType – obrigatório. O tipo do valor de retorno 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 usuário devem ser tipadas. Neste exemplo, SelectedGenre: Text define o primeiro parâmetro como nossa função como sendo do tipo Text e SelectedGenre é o nome do parâmetro usado no corpo para a operação Filter. Consulte Tipos de dados para os nomes de tipo compatíveis. A função Type é usada para criar um tipo agregado para nossa biblioteca, de maneira que possamos retornar uma tabela de livros com base em nossa função.

Definimos LibraryType como um tipo da tabela de registros plural. Se quisermos passar um único livro para uma função, poderemos extrair o tipo de registro para essa tabela com a função RecordOf:

BookType := Type( RecordOf( LibraryType ) );

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

A correspondência de registros para parâmetros de função é mais restrita do que em outras partes do Power Fx. Os campos de um valor de registro devem 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" ) vai resultar em um erro.

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

Comportamento: funções definidas pelo usuário

As fórmulas nomeadas e a maioria das funções definidas pelo usuário não dão suporte a funções de comportamento com efeitos colaterais, como Set ou Notify. Em geral, será melhor evitar atualizar o estado se você puder. Em vez disso, confie em padrões de programação funcionais e permita que o Power Fx recalcule automaticamente fórmulas conforme necessário. Mas, há casos em que é inevitável. Para incluir a lógica de comportamento em uma função definida pelo usuário, envolva o corpo em chaves:

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 Spend( 12 ) para verificar se temos 12 em nossa Savings e, em caso afirmativo, debitar 12 e adicionar 12 à variável Spent. O tipo de retorno dessa função é Void , pois não retorna um valor.

A sintaxe de uma função definida pelo usuário de comportamento é:

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

• FunctionName – Obrigatório. O nome da função definida pelo usuário.
• ParameterName(s) – Opcional. O nome de um parâmetro de função.
• ParameterType(s) – Opcional. O nome de um tipo, um nome do tipo de dados integrado, um nome da fonte de dados ou um tipo definido com a função Type.
• ReturnType – obrigatório. O tipo do valor de retorno da função. Use Void caso a função não retorne um valor.
• Formula(s) – obrigatório. A fórmula que calcula o valor da função com base nos parâmetros.

Assim como acontece com todas as fórmulas do Power Fx, a execução não termina quando um erro é encontrado. Depois que a função Error tiver sido chamada, a função If impedirá que as alterações em Savings e Spent aconteçam. A função IfError também pode ser usada para impedir a execução adicional depois de um erro. Mesmo que retorne Void, a fórmula ainda poderá retornar um erro se houver um problema.

Tipos definidos pelo usuário

As fórmulas nomeadas podem ser usadas com a função Type para criar tipos definidos pelo usuário. Use := em vez de = para definir um tipo definido pelo usuário; 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 realizar uma ação quando ocorre um erro em qualquer lugar do aplicativo. Ele oferece uma oportunidade global de interceptar um banner de erro antes que ele seja exibido para o 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.

Em aplicativos de tela, o resultado de cada avaliação da fórmula é verificado em busca de erros. Se um erro for encontrado, OnError será avaliado com as mesmas variáveis de escopo FirstError e AllErrors que seriam usadas se toda a fórmula tivesse sido encapsulada em uma função IfError.

Se OnError estiver vazio, uma faixa de erro padrão mostrará o FirstError.Message do erro. Definir uma fórmula OnError substitui esse comportamento, de modo que o criador possa lidar com relatórios de erros conforme necessário. Você pode solicitar o comportamento padrão no OnError, relançando o erro com a função Error. Use a abordagem de crescimento se você quiser filtrar ou lidar com alguns erros de forma diferente, mas permitir que outras pessoas passem.

OnError não pode substituir um erro nos cálculos da maneira que IfError pode. Se OnError for invocado, o erro já terá acontecido e já foi processado por meio dos cálculos de fórmula como IfError; OnError controla apenas relatórios de erros.

As fórmulas OnError são avaliadas simultaneamente e é possível que sua avaliação possa se sobrepor 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 poderá ter sido alterado. Use a função With para criar um valor nomeado que seja local para a fórmula.

Embora cada erro seja processado individualmente pelo OnError, a faixa de erro padrão pode não aparecer individualmente para cada erro. Para evitar ter muitas faixas de erro exibidas simultaneamente, a mesma faixa de erro não será exibida novamente se tiver sido recém-mostrada.

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, 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 faixa de erro. Não é possível alterar o valor de um erro do OnError porque o erro já aconteceu— o OnError controla apenas como ele é relatado.

Se você adicionar um manipulador OnError , ele não afetará as etapas antes da etapa 5, mas isso 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 origem das informações de erro do FirstError:

Se você também quiser mostrar a faixa de erro padrão junto com o rastreamento, recresque o erro com a função Erro após a chamada de rastreamento , como se o Rastreamento não estivesse lá:

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

Propriedade OnStart

A propriedade OnStart é executada quando o usuário inicia o aplicativo. Essa propriedade geralmente é usada para:

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

Essa fórmula é executada antes da primeira tela ser exibida. Nenhuma tela é carregada; portanto, você não pode definir variáveis de contexto com a função UpdateContext. Mas você pode passar variáveis de contexto com a função Navigate .

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 selecionando Executar NoStart. Ao contrário de quando o aplicativo é carregado pela primeira vez, coleções e variáveis existentes já estão definidas. Para começar com coleções vazias, use a função ClearCollect, em vez da função Collect.

Propriedade StartScreen

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

Se 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 capturar 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 de exibição árvore , selecionando as reticências (...) e selecionando Navegar até StartScreen. A tela é alterada como se o aplicativo tivesse sido carregado.

Exemplos

Screen9

Screen9 mostra primeiro sempre que o aplicativo é iniciado.

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

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

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

Verifica se um participante é membro da equipe e direciona-o para a tela correta 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, o aplicativo usará ErrorScreen em vez disso.

Propriedade StudioVersion

Use a propriedade StudioVersion para mostrar ou registrar em log 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 desse texto pode ser alterado ao longo do tempo, portanto, trate-o como um todo e não extraia partes individuais.