Escolhendo formatos de dados para compartilhamento (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]

Esteja você escrevendo um aplicativo de origem, que ajuda os usuários a compartilharem o conteúdo, ou um aplicativo de destino, que recebe esse conteúdo, reserve um tempo e analise para quais formatos de dados e tipos de arquivo você deseja dar suporte. Aqui, descreveremos os formatos padrão com suporte pelo namespace Windows.ApplicationModel.DataTransfer e como criar e usar os formatos personalizados quando os formatos padrão não se aplicam.

Escolhendo formatos de dados de um aplicativo de origem

Ao escrever um aplicativo de origem, você não está limitado a um único formato de dados ou tipo de arquivo. Ainda que um formato faça mais sentido do que os outros, a possibilidade de fornecer os mesmos dados em outros formatos pode ajudá-lo a garantir que os usuários compartilhem usando o aplicativo de destino que escolherem. Por exemplo, se um usuário quiser compartilhar texto formatado – digamos, em uma página da Web – poderá ser conveniente fornecer uma versão do conteúdo em texto sem formatação, afinal, nem todo aplicativo de destino dá suporte para texto formatado.

Observação  O número de formatos adicionais depende do tipo de conteúdo que os usuários podem compartilhar. É importante considerar o que é o conteúdo e o que o usuário espera ao compartilhá-lo. Em geral, é bastante útil criar uma versão de texto sem formatação para o texto formatado. A criação de um link para uma página da Web contendo esse texto, porém, pode não ser a expectativa do usuário.

Cenário de exemplo: o usuário deseja compartilhar um artigo que ele está lendo em seu aplicativo. Se o conteúdo estiver disponível na Web, primeiro inclua um link ao artigo. Adicionalmente, você deve incluir um resumo do artigo com um link para a origem no formato HTML, bem como texto.

Cenário de exemplo: O usuário deseja compartilhar uma seleção do artigo em seu aplicativo. Neste caso, o formato HTML reflete com mais precisão a intenção do usuário. Você também deve incluir uma versão do texto da seleção do usuário. A forma recomendada de obter isso é usar MSApp.createDataPackageFromSelection.

Esta tabela pode ajudá-lo a decidir os formatos que você deve suportar como um aplicativo de origem.

Os formatos personalizados também são permitidos para as situações em que são necessários formatos mais específicos do que os formatos padrão. Esses formatos personalizados podem ser baseados em esquemas de dados padrão, como aqueles encontrados em http://www.schema.org, ou um formato que você define exclusivamente para o seu aplicativo.

Escolhendo formatos de dados de um aplicativo de destino

Para um aplicativo de destino, recomendamos que você tente dar suporte ao maior número de tipos de formato possível. Isso ajuda a garantir que seu aplicativo esteja disponível como uma opção sempre que o usuário desejar compartilhar. Entretanto, assim como em aplicativos de origem, você não poderá dar suporte a um determinado formato se não planejar o recebimento desse tipo de dados. Por exemplo, um aplicativo que aceita somente texto não deve ser registrado como um aplicativo que dá suporte a bitmaps.

Aqui estão algumas recomendações de formatos aos quais você deve dar suporte.

Se o aplicativo pode dar suporte a vários formatos e todos esses formatos estiverem presentes no conteúdo que está sendo compartilhado, recomendamos que você processe somente o formato mais relevante ao aplicativo. Por exemplo, se o aplicativo compartilhar links e ele receber conteúdo compartilhado que tem um link e algum texto, seu aplicativo deve processar somente o link.

Às vezes, o aplicativo pode se beneficiar ao receber dados que incluem mais informações do que as fornecidas pelos formatos padrão. Por exemplo, um aplicativo de biblioteca pode desejar receber texto, mas somente se este texto tiver informações sobre um livro. Há suporte para formatos personalizados nessas situações. Esses formatos personalizados podem ser baseados em esquemas de dados padrão, como aqueles encontrados em http://www.schema.org, ou um formato que você define exclusivamente para o seu aplicativo.

Usando formatos baseados em esquema

Muitas vezes, os dados que você deseja compartilhar (como um aplicativo de origem ou de destino) são mais específicos que os fornecidos pelos formatos padrão. Por exemplo, um aplicativo focado em filmes pode desejar compartilhar informações sobre filmes e obter detalhes, como título, classificação, diretor, etc. Um aplicativo focado em livros pode desejar compartilhar informações sobre livros, incluindo autor, título e data de publicação. Se o aplicativo estiver em uma categoria como essa, recomendamos que você dê suporte a um dos esquemas listados em http://www.schema.org.

