Funções Launch e Param

Artigo
10/16/2024

Aplica-se a: Aplicativos de tela

Inicia uma página Web ou uma aplicação de tela e fornece acesso aos parâmetros de iniciação.

Launch

Lança uma página Web ou uma aplicação de tela. A função suporta:

Address (required), o URL da página da Web do aplicativo de tela.
Parâmetros (opcional), valores nomeados para passar para a página da Web ou aplicativo de tela. Numa aplicação de tela, os parâmetros podem ser lidos com a função Param.
Target (opcional), a guia do navegador na qual iniciar a página da Web ou o aplicativo de tela.

A inicialização só pode ser usada em fórmulas de comportamento.

Nota

Se a fórmula Iniciar for utilizada para abrir o Power Apps e a aplicação não estiver visível para o utilizador final, é recomendado que verifique se a aplicação está bloqueada por um bloqueador de janelas de pop-up do browser ou se o browser está a aguardar a resposta do utilizador a uma caixa de diálogo que pergunta se pretende navegar para um novo ecrã.

Morada

As páginas Web são iniciadas através de um endereço URL. Por exemplo:

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

Pode iniciar aplicações de tela com Ligação Web ou URL da Aplicação (ID de aplicação com prefixo com /providers/Microsoft.PowerApps/apps/). Para localizar estes valores para uma aplicação:

Aceder a Power Apps.
Selecione Aplicações no painel de navegação esquerdo.
Selecione a sua aplicação.
Selecione Detalhes no menu superior.
Também pode selecionar ... (Mais Comandos) e, em seguida, selecionar Detalhes no menu pendente.
Copiar ligação Web.

A Ligação Web pode ser utilizada em qualquer página Web e iniciará a aplicação de tela. Também pode ser utilizado com a função Launch. Por exemplo:

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

As aplicações nativas num dispositivo não podem ser iniciadas diretamente. Poderão estar disponíveis opções indiretas em algumas plataformas, como uma aplicação nativa a instalar um esquema de URL personalizado ou a registar no browser para oferecer uma opção para Web sites específicos.

Parâmetros

A inicialização pode passar parâmetros para a página da Web ou o aplicativo de tela. Os parâmetros pode ser fornecidos de duas maneiras:

Uma lista de argumentos de pares nome-valor. Por exemplo:

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

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

O endereço e os parâmetros são codificados no URL antes de serem transmitidos para substituir determinados caracteres não alfanuméricos com % e um número hexadecimal como se a função EncodeUrl tivesse sido utilizada em cada um.

Quando inicia uma página Web, uma cadeia de consulta de parâmetros pode ser incluída no final do endereço URL. Quaisquer parâmetros adicionais fornecidos para Launch serão adicionados ao final da cadeia de consulta. As cadeias de consulta não funcionam quando iniciam uma aplicação de tela.

Quando inicia uma aplicação num dispositivo móvel onde essa aplicação já está em execução, os parâmetros não serão atualizados na aplicação em execução. É necessário recarregar a aplicação para que os parâmetros sejam atualizados.

Destino

Utilize o argumento LaunchTarget para especificar a janela de browser de destino onde abrir a página Web ou a aplicação. Utilize um dos seguintes valores de enumeração LaunchTarget ou forneça um nome de janela personalizada.

Enumeração LaunchTarget	Descrição
Novo	A página Web ou a aplicação é aberta numa nova janela ou separador.
Substituir	A página Web ou a aplicação substitui a janela ou separador atual.
Designação	Em vez de um valor de enumeração, utilize a sua própria cadeia de texto para atribuir um nome à janela ou ao separador. Self é um nome exclusivamente interno que é utilizado apenas pela função Launch. Não tem qualquer impacto nem corresponderá ao título da janela que os seus utilizadores veem. Se já existir uma janela ou um separador com o nome fornecido, o respetivo conteúdo será substituído. Caso contrário, será criado um novo separador ou janela. name não pode começar com o caráter de sublinhado "_".

Novo é o enumeração padrão ao executar em um navegador da Web com Substituir e nomear como opções disponíveis. Num leitor móvel, Novo é a predefinição para páginas Web com nomear como a opção disponível; enquanto a atual aplicação de tela será sempre substituída por outra aplicação de tela.

