Comment prendre en charge les opérations Pull (HTML)

Article
12/11/2015

[ Cet article est destiné aux développeurs de Windows 8.x et Windows Phone 8.x qui créent des applications Windows Runtime. Si vous développez une application pour Windows 10, voir la Documentation ]

Dans la plupart des cas, l’application fournit les données de partage directement depuis son gestionnaire d’événements datarequested. Toutefois, votre application peut avoir besoin de temps pour préparer les données au partage. Dans ces circonstances, vous pouvez fournir la liste de formats pris en charge, mais attendez de préparer et de fournir le contenu que l’application cible en fasse la demande. Différer la remise du contenu jusqu’à ce que l’application cible en fasse la demande est ce que l’on appelle une opération de type Pull (ou partage retardé).

Pour prendre en charge les opérations Pull, commencez par créer une fonction chargée de collecter les données que l’utilisateur souhaite partager. Ainsi, au lieu de transmettre les données réelles à l’application cible, vous fournissez une fonction déléguée. Lorsque l’application cible essaie d’obtenir les données, le système appelle votre fonction déléguée. L’avantage de cette méthode est que votre application peut préparer le partage des données en arrière-plan, pendant que l’utilisateur effectue d’autres tâches dans votre application.

Ce que vous devez savoir

Technologies

Windows.ApplicationModel.DataTransfer

Prérequis

Vous devez être familiarisé avec Visual Studio et ses modèles connexes.
Vous devez être familiarisé avec JavaScript.
Vous devez comprendre comment obtenir des fichiers et d’autres données à l’aide de l’objet FileOpenPicker, par exemple. Pour en savoir plus, voir Accès aux fichiers à l’aide de sélecteurs de fichiers.

Instructions

Étape 1: Créer une fonction Gestionnaire de boutons pour permettre à l’utilisateur de choisir un fichier d’image

Le code de gestionnaire de boutons suivant permet à l’utilisateur de sélectionner un fichier d’image. Ce fichier est utilisé dans les dernières étapes de ce démarrage rapide.

Remarque

Le code suivant utilise pickSingleFileAsync. Sur Windows Phone 8.1, pickSingleFileAndContinue doit être utilisé à la place.

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;
    });
}

Étape 2: créer une fonction déléguée pour fournir le contenu que l’utilisateur souhaite partager.

La nature exacte de la fonction déléguée dépend de votre application. Voici un exemple :

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

Notez que la fonction déléguée fait appel à la méthode setData pour ajouter le contenu, et pas à une fonction de format spécifique, telle que setBitmap ou setStorageItems. Si vous utilisez une fonction déléguée, vous devez appeler la méthode setData pour fournir le contenu.

Étape 3: Configurer votre application en tant que source de partage

L’objet DataTransferManager est le point de départ principal de toute opération de partage. Ajoutez un gestionnaire d’événements DataRequested qui se déclenche quand l’utilisateur souhaite appeler le partage. Dans une application du Windows Store, cela se produit automatiquement quand l’utilisateur appelle l’icône Partager. Si vous développez une application pour Windows Phone, aucune icône Partager n’est intégrée, donc vous devez ajouter un contrôle sur lequel l’utilisateur peut appuyer pour déclencher le gestionnaire.

var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();
dataTransferManager.addEventListener("datarequested", sharePullHandler);

Les étapes restantes servent à implémenter la fonction sharePullHandler.

Étape 4: obtenir un objet DataRequest

Lorsqu’un événement datarequested survient, votre application reçoit un objet DataRequest. Cet objet contient une classe DataPackage que vous utilisez généralement pour fournir le contenu qu’un utilisateur souhaite partager. Toutefois, dans les opérations Pull, vous spécifiez une fonction déléguée à la place des données réelles.

var request = e.request;

Étape 5: Définir les propriétés de titre et de description

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

Étape 6: Définissez les types de fichiers, le cas échéant.

Si vous utilisez une fonction déléguée pour partager les fichiers, vous devez spécifier les types de fichiers que votre application prend en charge.

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

Étape 7: Ajouter la fonction déléguée à l’objet DataPackage

La méthode setDataProvider spécifie la fonction déléguée que vous avez créée pour fournir le contenu réel.

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

À ce stade, lorsque l’utilisateur appuie sur l’icône Partager, l’application est en mesure de répondre instantanément avec un objet DataPackage contenant la fonction déléguée. L’opération de partage peut alors continuer en arrière-plan, ce qui permet à l’utilisateur d’effectuer d’autres tâches en parallèle.

Gardez à l’esprit que si vous utilisez la méthode setStorageItems pour partager des fichiers, celle-ci crée des objets StorageFile en lecture seule destinés au partage et conserve les objets originaux. Cela signifie que si vous ajoutez des propriétés étendues au fichier original après avoir appelé setStorageItems, les nouvelles propriétés étendues ne sont pas prises en compte dans les objets StorageFile en cours de partage. Nous vous recommandons donc d’attendre que vos fichiers soient prêts à être partagés avant de les ajouter.

Remarques

Si une application partage des données en retardant le rendu, elle doit être une application sur une seule page pour éviter la navigation entre plusieurs pages. De plus, si votre application prend en charge la navigation à l’intérieur des cadres, elle doit inscrire les fonctions déléguées dans le contexte de script de niveau supérieur au lieu de les inscrire au niveau des cadres. La navigation entraîne la perte du contexte de script, ce qui invalide les fonctions déléguées et empêche le rendu retardé.

Terminer l’exemple

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());
    }
};