Se você desejar compartilhar dados usando um desses esquemas, faça o seguinte:

1. Identifique o item (livro, filme, etc) que o usuário deseja compartilhar.
2. Colete as informações relacionadas ao item e as empacote em um objeto JSON (JavaScript Object Notation).
3. Use setData para adicionar o conteúdo a um DataPackage. Quando você faz isso, é preciso incluir uma ID de formato. Por enquanto, use http://schema.org/<schema> como o ID. Por exemplo, http://schema.org/Book.

Este exemplo ilustra como compartilhar dados em um formato personalizado.

var book = {
    "type" : "http://schema.org/Book",
    "properties" : 
    {
         "image" : "http://sourceurl.com/catcher-in-the-rye-book-cover.jpg",
         "name" : "The Catcher in the Rye",
         "bookFormat" : "http://schema.org/Paperback",
         "author" : "http://sourceurl.com/author/jd_salinger.html",
         "numberOfPages" : 224,
         "publisher" : "Little, Brown, and Company",
         "datePublished" : "1991-05-01",
         "inLanguage" : "English",
         "isbn" : "0316769487"
    }
};
book = JSON.stringify(book);

function shareCustomData() {
    var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();
    dataTransferManager.addEventListener("datarequested", function (e) {
        var request = e.request;
        request.data.setData("http://schema.org/Book", book);
    });
}

Observe que só colocamos um único formato de dados no DataPackage. Dessa forma, qualquer aplicativo de destino que o usuário selecionar saberá o que esperar.

Se você desejar receber dados que usam um desses esquemas, aqui estão as etapas que você precisa seguir:

1. Edite o manifesto do pacote para declarar que o aplicativo é um destino de compartilhamento. Consulte o Guia de início rápido para saber como fazer isso.
2. No manifesto do pacote, adicione um formato de dados que identifique o esquema com suporte no aplicativo. Use http://schema.org/<schema> como o formato de dados. Por exemplo, http://schema.org/Book.
3. Use getDataAsync para obter o conteúdo do objeto DataPackageView que você recebe durante uma operação de compartilhamento.

Este exemplo ilustra como receber dados compartilhados em um formato personalizado.

if (shareOperation.data.contains("http://schema.org/Book")) {
    shareOperation.data.getTextAsync(("http://schema.org/Book").done(function (customFormatString) {
        var customFormatObject = JSON.parse(customFormatString);
        if (customFormatObject) {
            // This sample expects the custom format to be of type http://schema.org/Book
            if (customFormatObject.type === "http://schema.org/Book") {
                customFormatString = "Type: " + customFormatObject.type;
                if (customFormatObject.properties) {
                    customFormatString += "\nImage: " 
                            + customFormatObject.properties.image
                            + "\nName: " + customFormatObject.properties.name
                            + "\nBook Format: " + customFormatObject.properties.bookFormat
                            + "\nAuthor: " + customFormatObject.properties.author
                            + "\nNumber of Pages: " + customFormatObject.properties.numberOfPages
                            + "\nPublisher: " + customFormatObject.properties.publisher
                            + "\nDate Published: " + customFormatObject.properties.datePublished
                            + "\nIn Language: " + customFormatObject.properties.inLanguage
                            + "\nISBN: " + customFormatObject.properties.isbn;
                }
            }
        }
    });
}

Usando formatos personalizados

Se, você não conseguir encontrar um esquema em http://schema.org/docs/full.htm que atenda às necessidades do seu aplicativo, poderá criar o seu próprio formato personalizado. Se esta for a sua decisão, há algumas considerações que são fundamentais:

• O nome do formato personalizado é importante. O mesmo nome deve ser usado nos dois aplicativos – de origem e de destino.
• É preciso publicar o formato. Dessa forma, os desenvolvedores que quiserem usá-lo saberão como fazer o empacotamento necessário do conteúdo.

Abordamos essas e outras considerações mais detalhadamente em Diretrizes para a criação de formatos de dados personalizados.

Tópicos relacionados

Exemplo de aplicativo de compartilhamento de origem de conteúdo

Exemplo de aplicativo de compartilhamento de destino de conteúdo

Guia de início rápido: compartilhando conteúdo

Guia de início rápido: recebendo conteúdo compartilhado