Diretrizes para criar formatos de dados personalizados

Applies to Windows and Windows Phone

Os usuários compartilham uma variedade de informações quando estão online. Aplicativos bem sucedidos analisam os tipos de informações que os usuários estão mais propensos a compartilhar com os outros e compactam essas informações para que os aplicativos de recebimento possam processá-las corretamente. Em muitos casos, as informações que os usuários desejam compartilhar se enquadram em um dos seis formatos padrão com suporte no Windows. No entanto, pode haver alguns casos em que ter um tipo de dado mais direcionado pode proporcionar uma melhor experiência do usuário. Para essas situações, seu aplicativo pode dar suporte para formatos de dados personalizados.

Exemplo

Para ilustrar como pensar na criação de um formato personalizado, considere o seguinte exemplo.

Na empresa fictícia, a Fabrikam, um desenvolvedor cria um aplicativo que compartilha arquivos armazenados online. Uma opção seria usar o StorageItems voltado para transmissão, mas isso poderia ser um processo demorado e ineficiente, porque o aplicativo de destino terminaria o download dos arquivos localmente para lê-los. Em vez disso, o desenvolvedor decide criar um formato personalizado para uso com esses tipos de arquivo.

Em primeiro lugar, o desenvolvedor considera a definição do novo formato. Nesse caso, trata-se de uma coleção de qualquer tipo de arquivo (documento, imagem, etc.) armazenado online. Como os arquivos estão na Web, e não na máquina local, o desenvolvedor decide dar ao formato o nome WebFileItems.

Em seguida, o desenvolvedor precisa decidir as especificações do formato e decide o seguinte:

  • O formato deve consistir em um IPropertyValue que contém um InspectableArray que representas os URls (Uniform Resource Identifiers).
  • O formato deve conter pelo menos um item, mas não há limite para o máximo de itens que pode conter.
  • Qualquer URI válido é permitido.
  • Não recomendamos o uso de URIs que não são acessíveis fora dos limites do aplicativo de origem (como URIs autenticados).

Com essas informações mapeadas, o desenvolvedor agora tem informações suficientes para criar e usar um formato personalizado.

Meu aplicativo deve usar formatos personalizados?

O recurso de compartilhamento no Windows 8 oferece suporte a seis formatos de dados padrão:

  • texto
  • HTML
  • bitmap
  • StorageItems
  • URI
  • RTF

Esses formatos são muito versáteis, o que facilita para o seu aplicativo dar suporte rapidamente ao compartilhamento e ao recebimento de conteúdo compartilhado. A desvantagem desses formatos é que eles nem sempre oferecem uma boa descrição dos dados para o aplicativo de recebimento. Para ilustrar isso, considere a seguinte cadeia, que representa um endereço postal:

1234 Main Street, New York, NY 98208

Um aplicativo pode compartilhar essa cadeia usando o DataPackage.setText. Mas, como o aplicativo que recebe a cadeia de texto não saberá exatamente o que ela representa, ele se limita ao que pode fazer com esses dados. Usando um formato de dados personalizado, o aplicativo de origem pode definir os dados que estão sendo compartilhados como "lugar" usando o formato http://schema.org/Place. Isso dá ao aplicativo de recebimento algumas informações adicionais que ele pode usar para processar as informações da forma como o usuário espera. O uso de formatos de esquema existentes permite que seu aplicativo seja vinculado a um banco de dados maior de formatos definidos.

Os formatos personalizados também podem ajudá-lo a fornecer maneiras mais eficientes de compartilhar dados. Por exemplo, um usuário tem uma coleção de fotos armazenadas no Microsoft OneDrive e decide compartilhar algumas em uma rede social. Esse cenário é difícil de implementar usando os formatos padrão, por algumas razões:

  • Você só pode usar o formato URI para compartilhar um item de cada vez.
  • O OneDrive compartilha coleções como StorageItems voltados para transmissão. Usando o StorageItems nesse cenário, o aplicativo teria que baixar todas as imagens e compartilhá-las.
  • O Texto e HTML permitem que você forneça uma lista de links, mas o significado desses links é perdido: o aplicativo que recebe não saberá que esses links representam as imagens que o usuário deseja compartilhar.

Usar um formato de esquema existentes ou um formato personalizado para compartilhar essas imagens oferece dois benefícios importantes:

  • O aplicativo pode compartilhar as imagens mais tarde, porque você criaria uma coleção de URIs, em vez de baixar todas as imagens localmente.
  • O aplicativo que recebe entenderia que esses URIs representam imagens e poderia processá-los corretamente.

O que fazer e o que não fazer

Definindo um formato personalizado

