Funções Launch e Param

Artigo
10/16/2024

Aplica-se a: aplicativos Canvas

Inicia uma página da Web ou um aplicativo de tela e fornece acesso aos parâmetros de inicialização.

Launch

Inicia uma página da Web ou um aplicativo de tela. A função oferece suporte a:

Endereço (obrigatório), a URL da página da web do aplicativo Canvas.
Parâmetros (opcional), valores nomeados a serem passados para a página da web ou aplicativo de tela. Em um aplicativo de tela, os parâmetros podem ser lidos com a função Param.
Target (opcional), a aba do navegador na qual iniciar a página da web ou o aplicativo Canvas.

Launch só pode ser usado em fórmulas de comportamento.

Observação

Se a fórmula Launch for usada para abrir o Power Apps e o aplicativo não estiver visível para o usuário final, é recomendável verificar se o aplicativo está bloqueado por um bloqueador de pop-ups do navegador ou se o navegador está aguardando a resposta do usuário a uma caixa de diálogo que pergunta se ele deseja navegar para uma nova tela.

Address

As páginas da Web são iniciadas por meio de um endereço de URL. Por exemplo:

Launch( "https://bing.com" )

Você pode iniciar aplicativos de tela com Link da Web ou URI do Aplicativo (id do aplicativo prefixado com o /providers/Microsoft.PowerApps/apps/). Para encontrar esses valores para um aplicativo:

Vá para Power Apps.
Selecione Aplicativos no painel de navegação esquerdo.
Selecione seu aplicativo.
Selecione Detalhes no menu superior.
Você também pode selecionar ... (Mais Comandos) e selecione Detalhes no menu suspenso.
Copiar Link da Web.

O link da Web pode ser usado em qualquer página da web e iniciará o aplicativo de tela. Também pode ser usado com a função Launch. Por exemplo:

Launch( "https://apps.powerapps.com/e/{environment id}/a/{app id}?tenantId={tenantId}" )

Aplicativos nativos em um dispositivo não podem ser iniciados diretamente. Pode haver opções indiretas disponíveis em algumas plataformas, como um aplicativo nativo que instala um esquema de URL personalizado ou se registra no navegador da Web para oferecer uma opção para sites específicos.

Parâmetros

O Launch pode passar parâmetros para a página da web ou aplicativo de tela. Parâmetros podem ser oferecidos de duas maneiras:

Uma lista de argumentos de pares de valores de nomes. Por exemplo:

Launch( "https://bing.com/search", "q", "Power Apps", "count", 1 )

Um registro de valores de campo. Por exemplo:
```
Launch( "https://bing.com/search", { q: "Power Apps", count: 1 } )
```
Esse formulário pode ser mais fácil de trabalhar, pois torna mais clara a associação entre nome e valor. É o único formulário que suporta o argumento LaunchTarget opcional.

O endereço e os parâmetros são codificados em URL antes de serem passados para substituir certos caracteres não alfanuméricos por % e um número hexadecimal como se a função EncodeUrl foi usada em cada um.

Ao iniciar uma página da Web, uma cadeia de caracteres de consulta de parâmetros pode ser incluída no final do endereço da URL. Quaisquer parâmetros adicionais fornecidos para Launch será adicionado ao final da cadeia de caracteres de consulta. As cadeias de consulta não funcionam ao iniciar um aplicativo de tela.

Ao iniciar um aplicativo em um dispositivo móvel no qual o aplicativo já está em execução, os parâmetros não serão atualizados no aplicativo em execução. Uma recarga do aplicativo é necessária para que os parâmetros sejam atualizados.

Destino

Use o argumento LaunchTarget para especificar a janela do navegador de destino na qual abrir a página da Web ou aplicativo. Use um dos seguintes valores de enumeração LaunchTarget ou forneça uma janela personalizada nome.

Enumeração LaunchTarget	Descrição
Novo	A página da Web ou aplicativo é aberto em uma nova janela ou guia.
Substituir	A página da Web ou aplicativo substitui a janela ou guia atual.
nome	Em vez de um valor de enumeração, use sua própria cadeia de texto para a janela ou guia nome. Self é um nome interno usado apenas pela função Launch. Não tem impacto nem corresponderá ao título da janela que seus usuários veem. Se uma janela ou guia com o determinado nome já existir, seu conteúdo será substituído. Caso contrário, uma nova janela ou guia será criada. nome não pode começar com o caractere de sublinhado "_".

A novidade é o enumeração padrão ao executar em um navegador da web com Substituir e nome como opções disponíveis. Em um player móvel, Novo é o padrão para páginas da Web com nome como opção disponível, enquanto o aplicativo de tela atual sempre será substituído por outro aplicativo de tela.

Nota

