Como receber 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]

O compartilhamento de arquivos requer um pouco mais de preparação do que tipos de dados simples, como texto. Ao compartilhar arquivos, você precisa considerar quanto tempo pode levar o processamento dos arquivos.

Se você acredita que o seu aplicativo precisa de tempo para processar os arquivos que um usuário quer compartilhar, certifique-se de chamar reportStarted antes de começar a processá-los. Esse método garante que o sistema manterá o seu aplicativo ativo até que o processamento ser concluído. Uma vez que o seu aplicativo tenha concluído o processamento, chame reportCompleted para encerrar a operação de compartilhamento. para saber mais, veja "Relatar o status de compartilhamento estendido" no Guia de início rápido: recebendo conteúdo compartilhado.

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.

Instruções

Etapa 1: Suporte o contrato de Compartilhamento.

Antes que seu aplicativo possa receber conteúdo compartilhado, você tem que declarar que ele suporta o contrato de Compartilhamento. Esse contrato permite que o sistema saiba que o seu aplicativo está disponível para receber conteúdo. Se estiver usando um modelo do Microsoft Visual Studio para criar seu aplicativo, aqui está como ter suporte para o contrato de Compartilhamento de Destino:

Abra o arquivo de manifesto (package.appxmanifest).
Abra a guia Declarações.
Escolha Compartilhar Destino na lista Declarações Disponíveis.
Clique em Adicionar para adicionar suporte ao contrato de Compartilhamento de Destino em seu aplicativo.

Etapa 2: Especifique os tipos de arquivo que seu aplicativo suporta.

Você pode especificar os tipos de arquivo que seu aos quais seu aplicativo dá suporte especificando suas extensões no manifesto do aplicativo:

Abra arquivo de manifesto.
Na seção Formatos de dados, clique em Adicionar novo.
Digite a extensão do nome de arquivo como ".txt" (sem aspas).
Repita a etapa anterior para quaisquer tipos de arquivos adicionais.

As etapas anteriores adicionam a seguinte seção ao manifesto:

<Extensions>
  <Extension Category="windows.shareTarget">
    <ShareTarget>
      <SupportedFileTypes>
        <FileType>.txt</FileType>
    </ShareTarget>
  </Extension>
</Extensions>

Observação Você não precisa especificar StorageItems na seção de formatos de dados. O suporte para isso é inferido a partir da seção SupportedFileTypes no manifesto. Se o seu aplicativo dá suporte a quaisquer tipos de arquivos, você pode especificá-los no manifesto marcando Dá suporte a qualquer tipo de arquivo.

Observação Você pode especificar um ponto de entrada diferente quando seu aplicativo for ativado para o contrato de Compartilhamento de Destino. Para fazer isso, modifique a entrada da página Iniciarna seção de configurações do Aplicativoda declaração do Destino de Compartilhamento no manifesto do pacote. É altamente recomendável que você também use um arquivo JavaScript separado que cuide da ativação desta página. Por exemplo, dê uma olhada em Exemplo de aplicativo de compartilhamento de destino de conteúdo.

Etapa 3: Adicione um manipulador de eventos para detectar quando o seu aplicativo é ativado.

Quando um usuário seleciona o seu aplicativo para compartilhar conteúdo, o sistema ativa o aplicativo. Como existem muitas maneiras disso acontecer, você precisa adicionar o código a seu manipulador de eventos que detecta o motivo pelo qual ocorreu a ativação. Você pode fazer isso verificando o valor da propriedade kind.

app.onactivated = function (args) {
    if (args.detail.kind === activation.ActivationKind.launch) {
        // The application has been launched. Initialize as appropriate.
    } else if (args.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.shareTarget) {
        ...
    }
};

Etapa 4: Obtenha o objeto ShareOperation.

O objeto ShareOperation contém todos os dados necessários para que o seu aplicativo obtenha o conteúdo que o seu usuário quiser compartilhar.

shareOperation = args.detail.shareOperation;

Etapa 5: Retorne do manipulador de eventos ativados rapidamente.

O manipulador de eventos activated deve retornar rapidamente. Coloque na fila um evento assíncrono a partir do manipulador de eventos activated dessa forma, o processamento de compartilhamento dedados ocorre depois que o evento ativado retorna.