Nota

A utilização de um LaunchTarget com qualquer valor que não o Novo em cenários incorporados (por exemplo, Power BI ou SharePoint) não é suportada e pode resultar em comportamentos inesperados. No futuro, este comportamento pode mudar ou causar um erro.

Param

A função Param obtém um parâmetro transmitido à aplicação quando esta foi iniciada. Se o parâmetro nomeado não tiver sido transmitido, Param devolverá um valor blank.

Ao iniciar uma aplicação de teça a partir de outra aplicação de tela, utilize os argumentos de Parameter para a função Launch. Os nomes e os valores dos parâmetros serão codificados num URL automaticamente.
Ao iniciar uma aplicação de tela a partir de uma página Web, adicione parâmetros à cadeia de consulta da ligação Web da aplicação de tela. Isto envolve adicionar &parametername=parametervalue, pressupondo que a cadeia de consulta já tenha sido iniciada para o tenantId. Por exemplo, adicionar &First%20Name=Vicki&category=3 transmitiria dois parâmetros: First Name com um valor de "Vicki" e category com um valor de "3" (o tipo de valor é text). O nome e o valor do parâmetro têm de ser codificados por URL se contiverem espaços ou caracteres especiais, semelhante a utilizar a função EncodeURL.
Os nomes de parâmetros são sensíveis a maiúsculas e minúsculas.
Os nomes de parâmetros e os valores serão decodificados por URL automaticamente para utilização na sua aplicação.
Os valores dos parâmetros não são alterados, a menos que a aplicação seja recarregada. Utilizar Iniciar num dispositivo móvel onde a aplicação já está em execução não atualiza os parâmetros.
Mesmo que o parâmetro contenha um número, o tipo devolvido por Param será sempre uma cadeia de texto. A conversão para outros tipos irá ocorrer automaticamente ou utilizará conversões explícitas, tais como a função Value para converter explicitamente para um número.

Nota

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

Sintaxe

Launch(Endereço[,ParameterName1,ParameterValue1 , ... ] )

Endereço – Obrigatório. O endereço de uma página Web ou o ID de uma aplicação a iniciar.
ParameterNames – Opcional. Nome do parâmetro.
ParameterValues – Opcional. Os valores de parâmetros correspondentes a transmitir à aplicação ou à página Web.

Launch(Endereço,[ParameterName1:ParameterValue1 , ... ] { } [, LaunchTarget ] )

Endereço – Obrigatório. O endereço de uma página Web ou o ID de uma aplicação a iniciar.
ParameterNames – Opcional. Nome do parâmetro.
ParameterValues – Opcional. Os valores de parâmetros correspondentes a transmitir à aplicação ou à página Web.
LaunchTarget – Opcional. Um valor de enumeração LaunchTarget ou um nome personalizado.

Param( ParameterName )

ParameterName - Obrigatório. O nome do parâmetro transmitido à aplicação.

Parâmetros reservados

As seguintes palavras-chave estão reservadas (independentemente do caso) para utilização interna e não devem ser utilizadas como 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
origem
sourcetime
standaloneconsent
teamid
teamtype
tenantId
theme
uselocalpackagehostresources
userteamrole

Exemplos

Lançamento Simples

De uma aplicação de tela para uma página Web:

Fórmula	Descrição
Lançamento( "http://bing.com/search", "q", "Power Apps", "count", 1 )	Abre a página web https://bing.com/search?q=Power%20Apps&count=1. É aberta uma nova janela ou separador.
Lançamento( "http://bing.com/search", { q: "Power Apps", count: 1 } )	O mesmo que os exemplos anteriores ao utilizar a notação de registo equivalente. É aberta uma nova janela ou separador.
Lançamento( "http://bing.com/search", { q: "Power Apps", count: 1 }, LaunchTarget.Replace )	O mesmo que nos exemplos anteriores ao substituir a janela ou o separador real com o resultado se estiver a executar num browser.
Lançamento( "http://bing.com/search", { q: "Power Apps", count: 1 }, "Resultados da Pesquisa" )	O mesmo que o exemplo anterior, criar ou substituir o conteúdo da janela ou do separador denominado Resultados da Pesquisa.

