Como iniciar o aplicativo padrão para um URI (HTML)

[ Este artigo destina-se aos desenvolvedores do Windows 8.x e do Windows Phone 8.x que escrevem aplicativos do Windows Runtime. Se você estiver desenvolvendo para o Windows 10, consulte documentação mais recente]

Saiba como iniciar o aplicativo padrão para um URI (Uniform Resource Identifier ). Os URIs permitem que você inicie outro aplicativo no sistema operacional para executar uma tarefa específica. Por exemplo, para permitir que um usuário envie um email para um contato em seu aplicativo, você pode usar o URI mailto: para iniciar o aplicativo de email padrão do usuário.

Essas etapas mostram como usar a API Windows.System.Launcher para iniciar o manipulador padrão para um URI.

Instruções

Etapa 1: Criar o URI

Crie um objeto Windows.Foundation.Uri para iniciar o URI. O URI usa o nome de esquema http.

// The URI to launch
var uriToLaunch = "https://www.bing.com";

// Create a Uri object from a URI string 
var uri = new Windows.Foundation.Uri(uriToLaunch);

Etapa 2: Iniciar o URI

O sistema operacional fornece várias opções diferentes para iniciar o manipulador padrão para um URI. Essas opções estão descritas neste gráfico e nas seções que seguem.

Estes exemplos usam o método Windows.System.Launcher.launchUriAsync para iniciar o URI. Trata-se de um método sobrecarregado.

Default launch

Chame o método Windows.System.Launcher.launchUriAsync(Uri) para iniciar o URI criado na etapa 1 usando o aplicativo padrão para o URI http.

// Launch the URI
Windows.System.Launcher.launchUriAsync(uri).then(   
   function (success) {
      if (success) {
        // URI launched
      } else {
        // URI launch failed
      }
   });

Launch with a warning dialog

Chame o método Windows.System.Launcher.launchUriAsync(Uri, LauncherOptions) para iniciar o URI criado na etapa 1 com um aviso. Use a propriedade treatAsUntrusted para indicar se o sistema operacional exibe um aviso.

Observação  

Chame preventDefault em seu manipulador de eventos se a propriedade treatAsUntrusted estiver definida e você estiver usando um elemento a para ativar o URI.

function linkClickHandler(eventInfo) {
    var link = eventInfo.target;
    if (eventInfo.srcElement && (
        (eventInfo.type === "click") ||
        (eventInfo.type === "keydown" && (
        eventInfo.keyCode === WinJS.Utilities.Key.enter ||
        eventInfo.keyCode === WinJS.Utilities.Key.space)))) {
        eventInfo.preventDefault();
        if (link.href.indexOf("ms-appx") > -1) {
            WinJS.Navigation.navigate(link.href);
        }
        else if (link.href.indexOf("http") > -1) {
            // Create a Uri object from a URI string 
            var uri = new Windows.Foundation.Uri(link.href);
            var options = new Windows.System.LauncherOptions();
            // Launch the URI with a warning prompt
            options.treatAsUntrusted = true;
            // Launch the URI
            Windows.System.Launcher.launchUriAsync(uri, options).then(
                function (success) {
                    if (success) {
                        // URI launched
                    } else {
                        // URI launch failed
                    }
                });
        }
    }
}

Launch with a recommended app fallback

Em alguns casos, pode ser que o usuário não tenha um aplicativo instalado para manipular o URI que você está iniciando. Por padrão, nesses casos, o sistema operacional oferece ao usuário um link para pesquisar o aplicativo apropriado na loja. Se você quiser dar ao usuário uma recomendação específica sobre qual aplicativo deve ser adquirido nesse cenário, pode transmitir tal recomendação junto com o arquivo que você está iniciando. Para fazer isso, chame o método Windows.System.Launcher.LaunchUriAsync(Uri, LauncherOptions) com LauncherOptions.preferredApplicationPackageFamilyName definido com o nome da família do pacote do aplicativo na Loja que você deseja recomendar. Em seguida, defina LauncherOptions.preferredApplicationDisplayName como o nome desse aplicativo. O sistema operacional usará essas informações para substituir a opção geral de pesquisar um aplicativo na loja por uma opção específica para adquirir o aplicativo recomendado na loja.