WinJS.Application.addEventListener("shareready", shareReady, false);
WinJS.Application.queueEvent({ type: "shareready" });

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

Etapa 6: Verifique se DataPackageView contém StorageItems.

O objeto ShareOperation contém um objeto DataPackageView. Esse objeto é uma versão apenas leitura do objeto DataPackage que o aplicativo de origem usou para criar os dados. Use esse objeto para verificar se o conteúdo compartilhado contém StorageItems.

if (shareOperation.data.contains(Windows.ApplicationModel.DataTransfer.StandardDataFormats.storageItems)) {
    // Data being shared contains one or more StorageItem. Code to process the StorageItems goes here.
}

Verificar se o DataPackage contém o formato de dados em que você está interessado é uma prática recomendada, mesmo se o seu aplicativo aceitar somente um formato. Isso facilita o suporte futuro a outros de outros formatos de dados.

Etapa 7: Processe os arquivos.

Para obter os arquivos, chame o método DataPackageView.GetStorageItemsAsync.

shareOperation.data.getStorageItemsAsync().then(function (storageItems) {
    var fileList = "";
    for (var i = 0; i < storageItems.size; i++) {
        fileList += storageItems.getAt(i).name;
        if (i < storageItems.size - 1) {
            fileList += ", ";
        }
    }
    // In this example, we only display the file names. To do this, you need 
    // a <div> element with an id of "output" in your HTML page.

    // In your app, replace this with whatever is appropriate for your scenario.
    document.getElementById("output").innerText = "Files: " + fileList;
});

Observação

O processamento dos arquivos pode ser demorado. É importante não forçar o usuário a aguardar o seu aplicativo concluir o carregamento e processamento dos dados. No Windows 8.1, você pode chamar o método reportStarted para informar ao sistema que seu aplicativo iniciou o processamento do conteúdo que está sendo compartilhado. O sistema mantém seu aplicativo ativo até você chamar reportCompleted—mesmo que os usuários ignorem o seu aplicativo e retornem para o aplicativo de origem. Para saber mais, veja "Relatar o status de compartilhamento estendido" no Guia de início rápido: recebendo conteúdo compartihado.

Etapa 8: Chame reportCompleted.

Depois que o aplicativo concluir com sucesso o compartilhamento do conteúdo, chame reportCompleted. Depois que você chamar este método, o sistema ignora seu aplicativo.

shareOperation.reportCompleted();

Comentários

Dê uma olhada em nosso exemplo de código Exemplo de aplicativo de compartilhamento de destino de conteúdo para ver a experiência ponta a ponta inteira de um aplicativo que recebe texto como parte do compartilhamento.

Exemplo completo

var shareOperation = null;

function shareReady(args) {
    if (shareOperation.data.contains(Windows.ApplicationModel.DataTransfer.StandardDataFormats.storageItems)) {
        shareOperation.data.getStorageItemsAsync().then(function (storageItems) {
            var fileList = "";
            for (var i = 0; i < storageItems.size; i++) {
                fileList += storageItems.getAt(i).name;
                if (i < storageItems.size - 1) {
                    fileList += ", ";
                }
            }
            // In this example, we only display the file names. To do this, you need 
            // a <div> element with an id of "output" in your HTML page.

            // In your app, replace this with whatever is appropriate for your scenario.
            document.getElementById("output").innerText = "Files: " + fileList;
        });
    }
}

app.onactivated = function (args) {
    if (args.detail.kind === activation.ActivationKind.launch) {
        // The app has been launched.
        args.setPromise(WinJS.UI.processAll());
    } else if (args.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.shareTarget) {
        // This app was activated for the Share contract.
        args.setPromise(WinJS.UI.processAll());

        // We receive the ShareOperation object as part of the eventArgs.
        shareOperation = args.detail.shareOperation;

        // We queue an asychronous event so that working with the ShareOperation 
        // object does not block or delay the return of the activation handler.
        WinJS.Application.addEventListener("shareready", shareReady, false);
        WinJS.Application.queueEvent({ type: "shareready" });
    }
};