De uma aplicação de tela para uma aplicação de tela

Atualize o ID da aplicação, o nome do ecrã e o número de registo, conforme adequado.

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

De uma aplicação Web para uma aplicação de tela

Atualize o ID da aplicação, o ID do inquilino, o nome do ecrã e o número de registo, conforme adequado.

<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>

Parâmetro Simples

Os exemplos de inicialização simples acima para iniciar a aplicação de tela a partir de página Web ou a partir de outra aplicação de tela mostram exemplos simples para a função Param:

Fórmula	Descrição	Resultado
Param( "Navigate" )	O parâmetro Navigate foi fornecido quando a aplicação foi iniciada e devolvida.	"Segundo Ecrã"
Param( "Record" )	O parâmetro Record foi fornecido quando a aplicação foi iniciada. Apesar de ter sido transmitido como número para a função Launch, o resultado de Param será uma cadeia de texto que pode ser convertida implícita ou explicitamente para outros tipos.	"34"
Param( "Usuário" )	O parâmetro User não foi fornecido. É devolvido um valor blank que pode ser testado com a função IsBlank.	em branco

Exemplos Passo a Passo para Launch e Param

O modelo de esquema de tablet Demonstração de Produtos foi utilizado para os exemplos seguintes. Para criar uma aplicação com este modelo, siga os passos de criar uma aplicação e selecione o modelo Demonstração de Produtos. Também pode utilizar a sua própria aplicação.

Exemplo - Launch

Aceder a Power Apps.
Selecione Aplicações no painel de navegação esquerdo.
Selecione a sua aplicação e, em seguida, selecione Editar.
Selecione Inserir a partir do menu e selecione Etiqueta.
Mova a etiqueta para a parte inferior direita do ecrã.
No painel de propriedades no lado direito, selecione Cor como branco e defina a Espessura do limite como 1.
Selecione a propriedade Text do lado direito e introduza texto como Tablets Surface nas notícias.
Na lista de propriedades na parte superior esquerda, selecione OnSelect.
Introduza a fórmula como Launch("https://www.bing.com/news/search","q","Microsoft Surface tablets"). Também pode utilizar qualquer outro URL, parâmetro ou palavras chave que pretender.
Guarde e publique a aplicação.
Executar a aplicação.
Selecione a etiqueta Tablets Surface em notícias para iniciar a pesquisa de notícias com palavras-chave Microsoft Tablets Surface.

Sugestão

Para a escalabilidade, pode substituir as palavras chave inseridas manualmente na função Launch com variáveis.

Exemplo - Param

Aceder a Power Apps.
Selecione Aplicações no painel de navegação esquerdo.
Selecione a sua aplicação e, em seguida, selecione Editar.
Selecione Inserir a partir do menu e selecione Etiqueta.
Mova a etiqueta para a parte inferior direita do ecrã.
Selecione a propriedade Text para a etiqueta na parte superior esquerda.
Introduza a fórmula como Param("browser"). Também pode utilizar um parâmetro diferente à sua escolha.
Guarde e publique a aplicação.
Copie a ligação Web para a sua aplicação a partir do Power Apps.
Abra um novo browser.
Cole a ligação Web da aplicação no browser e acrescente &browser=Microsoft%20Edge no final.
Quando a aplicação é iniciada, a etiqueta mostra o valor do parâmetro transmitido.
Feche o leitor de aplicações e edite a aplicação.
Selecione Aplicação na vista de árvore na navegação esquerda.
Selecione a propriedade StartScreen na parte superior esquerda.
Introduza a fórmula como If( Param("screen") = "techspecs", TechSpecs ).

Se a função na propriedade StartScreen verifica se o parâmetro é igual a um determinado valor, neste caso o valor techspecs. Se corresponder, devolve o controlo de ecrã TechSpecs à propriedade StartScreen.

Nota

Substitua o nome do controlo TechSpecs na função If com o nome de um controlo de ecrã na sua própria aplicação se não estiver a utilizar o modelo de aplicação Demonstração de Produtos.
Guarde e publique a aplicação.
Abra um novo browser.
Cole a ligação Web da aplicação no browser e acrescente &screen=techspecs no final.
A aplicação inicia diretamente com TechSpecs como o ecrã inicial.