Como dar suporte para operações pull (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]

A maioria das vezes, o aplicativo fornece os dados de compartilhamento imediatamente a partir de seu manipulador de eventos datarequested. Às vezes, entretanto, seu aplicativo pode precisar de tempo para obter os dados prontos para compartilhamento. Quando isso acontece, você pode fornecer uma lista de formatos permitidos, mas atrasar a preparação e o fornecimento do conteúdo até o aplicativo de origem solicitá-lo. Adiar o fornecimento de conteúdo até que o aplicativo de destino o solicite constitui uma operação pull (ou compartilhamento atrasado).

Para dar suporte para operações pull, primeiro você cria uma função que empacota os dados que o usuário quer compartilhar. Então, em vez de fornecer os dados reais para o aplicativo de destino, você fornece uma função de delegação. Quando o aplicativo de destino tenta obter os dados, o sistema chama essa função de delegação. A vantagem aqui é que o seu aplicativo pode compartilhar os dados em tela de fundo, permitindo que o usuário continue usando o aplicativo para outras atividades.

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: Crie uma função de delegação para fornecer o conteúdo que o usuário deseja compartilhar.

A natureza exata da função de delegação depende do seu aplicativo. Veja a seguir um exemplo.

function onDeferredImageRequested(request) {
    if (imageFile) {
        var imageStreamRef = Windows.Storage.Streams.RandomAccessStreamReference.createFromFile(imageFile);
        request.setData(imageStreamRef);
    }
}

Para adicionar o conteúdo, a função de delegação usa setData em vez de uma função específica de formato, como setBitmap ou setStorageItems. Sempre que usar uma função de delegação, você precisará usar setData para fornecer o conteúdo.

Etapa 3: 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", sharePullHandler);

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

Etapa 4: Obter um objeto DataRequest

Quando ocorre um evento datarequested, seu aplicativo recebe um objeto DataRequest. Este objeto contém um DataPackage que geralmente seria usado para fornecer o conteúdo que o usuário deseja compartilhar. Porém, nas operações pull, você especifica uma função de delegação em vez dos dados reais.

var request = e.request;

Etapa 5: Definir as propriedades de título e descrição

request.data.properties.title = "Share Pull Example";
request.data.properties.description = "Demonstrates how to pull operations in share.";

Etapa 6: Defina os tipos de arquivo, se necessário.

Se você estiver usando uma função de delegação para compartilhar arquivos, precisará especificar os tipos de arquivo para os quais há suporte no seu aplicativo.

request.data.properties.fileTypes.replaceAll([".jpg", ".bmp", ".gif", ".png"]);

Etapa 7: Adicionar a função de delegação ao objeto DataPackage

O método setDataProvider especifica a função de delegação que você criou para fornecer o conteúdo em si.

request.data.setDataProvider(Windows.ApplicationModel.DataTransfer.StandardDataFormats.bitmap, onDeferredImageRequested);

Neste ponto, quando o usuário toca no símbolo do evento Share, o aplicativo pode responder instantaneamente com um objeto DataPackage que contém a função delegada. A operação de compartilhamento pode agora continuar em segundo plano, liberando o usuário para continuar com quaisquer que sejam as outras atividades desejadas.

Lembre-se: se estiver compartilhando arquivos, o setStorageItems criará objetos StorageFile somente leitura para compartilhamento e preservará os objetos originais. Isso significa que, se você adicionar propriedades expandidas a um arquivo original depois de chamar setStorageItems, essas novas propriedades expandidas não serão incluídas nos objetos StorageFile que estão sendo compartilhados. É por isso que recomendamos que você só adicione os arquivos quando estiver completamente preparado.

Comentários

Um que compartilha dados usando a renderização adiada deve ser um aplicativo de página única a fim de evitar a navegação entre páginas. Além disso, se o seu aplicativo der suporte para navegação em quadros, ele deverá usar o contexto de script de nível superior para registrar as funções de delegação em vez de registrar os delegados no nível do quadro. A navegação provoca a perda do contexto de script, o que invalida as funções de delegação e causa a falha da renderização adiada.

Exemplo completo

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 onDeferredImageRequested(request) {
    if (imageFile) {
        var imageStreamRef = Windows.Storage.Streams.RandomAccessStreamReference.createFromFile(imageFile);
        request.setData(imageStreamRef);
    }
}

function sharePullHandler(e) {
    var request = e.request;
    request.data.properties.title = "Share Pull Example";
    request.data.properties.description = "Demonstrates how to support pull operations in share.";
    request.data.properties.fileTypes.replaceAll([".jpg", ".bmp", ".gif", ".png"]);
    request.data.setDataProvider(Windows.ApplicationModel.DataTransfer.StandardDataFormats.bitmap, onDeferredImageRequested);
}

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", sharePullHandler);
            // Set up the button handler to pick an 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());
    }
};