Início rápido: recebendo conteúdo compartilhado (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]

Este guia de início rápido percorre as etapas necessárias para receber o conteúdo compartilhado de outro aplicativo.

Objetivo: Para saber como receber conteúdo compartilhado.

Pré-requisitos

Para usar o código descrito nesta seção:

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

Instruções

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 que o sistema saiba que o seu aplicativo está disponível para receber conteúdo. Se estiver usando um modelo do Visual Studio para criar seu aplicativo, aqui está como ter suporte para o contrato de Compartilhamento de Destino:

Abra o arquivo de manifesto. Ele deve ser chamado de package.appxmanifest.
Abra a guia Declarações.
Escolha Compartilhar Destino na lista Declarações Disponíveis.

Para saber mais, veja Modelo de item de contrato de Compartilhamento de Destino.

2. Especificar os tipos de arquivo e os formatos de dados que você dá suporte

Como desenvolvedor de aplicativo de destino, você precisa decidir quais tipos de arquivo e formatos de dados deseja dar suporte. Para especificar os tipos de arquivo que você dá suporte:

Abra o arquivo de manifesto.
Na seção Tipos de Arquivos com Suporte da página Declarações, clique em Adicionar novo.
Digite a extensão do nome do arquivo que você deseja dar suporte. Por exemplo, .docx. Você precisa incluir o ponto (.).

Se quiser dar suporte a todos os tipos de arquivos, marque a caixa SupportsAnyFileType.

Para especificar os formatos de dados que você dá suporte:

Abra o arquivo de manifesto.
Na seção Formatos de Dados, clique em Adicionar Novo.
Digite o nome do formato de dados a que você dá suporte. Por exemplo, "Texto".

As APIs de Compartilhamento oferecem suporte a vários formatos padrão, como Texto, HTML e Bitmap. Também é possível especificar tipos de arquivo personalizado e formatos de dados. Se você especificar, lembre-se que os aplicativos de origem precisam conhecer o que são esses tipos e formatos; caso contrário, esses aplicativos não compartilharão dados desse tipo.

3. Manipular a ativação de compartilhamento

Quando um usuário seleciona seu aplicativo, um evento activated do aplicativo é acionado. Seu aplicativo precisa controlar esse evento para processar os dados que o usuário deseja compartilhar. Como existem muitos motivos para um evento activated disparar, a primeira coisa que você precisa fazer é verificar se o motivo para o evento é compartilhar dados.

if (eventObject.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.shareTarget) {
    // Code to handle activation goes here.
}

Os dados que o usuário quer compartilhar estão contidos em um objeto ShareOperation. Você pode usar esse objeto para verificar o formato dos dados que ele contém. Aqui está um exemplo de manipulador de eventos que trata o conteúdo compartilhado no formato de texto simples.

var shareOperation = eventObject.detail.shareOperation;
if (shareOperation.data.contains(Windows.ApplicationModel.DataTransfer.StandardDataFormats.text)) {
    shareOperation.data.getTextAsync().done(function (text) {
            // To output the text using this example, 
            // you need a div tag with an id of "output" in your HTML file.
            document.getElementById("output").innerText = text;
        }, function (e) {
            displayError("Error retrieving Text format: " + e);
        }
    });
}

4. Relatar o status de compartilhamento estendido (para operações mais longas)

Observação

A etapa a seguir somente se aplica aos aplicativos da Windows Store. É possível chamar os métodos de relatório abaixo a partir do Windows Phone 8.1, mas os dados não serão retornados.

Em alguns casos, pode levar algum tempo para seu aplicativo processar os dados que o usuário deseja compartilhar. Chamamos essas instâncias de compartilhamento compartilhamentos estendidos. Exemplos de compartilhamentos estendidos incluem usuários que compartilham conjuntos de arquivos ou imagens. Esses itens são maiores do que uma cadeia de texto simples, por isso demoram mais tempo para processar.

Observação Se o seu aplicativo só pode receber itens simples como texto ou um hiperlink, você pode ignorar esta seção.

Como um aplicativo de destino, seu aplicativo não deve forçar o usuário a consultar a interface do usuário do aplicativo apenas porque ele precisa de mais tempo para manipular dados. Em vez disso, você deve usar o objeto ShareOperation para permitir que o sistema saiba que o aplicativo ainda está funcionando. Dessa forma, o usuário pode sair da interface do usuário do aplicativo e voltar para o que ele estava fazendo. Por enquanto, o aplicativo continua processando os dados no tela de fundo.

shareOperation.reportStarted();

Depois de chamar reportStarted, não espere mais interação do usuário com seu aplicativo. Como resultado, você não deve chamá-lo, a menos que ele esteja em um ponto onde possa ser encerrado pelo usuário.

Com um compartilhamento estendido, é possível que o usuário possa ignorar o aplicativo de origem antes que seu aplicativo tenha todos os dados do objeto DataPackage. Como resultado, recomendamos que o sistema saiba quando o aplicativo adquiriu os dados necessários. Dessa forma, o sistema pode suspender ou terminar o aplicativo de origem conforme necessário.