Observação  Defina ambas essas opções para recomendar um aplicativo. Se você definir uma opção sem a outra, haverá falha.

// Set the recommended app.
var options = new Windows.System.LauncherOptions();
options.preferredApplicationPackageFamilyName = "Contoso.URIApp_8wknc82po1e";
options.preferredApplicationDisplayName = "Contoso URI App";

// Launch the URI and pass in the recommended app 
// in case the user has no apps installed to handle the URI
Windows.System.Launcher.launchUriAsync(uri, options).then(
   function (success) {
      if (success) {
        // Uri launched
      } else {
        // Uri launch failed
      }
   });

Iniciar com um Modo de Exibição Restante Desejado (somente Windows)

Aplicativos de origem que chamam LaunchUriAsync podem solicitar que eles permaneçam na tela após a inicialização de um arquivo. Por padrão, o Windows tenta dividir todo o espaço disponível igualmente entre o aplicativo de origem e o aplicativo de destino que manipula o URI. Aplicativos de origem podem usar a propriedade DesiredRemainingView para indicar ao sistema operacional que eles preferem que sua janela de aplicativo ocupe mais ou menos espaço disponível. DesiredRemainingView também pode ser usado para indicar que o aplicativo de origem não precisa permanecer na tela depois da inicialização do URI e pode ser completamente substituído pelo aplicativo de destino. Esta propriedade especifica somente o tamanho da janela preferido do aplicativo de chamada. Ele não especifica o comportamento de outros aplicativos que podem acontecer de também estar na tela ao mesmo tempo.

Observação  O Windows leva em conta vários fatores diferentes ao determinar o tamanho da janela final do aplicativo de origem, por exemplo, a preferência do aplicativo de origem, o número de aplicativos na tela, a orientação da tela e assim por diante. Definindo DesiredRemainingView, você não garante um comportamento de janelas específico para o aplicativo de origem.

Windows 8.1: LauncherOptions.DesiredRemainingView não é suportado até o Windows 8.1 e Windows Server 2012 R2.

Windows Phone: LauncherOptions.DesiredRemainingView não é suportado no Windows Phone.

// Launch the URI with a desired remaining view
var options = new Windows.System.LauncherOptions();
options.desiredRemainingView = Windows.UI.ViewManagement.ViewSizePreference.useLess;

Windows.System.Launcher.launchUriAsync(uri, options).then(
   function (success) {
      if (success) {
        // URI launched
      } else {
        // URI launch failed
      }
   });

Comentários

Seu aplicativo não pode selecionar o aplicativo que foi iniciado. O usuário determina o aplicativo que é inicializado. O usuário pode selecionar um aplicativo da Windows Store ou um aplicativo de área de trabalho.

Ao iniciar um URI, seu aplicativo deve estar em primeiro plano, ou seja, deve estar visível para o usuário. Essa exigência ajuda a garantir que o usuário permaneça no controle. Para que essa exigência seja atendida, você deve vincular todas as inicializações de URI diretamente à interface do usuário do seu aplicativo. O usuário sempre deve executar alguma ação para iniciar uma inicialização de URI. Se você tentar iniciar um URI e seu aplicativo não estiver em primeiro plano, a inicialização falhará e o retorno de chamada de erro será invocado.

Você deve especificar a funcionalidade privateNetworkClientServer para iniciar URIs de intranet, por exemplo, um URI file:/// que aponta para um local de rede.

Você não deve usar este método para iniciar um URI na zona local. Por exemplo, os aplicativos não podem usar o URI file:/// para acessar arquivos no dispositivo local. Em vez disso, você deve usar Storage APIs para acessar arquivos. Se você tentar iniciar um URI de intranet sem a funcionalidade correta, ou um URI de zona local, a inicialização falhará e o retorno de chamada de erro será invocado.

Exemplo completo

Consulte Amostra de lançamento de associação (Windows).

Tópicos relacionados

Tarefas

Como manipular a ativação de protocolos

Como iniciar o aplicativo padrão para um arquivo

Diretrizes

Diretrizes e lista de verificação para tipos de arquivos e URIs

Referência

Windows.System.Launcher.launchUriAsync