Usar um LaunchTarget com qualquer valor diferente de Novo em cenários incorporados (por exemplo, Power BI ou SharePoint) não é compatível e pode resultar em um comportamento inesperado. No futuro, esse comportamento pode mudar ou causar um erro.

Param

A função Param recupera um parâmetro passado ao aplicativo quando ele foi iniciado. Se o parâmetro nomeado não tiver sido passado, Param retorna em branco.

Ao iniciar um aplicativo de tela de outro aplicativo de tela, use o argumento Parâmetro para a função Launch. Os nomes e valores dos parâmetros serão automaticamente codificados em URL.
Ao iniciar um aplicativo de tela a partir de uma página da Web, adicione parâmetros à cadeia de consulta do link da Web do aplicativo de tela. Isso envolve adicionar &parametername=parametervalue assumindo que a cadeia de consulta já foi iniciada para o tenantId. Por exemplo, adicionando &First%20Name=Vicki&category=3 passaria dois parâmetros: First Name com um valor de "Vicki" e category com um valor de "3" (o tipo de valor é texto). O nome e o valor do parâmetro devem ser codificados em URL se contiverem espaços ou caracteres especiais, semelhante ao uso da função EncodeURL.
Os nomes Param diferenciam maiúsculas e minúsculas.
Os nomes e valores dos parâmetros serão automaticamente decodificados por URL para uso no seu aplicativo.
Os valores dos parâmetros não mudam, a menos que o aplicativo seja recarregado. Usar Iniciar em um dispositivo móvel onde o aplicativo já está em execução não atualiza os parâmetros.
Mesmo que o parâmetro contenha um número, o tipo retornado por Param sempre será uma sequência de texto. A conversão para outros tipos ocorrerá automaticamente ou usará conversões explícitas, como a função Value para converter explicitamente em um número.

Observação

Para páginas personalizadas, os únicos parâmetros aceitos pela página são: recordId e entidadeName.

Sintaxe

Lançamento( Endereço [, NomeDoParâmetro1, ValorDoParâmetro1, ... ] )

Endereço – Obrigatório. O endereço de uma página da Web ou a ID de um aplicativo a ser iniciado.
ParameterNames – Opcional. Nome do parâmetro.
ParameterValues – Opcional. Os valores de parâmetro correspondentes a serem passados para o aplicativo ou a página da Web.

Lançamento( Endereço, { [ NomeDoParâmetro1: ValorDoParâmetro1, ... ] } [, DestinoDeLançamento ] )

Endereço – Obrigatório. O endereço de uma página da Web ou a ID de um aplicativo a ser iniciado.
ParameterNames – Opcional. Nome do parâmetro.
ParameterValues – Opcional. Os valores de parâmetro correspondentes a serem passados para o aplicativo ou a página da Web.
LaunchTarget – Opcional. Um valor de enumeração LaunchTarget ou um nome personalizado.

Parâmetro( NomedoParâmetro )

ParameterName - Obrigatório. O nome do parâmetro passado para o aplicativo.

Parâmetros reservados

As seguintes palavras-chave são reservadas (independentemente do uso de maiúsculas e minúsculas) para uso interno e não devem ser usadas como um parâmetro personalizado na função Param():

amp%3Bauthmode
amp%3Benableonbehalfof
amp%3Bhidenavbar
amp%3Blocale
appmetadataversion
authmode
channeltype
cordovapath
correlationid
depurar
delegatelaunchurl
delegatelaunchurl
disablepreviewredirect
embedderorigin
enableonbehalfof
groupid
hideappsplash
hidenavbar
hint
hostclienttype
hostmode
iframecontainerid
isfullscreen
ispreviewmode
loader
loaderType
locale
localização
packagekind
packageproperties
playerresourcespath
playersessionid
powerappslanguage
screencolor
sdkversion
site
skipappmetadata
skipiframecreation
skiplaunchappcache
fonte
sourcetime
standaloneconsent
teamid
teamtype
tenantId
theme
uselocalpackagehostresources
userteamrole

Exemplos

Lançamento simples

De um aplicativo de tela para uma página da Web:

Fórmula	Description
Lançamento( "http://bing.com/search", "q", "Power Apps", "count", 1 )	Abre a página da Web https://bing.com/search?q=Power%20Apps&count=1. Uma nova janela ou guia é aberta.
Lançamento( "http://bing.com/search", { q: "Power Apps", count: 1 } )	O mesmo que os exemplos anteriores usando a notação de registro equivalente. Uma nova janela ou guia é aberta.
Lançamento( "http://bing.com/search", { q: "Power Apps", count: 1 }, LaunchTarget.Replace )	O mesmo que os exemplos anteriores, substituindo a janela ou guia atual pelo resultado, se estiver sendo executado em um navegador da Web.
Lançamento( "http://bing.com/search", { q: "Power Apps", count: 1 }, "Resultados da pesquisa" )	O mesmo que o exemplo anterior, criando ou substituindo o conteúdo da janela ou guia denominada Procurar resultados.

