Como compartilhar HTML (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]

O compartilhamento de HTML é diferente de outros formatos básicos como texto ou links. O principal desafio consiste no fato de que o conteúdo que um usuário seleciona pode conter referências a outros elementos. Aplicativos que suportam o compartilhamento de HTML precisam considerar como manipular esses referências para garantir que os usuários compartilharão o conteúdo que bem quiserem.

Um conteúdo com texto e imagens demonstra um dos típicos desafios do compartilhamento de HTML. Quando os usuários selecionam esse conteúdo e tocam no botão Share, eles esperam compartilhar o texto e a imagem. Porém, o HTML não contém a imagem, mas uma marca img que aponta para onde está a imagem. Você deve configurar um mapa de recurso, se a referência da imagem não for acessível a um aplicativo de destino, como uma imagem armazenada localmente.

Para lhe ajudar a garantir que você pode compartilhar HTML como os seus usuários esperam, o namespace Windows.ApplicationModel.DataTransfer inclui algumas funções que ajudam a capturar elementos referenciados, tais como imagens. Vamos lhe mostrar como.

O que você precisa saber

Tecnologias

Windows.ApplicationModel.DataTransfer

Pré-requisitos

Você deve estar familiarizado com o Visual Studio e com os modelos a ele associados.
Você deve ter familiaridade com JavaScript.
Você deve saber como usar JavaScript para identificar HTML selecionado por um usuário e a encontrar instâncias de objetos filhos como etiquetas de imagens dentro dessa seleção.

Instruções

Etapa 1: Configurar seu aplicativo como uma origem de compartilhamento

O objeto DataTransferManager é o ponto de partida de qualquer operação de compartilhamento. Adicione um manipulador de eventos DataRequested para disparar quando o usuário desejar chamar a opçã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.

var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();
dataTransferManager.addEventListener("datarequested", shareHtmlHandler);

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

Etapa 2: Obter um objeto DataRequest

Quando ocorre um evento datarequested, o seu aplicativo recebe um objeto DataRequest. Este objeto contém um DataPackage que você pode usar para fornecer o conteúdo que o usuário quer compartilhar.

var request = e.request;

Etapa 3: Definir as propriedades de título e descrição

request.data.properties.title = "Share Html Example";
request.data.properties.description =
    "Demonstrates how to share an HTML fragment with a local image.";

Etapa 4: Usar o método createHtmlFormat para formatar o fragmento

A função createHtmlFormat encapsula o formato HTML com os cabeçalhos e outras informações necessárias para que o sistema compartilhe o conteúdo.

var localImage = "ms-appx:///images/logo.png";
var htmlExample = "<p>Here is a local image: <img src=\"" + localImage + "\">.</p>";
var htmlFormat = 
    Windows.ApplicationModel.DataTransfer.HtmlFormatHelper.createHtmlFormat(htmlExample);

Etapa 5: Adicionar o HTML ao DataPackage

Para adicionar o HTML, use a função setHtmlFormat.

request.data.setHtmlFormat(htmlFormat);

Etapa 6: Criar um RandomAccessStreamReference da imagem local

var streamRef = 
    Windows.Storage.Streams.RandomAccessStreamReference.createFromUri(new Windows.Foundation.Uri(localImage));

Etapa 7: Adicionar o RandomAccessStreamReference ao mapa de recursos

Para adicionar o arquivo de imagem, use a propriedade resourceMap.

request.data.resourceMap[localImage] = streamRef;

Se o fragmento de HTML que está sendo compartilhado tiver várias imagens locais, você precisará repetir esta etapa para cada uma dessas imagens.

Exemplo completo

Aqui está um exemplo de uma função que define HTML do usuário para compartilhamento. Para obter um exemplo mais complexo, consulte a nossa amostra da galeria de código.

function shareHtmlHandler(e) {
    var localImage = "ms-appx:///images/logo.png";
    var htmlExample = "<p>Here is a local image: <img src=\"" + localImage + "\">.</p>";
    var request = e.request;
    request.data.properties.title = "Share Html Example";
    request.data.properties.description = "Demonstrates how to share an HTML fragment with a local image.";
    var htmlFormat = Windows.ApplicationModel.DataTransfer.HtmlFormatHelper.createHtmlFormat(htmlExample);
    request.data.setHtmlFormat(htmlFormat);
    var streamRef = Windows.Storage.Streams.RandomAccessStreamReference.createFromUri(new Windows.Foundation.Uri(localImage));
    request.data.resourceMap[localImage] = streamRef;
}

app.onactivated = function (args) {
    if (args.detail.kind === activation.ActivationKind.launch) {
        if (args.detail.previousExecutionState !== activation.ApplicationExecutionState.terminated) {
            // This app is newly launched; register the app as a share source.
            var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();
            dataTransferManager.addEventListener("datarequested", shareHtmlHandler);
        } else {
            // TODO: This app was reactivated from suspension.
            // Restore the app state here.
        }
        args.setPromise(WinJS.UI.processAll());
    }
};