Comment recevoir des fichiers (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 ]

Le partage de fichiers nécessite un peu plus de préparation que pour des types de données plus simples, tels que du texte. Au préalable d’une opération de partage de fichiers, vous devez essayer de déterminer combien de temps prendra le traitement de ces fichiers.

Si vous prévoyez que votre application aura besoin de plus de temps pour traiter les fichiers qu’un utilisateur souhaite partager, veillez à appeler la méthode reportStarted avant de commencer leur traitement. Cette méthode s’assure que le système garde votre application active pendant toute la durée du traitement des fichiers. Lorsque votre application a fini le traitement, appelez la méthode reportCompleted pour terminer l’opération de partage. Pour en savoir plus, voir "Notification sur l’état du partage étendu" dans Démarrage rapide : réception d’un contenu partagé.

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.

Instructions

Étape 1: prendre en charge le contrat de partage

Avant que votre application puisse recevoir un contenu partagé, vous devez déclarer qu’elle prend en charge le contrat de partage. Ce contrat indique au système que votre application est apte à recevoir du contenu. Si vous utilisez un modèle Microsoft Visual Studio pour créer votre application, voici comment prendre en charge le contrat de partage cible :

Ouvrez le fichier manifeste (package.appxmanifest).
Ouvrez l’onglet Déclarations.
Choisissez Partage cible dans la liste Déclarations disponibles.
Cliquez sur Ajouter pour ajouter la prise en charge du contrat de partage cible dans votre application.

Étape 2: Spécifiez les types de fichiers pris en charge par votre application.

Vous pouvez spécifier les types de fichiers que votre application prend en charge en précisant leurs extensions dans le manifeste de l’application :

Ouvrez le fichier manifeste.
Dans la section Formats de données, cliquez sur Ajouter.
Tapez l’extension du nom de fichier, tel que ".txt" (sans les guillemets).
Répétez l’étape précédente pour chaque autre type de fichier.

Les étapes précédentes ajoutent la section suivante au manifeste :

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

Remarque Vous n’avez pas besoin de spécifier StorageItems dans la section des formats de données. Leur prise en charge est stipulée dans la section SupportedFileTypes du manifeste. Si votre application prend en charge n’importe quel type de fichier, vous pouvez les spécifier dans le manifeste en consultant Prend en charge tout type de fichier.

Remarque Vous pouvez spécifier un autre point d’entrée lorsque votre application est activée pour le contrat de partage cible. Pour ce faire, modifiez l’entrée de page Démarrage dans la section des paramètres Application de la déclaration Partage cible du manifeste du package. Nous vous recommandons d’utiliser également un fichier JavaScript distinct qui gère l’activation pour cette page. Par exemple, consultez l’Exemple de partage de contenu cible entre applications.

Étape 3: ajouter un gestionnaire d’événements pour savoir à quel moment votre application est activée

Quand un utilisateur sélectionne votre application pour partager du contenu, le système active votre application. Étant donné que cela peut se produire de différentes façons, vous devez ajouter un code qui détecte la raison de l’activation de l’application. Pour ce faire, vérifiez la valeur de la propriété 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) {
        ...
    }
};

Étape 4: Obtenez l’objet ShareOperation.

L’objet ShareOperation contient toutes les données dont votre application a besoin pour obtenir le contenu qu’un utilisateur souhaite partager.

shareOperation = args.detail.shareOperation;

Étape 5: retourner rapidement du gestionnaire d’événements activé.

Le gestionnaire d’événements activated doit retourner rapidement. Mettez en file d’attente un événement asynchrone provenant du gestionnaire d’événements activated pour que le traitement des données de partage ait lieu après le retour de l’événement activé.

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

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

Étape 6: vérifier si l’objet DataPackageView contient des données au format StorageItems

L’objet ShareOperation contient un objet DataPackageView. Cet objet est une version en lecture seule de l’objet DataPackage que l’application source a utilisé pour créer les données. Utilisez cet objet pour voir si le contenu partagé contient des données au format 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.
}

Vérifier que le DataPackage contient le format de données qui vous intéresse est une pratique recommandée, même si votre application ne prend en charge qu’un seul format. Cela facilite la prise en charge d’autres formats de fichiers ultérieurement.

Étape 7: traiter les fichiers

Pour obtenir les fichiers, appelez la méthode 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;
});

Remarque

Le traitement des fichiers peut prendre du temps. Il est important que votre application n’oblige pas l’utilisateur à rester dans l’interface utilisateur de partage en attendant qu’elle termine le chargement et le traitement des données. Sur Windows 8.1, vous pouvez appeler la méthode reportStarted pour indiquer au système que votre application a commencé le traitement du contenu à partager. Le système garde votre application active jusqu’à ce que vous appeliez la méthode reportCompleted, même si l’utilisateur la masque pour revenir à l’application source. Pour plus d’informations, voir « Notification sur l’état du partage étendu », dans Démarrage rapide : réception d’un contenu partagé.

Étape 8: appeler reportCompleted

Lorsque votre application a terminé de partager le contenu, appelez la méthode reportCompleted. Quand vous avez appelé cette méthode, le système masque votre application.

shareOperation.reportCompleted();

Remarques

Consultez notre exemple de code Exemple de partage de contenu cible entre applications pour observer l’intégralité de l’expérience d’une application recevant du texte dans un contexte de partage.

Terminer l’exemple

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