Caso decida que o seu aplicativo pode se beneficiar com a definição de um formato personalizado, há algumas coisas que você deve considerar:

  • Compreenda os formatos de dados padrão para não criar um formato personalizado desnecessariamente. Você deve verificar se existe um formato no http://www.schema.org que se ajustaria ao seu cenário. É mais provável que outro aplicativo use um formato existente em relação ao seu formato personalizado, que significa que um público maior pode atingir os cenários ponta a ponta desejados.
  • Considere as experiências que você deseja proporcionar. É importante que você pense sobre as ações que os seus usuários desejam executar e que formato de dados oferece melhor suporte para essas ações.
  • Disponibilize a definição de seu formato personalizado para outros desenvolvedores de aplicativos.
  • Ao nomear seu formato, certifique-se de que o nome corresponda ao conteúdo desse formato. Por exemplo, UriCollection indica que qualquer URI é válido, enquanto WebImageCollection indica que ele contém apenas URIs que apontam para imagens online.
  • Considere com cuidado o significado do formato. Compreenda claramente o que representa o formato e como ele deve ser usado.
  • Analise a estrutura do formato. Pense se o formato dá suporte para vários itens ou para serialização e quais são as suas limitações.
  • Não mude o seu formato personalizado depois de publicá-lo. Considere-o como uma API: elementos podem ser adicionados ou preteridos, mas a compatibilidade com versões anteriores e o suporte a longo prazo são importantes.
  • Não confie em combinações de formatos. Por exemplo, não espere que um aplicativo entenda que, se vê um formato, também deve procurar um segundo formato. Cada formato deve ser independente.

Adicionando formatos personalizados ao seu aplicativo

Depois de definir um formato personalizado, siga estas recomendações para adicionar o formato ao seu aplicativo:

  • Teste o formato com outros aplicativos. Certifique-se de que os dados sejam processados corretamente a partir do aplicativo de origem para o aplicativo de destino.
  • Siga a finalidade planejada do formato. Não o use de formas não planejadas.
  • Se você estiver criando um aplicativo de origem, forneça pelo menos um formato padrão também. Isso garante que os usuários possam compartilhar dados com aplicativos que não oferecem suporte para o formato personalizado. A experiência pode não ser tão ideal para o usuário, mas é melhor do que não permitir que eles compartilhem dados com os aplicativos que quiserem. Você também deve documentar seu formato online, dessas forma outros aplicativos poderão conhecê-lo e adotá-lo.
  • Se você estiver criando um aplicativo de destino, considere dar suporte a pelo menos um formato padrão. Dessa forma, seu aplicativo pode receber dados de aplicativos de origem, mesmo que eles não usem o formato personalizado de sua preferência.
  • Se você desejar aceitar um formato personalizado específico de outro aplicativo, particularmente um de uma empresa diferente, você deverá verificar duas vezes para se ele está documentado publicamente online. Os formatos não documentados tem mais chance de mudar sem aviso, criando potencialmente inconsistências ou danificando seu aplicativo.

Diretriz de uso adicional

Escolhendo um tipo de dados

Uma das decisões mais importantes que você tomará ao definir um formato personalizado é o tipo de dados WinRT utilizado para transferência entre aplicativos de origem e de destino. A classe DataPackageoferece suporte a diversos tipos de dados para um formato personalizado:

Ao definir um formato, selecione o tipo adequado para esses dados. É muito importante que todos os consumidores e destinatários desse formato usem o mesmo tipo de dados (mesmo que haja opções diferentes). Caso contrário, isso pode gerar falhas inesperadas de compatibilidade de tipo de dados em aplicativos de destino.

Se escolher cadeia como o tipo de dados para o seu formato, você poderá recuperá-la no lado do destino usando o formato GetTextAsync(formatId) da função GetTextAsync. Essa função executa uma verificação de tipo de dados para você. Caso contrário, será necessário usar a GetDataAsync, o que significa que você deve se proteger contra possíveis incompatibilidades de tipo de dados. Por exemplo, se um aplicativo de origem oferecer um único URI, e o destino tentar recuperá-lo como uma coleção de URIs, ocorrerá uma incompatibilidade. Para ajudar a evitar esses conflitos, você pode adicionar um código semelhante a este:

Preenchendo o DataPackage


var uris = new Array();
uris[0] = new Windows.Foundation.Uri("http://www.msn.com");
uris[1] = new Windows.Foundation.Uri("http://www.microsoft.com");
var dp = new Windows.ApplicationModel.DataTransfer.DataPackage();
dp.setData("UriCollection", uris);


Recuperando os dados


if (dpView.contains("UriCollection")) {
    dpView.getDataAsync("UriCollection").done(function(uris) {
        // Array.isArray doesn’t work – uris is projected from InspectableArray
        if (uris.toString() === "[object ObjectArray]") {
            var validUriArray = true;
            for (var i = 0; (true === validUriArray) && (i < uris.length); i++) {
                validUriArray = (uris[i] instanceof Windows.Foundation.Uri);
            }
            if (validUriArray) {
                // Type validated data 
            }
        }
    }
}


Tópicos relacionados

Para desenvolvedores (aplicativos do Tempo de Execução do Windows em JavaScript e HTML)
Escolhendo formatos de dados para compartilhamento
Quickstart: Sharing content
Quickstart: Receiving shared content
Para desenvolvedores (aplicativos do Tempo de Execução do Windows em C#/VB/C++ e XAML)
Escolhendo formatos de dados para compartilhamento
Quickstart: Sharing content
Recebendo conteúdo compartilhado
Exemplos
Exemplo de aplicativo de compartilhamento de origem de conteúdo
Exemplo de aplicativo de compartilhamento de destino de conteúdo

 

 

Mostrar:
© 2014 Microsoft