shareOperation.reportDataRetreived();

Se algo der errado, você também poderá chamar reportError para enviar uma mensagem de erro ao sistema. O usuário verá a mensagem quando verificar o status do compartilhamento. Assim que você chama o reportError seu aplicativo é desligado e o compartilhamento encerrado — o usuário precisará iniciar novamente para compartilhar o mesmo conteúdo para seu aplicativo. Dependendo do cenário, você pode considerar que um determinado erro não é tão sério assim para finalizar a operação de compartilhamento. Nesse caso, opte por não chamar reportError e continue com o compartilhamento.

shareOperation.reportError("Could not reach the server! Try again later.");

Ao usar esses métodos, você costuma chamá-los na ordem descrita e não pode chamá-los mais de uma vez. Porém, tem vezes que um aplicativo de destino pode chamar reportDataRetrieved antes de reportStarted. Por exemplo, o aplicativo pode recuperar os dados como parte de uma tarefa no manipulador de ativação, mas não pode chamar reportStarted até que o usuário clique no botão Compartilhar.

Para ver esse tipo de compartilhamento em ação, veja o nosso exemplo de aplicativo de compartilhamento de destino de conteúdo.

5. Relatar que o compartilhamento foi concluído

Por fim, quando o aplicativo tiver processado o conteúdo compartilhado, você deverá chamar reportCompleted.

shareOperation.reportCompleted();

Depois que o aplicativo relata que o compartilhamento está concluído, o aplicativo é ignorado.

6. Retornar um objeto QuickLink se o compartilhamento foi bem-sucedido

Observação

Os QuickLinks não têm suporte no Windows Phone 8.1. Os aplicativos da Loja do Windows Phone podem receber QuickLinks como parte de uma operação de compartilhamento, mas eles serão automaticamente ignorados.

Quando um usuário seleciona seu aplicativo para receber conteúdo compartilhado, recomendamos que você crie um QuickLink. Um QuickLink é como um atalho que torna mais fácil para os usuários compartilhar informações com seu aplicativo. Por exemplo, seu aplicativo poderá criar um QuickLink que abre uma nova mensagem de email pré-configurada com o endereço de email de um amigo.

Quando um usuário seleciona seu aplicativo para receber conteúdo compartilhado, recomendamos que você crie um QuickLink. Um QuickLink é um atalho que torna mais fácil para os usuários compartilhar informações com seu aplicativo. Por exemplo, seu aplicativo poderá criar um QuickLink que abre uma nova mensagem de email pré-configurada com o endereço de email de um amigo.

Um QuickLink deve ter um título, um ícone e uma ID. O título (como "Email Mom") e o ícone aparecem quando o usuário toca no botão Compartilhar. A ID é o que seu aplicativo usa para identificar qual QuickLink foi escolhido. Quando o seu aplicativo cria um QuickLink, o aplicativo retorna o QuickLink ao sistema chamando o método reportCompleted do objeto ShareOperation. Aqui está um exemplo:

function reportCompleted() {
    var quickLink = new Windows.ApplicationModel.DataTransfer.ShareTarget.QuickLink();
    quickLink.id = "123456789";
    quickLink.title = id("quickLinkTitle").value;

    // For quicklinks, the supported FileTypes and DataFormats are set independently from the manifest.
    var dataFormats = Windows.ApplicationModel.DataTransfer.StandardDataFormats;
    quickLink.supportedFileTypes.replaceAll(["*"]);
    quickLink.supportedDataFormats.replaceAll([dataFormats.text, dataFormats.uri, dataFormats.bitmap, 
        dataFormats.storageItems, dataFormats.html, customFormatName]);

    Windows.ApplicationModel.Package.current.installedLocation.getFileAsync("images\\user.png").then(function (iconFile) {
        quickLink.thumbnail = Windows.Storage.Streams.RandomAccessStreamReference.createFromFile(iconFile);
        shareOperation.reportCompleted(quickLink);
    });
}

Lembre-se que seu aplicativo é responsável por armazenar a ID do QuickLink e os dados de usuário correspondentes. Quando o usuário toca no QuickLink, você pode obter sua ID por meio da propriedade ShareOperation.quickLinkId. Quando um compartilhamento para um QuickLink é bem-sucedido, você deve retornar o mesmo QuickLink quando chamar reportCompleted.

Resumo e próximas etapas

Agora, você deve ter uma boa noção de como receber conteúdo compartilhado e como criar um QuickLink para ajudar usuários a compartilhar conteúdo com seu aplicativo.

Para saber mais, ou para obter exemplos mais específicos de como adicionar o compartilhamento ao seu aplicativo, talvez você queira dar uma olhada em:

Observação Depurar um aplicativo de destino de compartilhamento é diferente de depurar outros tipos de aplicativos. Para saber mais, veja Diretrizes para depurar aplicativos de destino.