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

Rotineiramente, usuários querem compartilhar arquivos com outras pessoas ou com aplicativos. Usando a funcionalidade de compartilhamento, o seu aplicativo pode facilmente suportar um álbum de fotos das férias da família.

Ao suportar algo como o compartilhamento de arquivos, você precisa considerar quando o seu aplicativo concluirá os arquivos. Na maior parte do tempo, o seu aplicativo terá os arquivos, provavelmente, disponíveis para uso. Se é esse o caso, as etapas deste tópico devem ser justamente o que você procurava. Caso o seu aplicativo precise trabalhar mais um pouco antes para que os arquivos fiquem prontos — por exemplo, para converter arquivos de um formato em outro — sugerimos que você confira o nosso tópico, Como suportar operações pull. Esse tópico mostra como usar uma função delegada para que aplicativos de destino possam efetuar pull do conteúdo compartilhado pelo seu aplicativo em vez de exigir que o ser aplicativo envie o conteúdo por push.

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 obter arquivos e outros dados; por exemplo, usando o FileOpenPicker. Para saber mais, consulte Acessando arquivos com seletores de arquivos.

Instruções

Etapa 1: Crie uma função do manipulador de botão para permitir que o usuário escolha um arquivo de imagem

O seguinte código do manipulador de botão permite que o usuário selecione um arquivo de imagem. Este arquivo é usado nas etapas remanescentes desse guia de início rápido.

Observação

O código a seguir utiliza pickSingleFileAsync. No Windows Phone 8.1, pickSingleFileAndContinue deve ser usado no lugar.

var imageFile = null;
function pickImageFile() {
    var picker = new Windows.Storage.Pickers.FileOpenPicker();
    picker.fileTypeFilter.replaceAll([".jpg", ".bmp", ".gif", ".png"]);
    picker.pickSingleFileAsync().done(function (file) {
        imageFile = file;
    });
}

Etapa 2: 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", shareStorageItemsHandler);

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

Etapa 3: 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 4: Definir as propriedades de título e descrição

request.data.properties.title = "Share StorageItems Example";
request.data.properties.description = "Demonstrates how to share files.";

Etapa 5: Adicionar os arquivos ao DataPackage

Para adicionar os arquivos ao DataPackage, use o método setStorageItems.

request.data.setStorageItems([imageFile]);

Comentários

Por padrão, o setStorageItems fornece "clones" somente leitura de storageItems para compartilhamento com os aplicativos de destino. Depois que você chamar setStorageItems, as novas propriedades definidas nos itens de armazenamento individuais não serão refletidas nos itens clonados. Por isso é importante que você sempre verifique se os seus arquivos estão completamente preparados para o compartilhamento antes de adicioná-los ao DataPackage.

Além disso, se você quiser que um aplicativo de destino tenha a funcionalidade de leitura e gravação no storageItems, use a versão de sobrecarga do método setStorageItems que permite especificar somente leitura ou leitura e gravação. Por exemplo, um aplicativo de origem que pede que o aplicativo de destino realize a operação de excluir ao colar pode especificar a opção de leitura e gravação para permitir que o aplicativo de destino exclua os arquivos de origem após copiá-los.

Se o aplicativo precisa usar uma operação assíncrona para preparar a imagem ou a miniatura, será necessário usar o padrão de adiamento. Mostramos como fazer isso em Como fazer chamadas assíncronas em seu manipulador datarequested.

Se o aplicativo demorar muito (mais de 200 milissegundos) para preparar os arquivos, você precisará usar uma função de delegação para compartilhá-los. Veja como fazer isso em Como dar suporte para operações pull. Se você decidir usar uma função delegada, você precisa definir a propriedade FileTypes no DataPackage antes de adicionar os próprios arquivos.

Exemplo completo

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

var imageFile = null;
function pickImageFile() {
    var picker = new Windows.Storage.Pickers.FileOpenPicker();
    picker.fileTypeFilter.replaceAll([".jpg", ".bmp", ".gif", ".png"]);
    picker.pickSingleFileAsync().done(function (file) {
        imageFile = file;
    });
}

function shareStorageItemsHandler(e) {
    var request = e.request;
    request.data.properties.title = "Share StorageItems Example";
    request.data.properties.description = "Demonstrates how to share files.";
    request.data.setStorageItems([imageFile]);
}

app.onactivated = function (args) {
    if (args.detail.kind === activation.ActivationKind.launch) {
        if (args.detail.previousExecutionState !== activation.ApplicationExecutionState.terminated) {
            // This app is newly launched; register it as a share source.
            var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();
            dataTransferManager.addEventListener("datarequested", shareStorageItemsHandler);
            // Setup the button handler to pick image file
            document.getElementById("chooseImageButton").addEventListener("click", pickImageFile, false);
        } else {
            // TODO: This app was reactivated from suspension.
            // Restore the app state here.
        }
        args.setPromise(WinJS.UI.processAll());
    }
};