Guia de início rápido: compartilhando conteúdo (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]

Aplicativos bem-sucedidos permitem que os usuários compartilhem facilmente o que estão fazendo com amigos e com familiares. Aplicativos que facilitam o compartilhamento de conteúdo de usuários costumam ser mais conhecidos, e isso encoraja os usuários a usá-los mais frequentemente.

Para aprender a usar essas APIs, continue lendo. Se você tiver mais interesse em aprender como o seu aplicativo pode receber conteúdo compartilhado, consulte Guia de início rápido: recebendo conteúdo compartilhado.

Objetivo: Ao concluir a leitura deste guia de início rápido, você deverá ter uma boa ideia de como compartilhar conteúdo.

Pré-requisitos

Você deve estar familiarizado com o Visual Studio e com os modelos respectivos.
Você deve estar familiarizado com o desenvolvimento em HTML e JavaScript.

Instruções

Escolhendo formatos de dados

O núcleo de qualquer operação de compartilhamento é o objeto DataPackage. Esse objeto contém os dados que o usuário deseja compartilhar. Os tipos de conteúdo que um DataPackage pode conter incluem:

Texto simples
URIs (Uniform Resource Identifiers)
HTML
Texto formatado
Bitmaps
Arquivos
Dados definidos pelo desenvolvedor

Um objeto DataPackage pode conter um ou mais desses formatos, em qualquer combinação. Além disso, um DataPackage pode conter um delegado — uma função que é chamada quando o aplicativo de recebimento solicita dados. Recomendamos o uso de delegados sempre que os dados que o usuário quer compartilhar fizerem uso intensivo dos recursos, dado que um delegado pode ajudar o seu aplicativo a compartilhar dados com mais eficiência.

Escolhendo propriedades

Ao empacotar dados para compartilhamento, você tem a opção de fornecer uma variedade de propriedades que dão informações adicionais sobre o conteúdo compartilhado. Tirar proveito dessas propriedades pode ajudar os aplicativos de destino a melhorarem a experiência do usuário. Por exemplo, fornecer um título e uma descrição que transmitem o que o usuário está compartilhando pode ajudar quando o usuário estiver compartilhando conteúdo com mais de um aplicativo. A adição de uma miniatura ao compartilhar uma imagem ou um link para uma página da Web pode fornecer uma referência visual ao usuário. Para obter mais informações sobre quais propriedades estão disponíveis para uso, consulte nossa documentação sobre o DataPackage.DataPackagePropertySet.

Configurando sua origem de compartilhamento

Para configurar seu aplicativo como um aplicativo de origem de compartilhamento, você primeiramente precisa obter a instância da classe DataTransferManager que foi atribuída à janela atual.

var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();

Essa classe suporta um evento DataRequested que é disparado quando um usuário quiser chamar a função Compartilhar. Em um aplicativo da Windows Store, isso ocorre automaticamente quando o usuário chamar o botão Compartilhar. Se estiver desenvolvendo para Windows Phone, não haverá botão Compartilhar interno, portanto você precisará adicionar um controle para o usuário tocar e disparar o manipulador.

dataTransferManager.addEventListener("datarequested", function (e) {
    // Code to handle event goes here.
});

O exemplo anterior registra um manipulador de eventos que é chamado sempre que é disparado um evento datarequested. O manipulador recebe um objeto DataRequest que seu aplicativo usa para definir dados que o usuário deseja compartilhar a partir de seu aplicativo de origem de compartilhamento.

Qualquer conteúdo compartilhado deve conter duas propriedades: um título e o conteúdo em si. Além disso, também recomendamos que você inclua uma propriedade de descrição para esclarecer melhor.

O código a seguir se baseia nos exemplos anterior e mostra como compartilhar texto simples com um aplicativo de destino.

function registerForShare() {
    var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();
    dataTransferManager.addEventListener("datarequested", shareTextHandler);
}

function shareTextHandler(e) {
    var request = e.request;
    request.data.properties.title = "Share Text Example";
    request.data.properties.description = "Demonstrates how to share text.";
    request.data.setText("Hello World!");
}

Compartilhamento e delegados

Às vezes, não é desejável preparar dados imediatamente quando o usuário solicita compartilhamento. Por exemplo, se o seu aplicativo dá suporte a vários formatos de dados diferentes, não é eficiente criar todos os formatos imediatamente. É melhor esperar até o aplicativo de destino especificar o formato desejado e, então, gerar somente os dados solicitados. Para isso, configure o objeto DataPackage para preencher somente os dados necessário por meio de uma chamada de representante mediante solicitação.

request.data.setDataProvider(Windows.ApplicationModel.DataTransfer.StandardDataFormats.bitmap, onDeferredImageRequested);

Para saber mais detalhes sobre este tipo de compartilhamento, dê uma olhada em Como compartilhar arquivos.

Solicitando o painel de compartilhamento programaticamente

Após definir o conteúdo a ser compartilhado, você pode seguir adiante. Basta que o usuário selecione o aplicativo para receber o conteúdo. Para aquelas situações em que usar um botão não é o ideal — como ao compartilhar o placar de um jogo — você também pode iniciar programaticamente o botão Compartilhar.

Observação

A Charms bar não existe no Windows Phone 8.1, por isso será necessário incluir a opção de compartilhamento de forma programática. Ela pode ser acessada sempre como parte da barra de aplicativos ou estar associada a um controle específico em uma determinada página.

function showShareUI() {
    Windows.ApplicationModel.DataTransfer.DataTransferManager.showShareUI();
}

Erros de manipulação e outros problemas

Na maioria dos casos, fornecer conteúdo é um processo simples e direto. Entretanto, há situações em que seu aplicativo pode não conseguir compartilhar. Para lhe ajudar a lidar com essas situações no Windows 8.1, o objeto DataRequest suporta um método FailWithDisplayText. Use este método para exibir uma mensagem de texto para o usuário, caso ele não consiga compartilhar a partir de um modo de exibição específico ou precise executar etapas adicionais antes de compartilhar. Por exemplo, o aplicativo pode exigir que o usuário selecione conteúdo para compartilhamento, mas o usuário não faz essa seleção.

Resumo e próximas etapas

Agora você deve ter uma boa compreensão de como compartilhar os trabalhos.

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

Tópicos relacionados

Escolhendo formatos de dados para compartilhamento

Diretrizes e lista de verificação para conteúdo de compartilhamento

Início rápido: recebendo conteúdo compartilhado