Como receber um link (HTML)

Artigo
12/12/2015

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

Links são uma forma comum de dados que os usuários gostam de compartilhar. Às vezes, o usuário compartilha um link diretamente (como é o caso de um artigo em um site). O suporte a links também é útil como opção secundária quando usuários estiverem compartilhando HTML ou conteúdo que pode estar disponível on-line.

Este tópico mostra como receber um único link que está sendo compartilhado por um aplicativo de origem.

O que você precisa saber

Tecnologias

Pré-requisitos

Você deve estar familiarizado com o Visual Studio e com os modelos a ele associados.
Você deve ter familiaridade com JavaScript.

Instruções

Etapa 1: Suporte o contrato de Compartilhamento

Antes que seu aplicativo possa receber conteúdo compartilhado, você tem que declarar que ele suporta o contrato de Compartilhamento. Esse contrato permite, essencialmente, que o sistema saiba que o seu aplicativo está disponível para receber conteúdo. Se estiver usando um modelo do Microsoft Visual Studio para criar seu aplicativo, aqui está como ter suporte para o contrato de Compartilhamento de Destino:

Abra o arquivo de manifesto (package.manifest) na exibição do designer.
Abra a guia Declarações.
Escolha Compartilhar Destino na lista Declarações Disponíveis.
Clique em Adicionar para adicionar suporte ao contrato de Compartilhamento de Destino em seu aplicativo.

Etapa 2: Especificar que o seu aplicativo suporta links

Para suportar links, você precisa especificar que o seu aplicativo suporta o formato URI:

Abra arquivo de manifesto.
Na seção Formatos de dados, clique em Adicionar novo.
Digite "texto" (sem aspas).

As etapas anteriores adicionam a seguinte seção ao manifesto:

<Extensions>
  <Extension Category="windows.shareTarget">
    <ShareTarget>
      <DataFormat>uri</DataFormat>
    </ShareTarget>
  </Extension>
</Extensions>

Observação Você pode especificar um ponto de entrada diferente quando seu aplicativo for ativado para o contrato de Compartilhamento de Destino. Para fazer isso, modifique a entrada da página Iniciarna seção de configurações do Aplicativoda declaração do Destino de Compartilhamento no manifesto do pacote. É altamente recomendável que você também use um arquivo JavaScript separado que cuide da ativação desta página. Por exemplo, dê uma olhada em Exemplo de aplicativo de compartilhamento de destino de conteúdo.

Etapa 3: Adicione um manipulador de eventos para detectar quando o seu aplicativo é ativado.

Quando um usuário seleciona o seu aplicativo para compartilhar conteúdo, o sistema ativa o aplicativo. Como existem muitas maneiras disso acontecer, você precisa adicionar o código a seu manipulador de eventos que detecta o motivo pelo qual ocorreu a ativação. Você pode fazer isso verificando o valor da propriedade kind.

app.onactivated = function (args) {
    if (args.detail.kind === activation.ActivationKind.launch) {
        // The application has been launched. Initialize as appropriate.
    } else if (args.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.shareTarget) {
        ...
    }
};

Se você usar uma página de início dedicada para o contrato de Compartilhamento de Destino, você pode ignorar a verificação da propriedade kind

Etapa 4: Obtenha o objeto ShareOperation.

O objeto ShareOperation contém todos os dados necessários para que o seu aplicativo obtenha o conteúdo que o seu usuário quiser compartilhar.

shareOperation = args.detail.shareOperation;

Etapa 5: Retorne do manipulador de eventos ativados rapidamente.

O manipulador de eventos activated deve retornar rapidamente. Coloque na fila um evento assíncrono a partir do manipulador de eventos activated dessa forma, o processamento de compartilhamento dedados ocorre depois que o evento ativado retorna.

WinJS.Application.addEventListener("shareready", shareReady, false);
WinJS.Application.queueEvent({ type: "shareready" });

As demais etapas destinam-se à implementação da função shareReady.

Etapa 6: Verifique se DataPackageView contém um URI.

O objeto ShareOperation contém um objeto DataPackageView. Esse objeto é uma versão apenas leitura do objeto DataPackage que o aplicativo de origem usou para criar os dados. Use esse objeto para verificar se o conteúdo que está sendo compartilhado contém um link.

if (shareOperation.data.contains(Windows.ApplicationModel.DataTransfer.StandardDataFormats.uri)) {
    // Code to process URI goes here.
}

Verificar se o DataPackage contém o formato de dados em que você está interessado é uma prática recomendada, mesmo se o seu aplicativo aceitar somente um formato. Isso facilita o suporte futuro a outros tipos de formatos de dados e formatos de arquivos.

Etapa 7: Processe o link.

Para obter o URI, chame o método DataPackageView.getUriAsync.

shareOperation.data.getUriAsync().then(function (uri) {
    if (uri != null) {
        // In this sample, we only display the URI. To output the link using this example, 
        // you need a div tag with an id of "output" in your HTML file.
        // In your app, replace this with whatever is appropriate for your scenario.
        document.getElementById("output").innerText = uri.absoluteUri;
    }
});

Etapa 8: Chame reportCompleted.

Depois que o aplicativo concluir com sucesso o compartilhamento do conteúdo, chame reportCompleted. Depois que você chamar este método, o sistema ignora seu aplicativo.

shareOperation.reportCompleted();

Comentários

Alguns aplicativos podem incluir um URI (Uniform Resource Identifier) que não começa com http:// ou https://. Por exemplo, um aplicativo de origem pode incluir um protocolo de ativação que leva o usuário diretamente ao conteúdo no próprio aplicativo. Se o aplicativo já aceitar qualquer URI, você obterá essa funcionalidade por padrão. Se o aplicativo for limitado a somente determinados tipos de URIs, você deve considerar o seguinte:

Se você der suporte a HTML, use o HTML fornecido em DataPackage.
Se você não der suporte à HTML, mas der suporte a texto, use o texto no DataPackage.
Se nenhuma das opções anteriores funcionar, considere exibir uma mensagem que informe ao usuário que você não dá suporte ao URI específico.

Em todos os casos, tente incorporar o título e a descrição dos dados em sua experiência. Isso dá ao usuário mais contexto acerca do que está sendo compartilhado.

Dê uma olhada em nosso exemplo de código Exemplo de aplicativo de compartilhamento de destino de conteúdo para ver a experiência ponta a ponta inteira de um aplicativo que recebe uma imagem como parte do compartilhamento.

Exemplo completo

var shareOperation = null;

function shareReady(args) {
    if (shareOperation.data.contains(Windows.ApplicationModel.DataTransfer.StandardDataFormats.uri)) {
        shareOperation.data.getUriAsync().done(function (uri) {
            // In this sample, we only display the URI. To output the link using this example, 
            // you need a div tag with an id of "output" in your HTML file.
            // In your app, replace this with whatever is appropriate for your scenario.
            document.getElementById("output").innerText = "Uri: " + uri.absoluteUri;
        });
    }
}

app.onactivated = function (args) {
    if (args.detail.kind === activation.ActivationKind.launch) {
        // The app was launced. Initialize as appropriate.
        args.setPromise(WinJS.UI.processAll());
    } else if (args.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.shareTarget) {
        // This app was been activated for the Share contract
        args.setPromise(WinJS.UI.processAll());

        // We receive the ShareOperation object as part of the eventArgs
        shareOperation = args.detail.shareOperation;


        // We queue an asychronous event so that working with the ShareOperation 
        // object does not block or delay the return of the activation handler.
        WinJS.Application.addEventListener("shareready", shareReady, false);
        WinJS.Application.queueEvent({ type: "shareready" });
    }
};