Guia de início rápido: dando suporte a formatos de dados personalizados (HTML)

  • Artigo

[ 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]

A classe principal que permite compartilhar dados entre aplicativos—DataPackage—suporta dois tipos de formato: padrão e personalizado. DataPackage suporta os formatos padrão com métodos fortemente tipados, como setText ou getHtml. Os formatos personalizados, por outro lado, permitem que você defina mais formatos direcionados que podem fornecer melhor experiência do usuário.

Se você quiser saber mais sobre os formatos personalizados e quiser saber o que deve levar em consideração antes de implementá-los no aplicativo, veja Diretrizes para a criação de formatos de dados personalizados.

Antes de começar

Se você está aqui, presumimos que já tenha um formato personalizado que é utilizado no seu aplicativo e deseja saber como compartilhar dados usando esse formato com outros aplicativos. Se você ainda está decidindo se o uso de um formato personalizado é a forma certa, consulte nosso tópico Diretrizes para criar formatos de dados personalizados.

Compartilhando dados usando um formato personalizado

Para compartilhar dados usando um formato personalizado, é necessário primeiramente obter uma instância do objeto DataPackage. No Windows 8.1, o código a seguir usa um ouvinte de eventos para detectar quando o usuário toca no botão Compartilhar e obtém um objeto DataPackage. Se estiver desenvolvendo para Windows Phone 8.1, não haverá botão Compartilhar interno, portanto, você precisará adicionar um controle para o usuário tocar e disparar o manipulador

DataTransferManager dataTransferManager = DataTransferManager.GetForCurrentView();

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

Neste ponto, é necessário coletar os dados que o usuário deseja compartilhar. O modo de fazer isso, depende obviamente do formato personalizado que você definiu. O código a seguir usa um formato que o DataPackage não suporta diretamente —valores separados por vírgula ou CSV—como formato personalizado.

function shareCustomData() {
    //Create the custom data.
    var myArray = new Array(1, 2, 3, 4);
    var arrayToCsv = myArray.join(",");
    var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();
    dataTransferManager.addEventListener("datarequested", function (e) {
        var request = e.request;
        request.data.properties.title = "Share Text Example";
        request.data.properties.description = "A demonstration that shows how to share.";
        request.data.setData("csv", arrayToCsv);
    });
}

Observe que, para compartilhar os dados, você deve usar o método setData de DataPackage. Esse método assume dois parâmetros: o nome do formato personalizado e os dados em si.

request.data.setData("csv", arrayToCsv);

Nesse ponto, é útil considerar alguns aspectos:

  • Para que um formato personalizado funcione corretamente, o nome do formato deve ser o mesmo no aplicativo de origem e no aplicativo de destino. Por esta razão, recomendamos que você teste seus formatos personalizados com os aplicativos que você acha que um usuário pode selecionar. Se você tiver criado o formato personalizado, forneça uma maneira para outros desenvolvedores o descobrirem. Temos mais informações sobre essas e outras considerações nas Diretrizes para criar formatos de dados personalizados.
  • Além disso, mesmo que um formato personalizado ofereça a melhor experiência para os usuários, é provavelmente uma boa ideia ter uma versão dos dados em um formato padrão. Dessa forma, você considera as situações em que os usuários desejam compartilhar conteúdo usando um aplicativo que não reconhece o formato personalizado.

Recebendo dados em um formato personalizado

Para receber dados compartilhados usando um formato personalizado, é necessário declarar que o aplicativo é um compartilhamento de destino e atualizar o arquivo de manifesto do pacote com o tipo de formato.

Para declarar que o aplicativo é um compartilhamento de destino:

  1. Abra o arquivo de manifesto. Ele deve ser nomeado como algo semelhante a package.appxmanifest.
  2. Abra a guia Declarações.
  3. Escolha Compartilhar Destino na lista Declarações Disponíveis.

Para especificar o tipo de formato:

  1. Abra o arquivo de manifesto.
  2. Na seção Tipos de Arquivos Suportados, clique em Adicionar Novo.
  3. Tipo de extensão para o tipo de formato. Você precisa incluir o ponto (.).

Depois, é necessário saber se o aplicativo foi ativado para uma operação de compartilhamento.

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

Após a ativação do aplicativo, use o objeto ShareOperation para obter os dados em compartilhamento.

shareOperation = eventObject.detail.shareOperation;

Em seguida, o aplicativo pode usar o método Contains para detectar se DataPackageView possui dados armazenados no formato personalizado.

if(shareOperation.data.contains("customformat")) {
    //Process the data here.
}

Para obter os dados, use o método getDataAsync.

shareOperation.data.getTextAsync(customFormatName).then(function (customFormatString) {
    // Process the custom data
});

O modo do aplicativo processar os dados depende do formato personalizado usado pelo aplicativo de origem.

Tópicos relacionados

Exemplo de aplicativo de compartilhamento de origem de conteúdo

Exemplo de aplicativo de compartilhamento de destino de conteúdo