De um aplicativo de tela para um aplicativo de tela

Atualize a ID do aplicativo, o nome da tela e o número do registro, conforme apropriado.

Launch( "/providers/Microsoft.PowerApps/apps/YOUR-APP-ID",
        { Navigate: "Second Screen", Record: 34 }
)

A partir de uma página da Web para um aplicativo de tela

Atualize a ID do aplicativo, o ID do locatário, o nome da tela e o número do registro, conforme apropriado.

<html>
  <body>
    <a
      href="https://apps.powerapps.com/play/e/YOUR-APP-ENVIRONMENT-ID/a/YOUR-APP-ID?tenantId=YOUR-TENANT-ID&Navigate=Second%20Screen&Record=34"
    >
      Launch canvas app
    </a>
  </body>
</html>

Param simples

Exemplos de lançamento simples acima para iniciar o aplicativo de tela da página da Web ou de outro aplicativo de tela mostram exemplos simples para a função Param:

Fórmula	Descrição	Resultado
Param( "Navegar" )	O parâmetro Navigate foi fornecido quando o aplicativo foi iniciado e retornado.	"Segunda tela"
Param( "Registro")	O parâmetro Record foi fornecido quando o aplicativo foi iniciado. Mesmo que tenha sido passado como um número para a função Launch, o resultado de Param será uma sequência de texto que pode ser convertida implícita ou explicitamente em outros tipos.	"34"
Param( "Usuário" )	O parâmetro User não foi fornecido. Um valor em branco é retornado e pode ser testado com a função IsBlank.	em branco

Exemplos passo a passo para Launch e Param

O modelo de layout de tablet Demonstração de Produto foi usado nos exemplos a seguir. Para criar um aplicativo com este modelo, siga as etapas no artigo criar um aplicativo e selecione o modelo Demonstração de Produto. Você também pode usar seu próprio aplicativo.

Exemplo - Launch

Vá para Power Apps.
Selecione Aplicativos no painel de navegação esquerdo.
Selecione o seu aplicativo e, depois, Editar.
Selecione Inserir e, no menu, selecione Rótulo.
Mova o rótulo para a parte inferior direita da tela.
No painel de propriedades à direita, selecione Cor como branco e defina Espessura da borda como 1.
Selecione a propriedade Text do lado direito e insira o texto como Tablets Surface em novidades.
Na lista de propriedades na parte superior esquerda, selecione OnSelect.
Insira a fórmula como Launch("https://www.bing.com/news/search","q","Microsoft Surface tablets"). Você também pode usar outro URL, parâmetro e teclas de sua preferência.
Salve e publique o aplicativo.
Reproduza o aplicativo.
Select label Tablets de superfície em notícias para iniciar a pesquisa de notícias com palavras-chave Microsoft Tablets de superfície.

Dica

Para escalabilidade, você pode substituir as palavras-chave inseridas manualmente na função Launch por variáveis.

Exemplo - Param

Vá para Power Apps.
Selecione Aplicativos no painel de navegação esquerdo.
Selecione o seu aplicativo e, depois, Editar.
Selecione Inserir e, no menu, selecione Rótulo.
Mova o rótulo para a parte inferior direita da tela.
Selecione a propriedade Text para o rótulo do canto superior esquerdo.
Insira a fórmula como Param("browser"). Você também pode usar um parâmetro diferente de sua escolha.
Salve e publique o aplicativo.
Cópia de link da Web para o seu aplicativo de Power Apps.
Abrir um novo navegador.
Cole o link da Web do aplicativo no navegador e acrescente &browser=Microsoft%20Edge no fim.
Quando o aplicativo é iniciado, o rótulo mostra o valor do parâmetro passado.
Feche o reprodutor do aplicativo e edite o aplicativo.
Selecione Aplicativo na visualização em árvore na navegação à esquerda.
Selecione a propriedade StartScreen no canto superior esquerdo.
Insira a fórmula como If( Param("screen") = "techspecs", TechSpecs ).

Se a função na propriedade StartScreen verificar se o parâmetro é igual a um determinado valor, neste caso o valor techspecs. E se corresponder, retorna o controle de tela Especificações técnicas para a propriedade StartScreen.

Observação

Substitua o nome de controle TechSpecs na função If pelo nome de um controle de tela em seu próprio aplicativo, se estiver usando o modelo de aplicativo Demonstração do Produto.
Salve e publique o aplicativo.
Abrir um novo navegador.
Cole o link da Web do aplicativo no navegador e acrescente &screen=techspecs no fim.
O aplicativo é iniciado diretamente com Especificações técnicas como a tela inicial.