Exemple : chargement et téléchargement de fichiers -- Flash CS3

L'exemple FileIO présente les techniques de chargement et de téléchargement de fichiers dans Flash Player. Ces techniques sont les suivantes :

Pour obtenir les fichiers d'application pour cet exemple, voir www.adobe.com/go/learn_programmingAS3samples_flash_fr. Les fichiers d'application FileIO se trouvent dans le dossier Samples/FileIO. Cette application se compose des fichiers suivants :

Fichier	Description
FileIO.fla ou FileIO.mxml	Le fichier d'application principal dans Flash (FLA) ou Flex (MXML).
com/example/programmingas3/fileio/FileDownload.as	Classe incluant les méthodes de téléchargement de fichiers à partir d'un serveur.
com/example/programmingas3/fileio/FileUpload.as	Classe incluant les méthodes de chargement de fichiers sur un serveur.

Sous-rubriques

Présentation de l'application FileIO

L'application FileIO contient l'interface utilisateur qui permet de charger ou télécharger des fichiers à l'aide de Flash Player. L'application commence par définir deux composants personnalisés, FileUpload et FileDownload, qui se trouvent dans le package com.example.programmingas3.fileio. Une fois que chaque composant a distribué son événement contentComplete, la méthode init() de chacun est appelée et transmet les références à des occurrences de composant ProgressBar et Button, qui permettent à l'utilisateur de suivre la progression du chargement/téléchargement ou d'annuler le transfert de fichier en cours.

Le code en question dans le fichier FileIO.mxml se présente comme suit (notez que dans la version Flash version, le fichier FLA contient des composants placés sur la scène, dont les noms correspondent à ceux des composants Flex décrits dans cette étape) :

<example:FileUpload id="fileUpload" creationComplete="fileUpload.init(uploadProgress, cancelUpload);" />
<example:FileDownload id="fileDownload" creationComplete="fileDownload.init(downloadProgress, cancelDownload);" />

Le code suivant correspond au panneau de chargement du fichier, qui contient une barre de progression et deux boutons. Le premier bouton, startUpload, appelle la méthode FileUpload.startUpload(), qui elle-même appelle la méthode FileReference.browse(). L'extrait suivant présente le code du panneau de chargement du fichier :

<mx:Panel title="Upload File" paddingTop="10" paddingBottom="10" paddingLeft="10" paddingRight="10">
    <mx:ProgressBar id="uploadProgress" label="" mode="manual" />
    <mx:ControlBar horizontalAlign="right">
        <mx:Button id="startUpload" label="Upload..." click="fileUpload.startUpload();" />
        <mx:Button id="cancelUpload" label="Cancel" click="fileUpload.cancelUpload();" enabled="false" />
    </mx:ControlBar>
</mx:Panel>

Ce code place une instance de composant ProgressBar et deux instances de composant Button sur la scène. Lorsque l'utilisateur clique sur le bouton de chargement startUpload, une boîte de dialogue du système d'exploitation s'affiche pour permettre à l'utilisateur de sélectionner le fichier à charger sur le serveur distant. L'autre bouton, cancelUpload, est désactivé par défaut ; cependant, lorsque l'utilisateur commence le chargement du fichier, ce bouton devient actif et lui permet de mettre fin à tout moment au transfert de fichier.

<mx:Panel title="Download File" paddingTop="10" paddingBottom="10" paddingLeft="10" paddingRight="10">
    <mx:ProgressBar id="downloadProgress" label="" mode="manual" />
    <mx:ControlBar horizontalAlign="right">
        <mx:Button id="startDownload" label="Download..." click="fileDownload.startDownload();" />
        <mx:Button id="cancelDownload" label="Cancel" click="fileDownload.cancelDownload();" enabled="false" />
    </mx:ControlBar>
</mx:Panel>

Ce code est très semblable au code de chargement de fichier. Lorsque l'utilisateur clique sur le bouton de téléchargement startDownload, la méthode FileDownload.startDownload() est appelée. Celle-ci débute le téléchargement du fichier spécifié dans la variable FileDownload.DOWNLOAD_URL. Pendant le téléchargement du fichier, la barre de progression s'actualise pour indiquer le pourcentage du fichier déjà téléchargé. L'utilisateur peut annuler l'opération à tout moment en cliquant sur le bouton cancelDownload, qui arrête immédiatement le téléchargement de fichier en cours.

Téléchargement de fichiers à partir d'un serveur distant

Le téléchargement de fichier à partir d'un serveur distant est géré par la classe flash.net.FileReference et la classe personnalisée com.example.programmingas3.fileio.FileDownload. Lorsque l'utilisateur clique sur le bouton de téléchargement, Flash Player commence à télécharger le fichier spécifié dans la variable com.example.programmingas3.fileio.FileDownload class de la classe FileDownload.

La classe FileDownload commence par définir quatre variables au sein du package com.example.programmingas3.fileio, comme le montre le code suivant :

    /**
     * Coder l'URL du fichier à télécharger sur l'ordinateur de l'utilisateur.
     */
    private const DOWNLOAD_URL:String = "http://www.yourdomain.com/file_to_download.zip";

    /**
     * Créer une instance FileReference pour gérer le téléchargement du fichier.
     */
    private var fr:FileReference;

    /**
     * Définir une référence au composant de téléchargement ProgressBar.
     */
    private var pb:ProgressBar;

    /**
     * Définir une référence au bouton d'annulation qui arrête immédiatement
     * le téléchargement en cours.
     */
    private var btn:Button;

La première variable, DOWNLOAD_URL, contient le chemin d'accès au fichier qui est téléchargé sur l'ordinateur de l'utilisateur lorsque celui-ci clique sur le bouton de téléchargement dans le fichier d'application principal.

La deuxième variable, fr, est un objet FileReference qui est initialisé dans la méthode FileDownload.init() et gérera le téléchargement du fichier distant sur l'ordinateur de l'utilisateur.

Les deux dernières variables, pb et btn, contiennent les références aux instances de composant ProgressBar et Button sur la scène, qui sont initialisées par la méthode FileDownload.init().

Initialisation du composant FileDownload

Le composant FileDownload est initialisé par l'appel de la méthode init() de la classe FileDownload. Cette méthode prend deux paramètres, pb et btn, qui sont des occurrences de composant ProgressBar et Button, respectivement.

    /**
     * Définir des références aux composants et ajouter des écouteurs pour les événements OPEN, 
     * PROGRESS et COMPLETE.
     */
    public function init(pb:ProgressBar, btn:Button):void
    {
        // Définir des références à la barre de progression et au bouton d'annulation,
        // qui sont transmises à partir du script d'appel.
        this.pb = pb;
        this.btn = btn;

        fr = new FileReference();
        fr.addEventListener(Event.OPEN, openHandler);
        fr.addEventListener(ProgressEvent.PROGRESS, progressHandler);
        fr.addEventListener(Event.COMPLETE, completeHandler);
    }

Lancement du téléchargement d'un fichier

Lorsque l'utilisateur clique sur le bouton de téléchargement sur la scène, la méthode startDownload() doit initialiser le processus de téléchargement de fichier. L'extrait suivant illustre la méthode startDownload() :

    /**
     * Lancez le téléchargement du fichier spécifié dans la constante DOWNLOAD_URL.
     */
    public function startDownload():void
    {
        var request:URLRequest = new URLRequest();
        request.url = DOWNLOAD_URL;
        fr.download(request);
    }

D'abord, la méthode startDownload() crée un objet URLRequest et définit l'URL cible sur la valeur définie par la variable DOWNLOAD_URL. Ensuite, la méthode FileReference.download() est appelée et l'objet URLRequest créé est transmis comme paramètre. Le système d'exploitation affiche alors une boîte de dialogue qui invite l'utilisateur à sélectionner un emplacement cible pour le document demandé. Une fois l'emplacement choisi, l'événement open (Event.OPEN) est transmis et la méthode openHandler() appelée.

La méthode openHandler() définit le format de texte de la propriété label du composant ProgressBar et active le bouton d'annulation, qui permet à l'utilisateur d'arrêter immédiatement le téléchargement en cours. La méthode openHandler() se présente comme suit :

    /**
     *  Une fois l'événement OPEN distribué, modifier le libellé de la barre de progression 
     * et activer le bouton d'annulation, qui permet à l'utilisateur de mettre fin 
     * au téléchargement.
     */
    private function openHandler(event:Event):void
    {
        pb.label = "DOWNLOADING %3%%";
        btn.enabled = true;
    }

Surveillance de la progression du téléchargement d'un fichier

Pendant le téléchargement d'un fichier du serveur distant sur l'ordinateur de l'utilisateur, l'événement progress (ProgressEvent.PROGRESS) est distribué à intervalles réguliers. Dès distribution de l'événement progress, la méthode progressHandler() est appelée et le composant ProgressBar sur la scène est actualisé. Le code de la méthode progressHandler() se présente comme suit :

    /**
     * Pendant le téléchargement du fichier, mettez à jour le statut de la barre de progression.
     */
    private function progressHandler(event:ProgressEvent):void
    {
        pb.setProgress(event.bytesLoaded, event.bytesTotal);
    }

L'événement progress contient deux propriétés : bytesLoaded et bytesTotal, qui sont utilisées pour mettre à jour le composant ProgressBar sur la scène. L'utilisateur reçoit ainsi une indication de la quantité de données déjà téléchargée et du restant. Il peut mettre fin au transfert de fichier à tout moment en cliquant sur le bouton d'annulation situé sous la barre de progression.

Si le téléchargement réussit, l'événement complete (Event.COMPLETE) appelle la méthode completeHandler(), qui avertit l'utilisateur de la fin de l'opération et désactive le bouton d'annulation. Le code de la méthode completeHandler() se présente comme suit :

    /**
     * A la fin du téléchargement, modifiez une 
     * dernière fois le libellé de la barre de progression et désactivez le bouton d'annulation car le téléchargement est  
     * terminé.
     */
    private function completeHandler(event:Event):void
    {
        pb.label = "DOWNLOAD COMPLETE";
        btn.enabled = false;
    }

Annulation du téléchargement d'un fichier

L'utilisateur peut à tout moment mettre fin au transfert de fichiers et empêcher le téléchargement d'octets supplémentaires en cliquant sur le bouton d'annulation de la scène. L'extrait suivant présente le code d'annulation du téléchargement :

    /**
     * Annulez le téléchargement du fichier actuel.
     */
    public function cancelDownload():void
    {
        fr.cancel();
        pb.label = "DOWNLOAD CANCELLED";
        btn.enabled = false;
    }

Tout d'abord, le code arrête immédiatement le transfert du fichier, empêchant ainsi le téléchargement de données supplémentaires. Ensuite, la propriété Label de la barre de progression s'actualise pour confirmer à l'utilisateur l'annulation du téléchargement. Enfin, le bouton d'annulation est désactivé, pour empêcher l'utilisateur de recliquer dessus tant qu'une autre tentative de téléchargement n'est pas lancée.

Chargement de fichiers sur un serveur distant

Le processus de chargement de fichier est très semblable au téléchargement. La classe FileUpload déclare les quatre mêmes variables, comme le montre le code suivant :

private const UPLOAD_URL:String = "http://www.yourdomain.com/your_upload_script.cfm";
private var fr:FileReference;
private var pb:ProgressBar;
private var btn:Button;

A la différence de la variable FileDownload.DOWNLOAD_URL, UPLOAD_URL contient l'URL du script côté serveur qui chargera le fichier à partir de l'ordinateur de l'utilisateur. Les trois autres variables ont le même comportement que leurs équivalents dans la classe FileDownload.

Initialisation du composant FileUpload

Le composant FileUpload contient une méthode init(), qui est appelée à partir de l'application principale. Cette méthode prend deux paramètres, pb et btn, qui sont des références aux composants ProgressBar et Button sur la scène. Ensuite, la méthode init() initialise l'objet FileReference défini plus tôt par la classe FileUpload. Enfin, la méthode attribue quatre écouteurs d'événements à l'objet FileReference. Le code de la méthode init() se présente comme suit :

public function init(pb:ProgressBar, btn:Button):void
{
    this.pb = pb;
    this.btn = btn;

    fr = new FileReference();
    fr.addEventListener(Event.SELECT, selectHandler);
    fr.addEventListener(Event.OPEN, openHandler);
    fr.addEventListener(ProgressEvent.PROGRESS, progressHandler);
    fr.addEventListener(Event.COMPLETE, completeHandler);
}

Lancement du chargement d'un fichier

Le chargement du fichier est initialisé lorsque l'utilisateur clique sur le bouton de chargement de la scène, qui appelle la méthode FileUpload.startUpload(). Celle-ci appelle la méthode browse() de la classe FileReference qui entraîne l'affichage par le système d'exploitation d'une boîte de dialogue invitant l'utilisateur à sélectionner le fichier à charger sur le serveur distant. L'extrait suivant présente le code de la méthode startUpload() :

public function startUpload():void
{
    fr.browse();
}

Une fois que l'utilisateur a sélectionné un fichier à charger, l'événement select (Event.SELECT) est distribué, appelant ainsi la méthode selectHandler(). La méthode selectHandler() créé un objet URLRequest et attribue à la propriété URLRequest.url la valeur de la constante UPLOAD_URL définie plus haut dans le code. Enfin, l'objet FileReference charge le fichier sélectionné dans le script côté serveur spécifié. Le code de la méthode selectHandler() se présente comme suit :

private function selectHandler(event:Event):void
{
    var request:URLRequest = new URLRequest();
    request.url = UPLOAD_URL;
    fr.upload(request);
}

Le reste du code de la classe FileUpload est identique au code défini dans la classe FileDownload. Si l'utilisateur souhaite mettre fin au chargement, il peut cliquer à tout moment sur le bouton d'annulation qui définit le libellé de la barre de progression et arrête immédiatement le transfert du fichier. La barre de progression est actualisée dès que l'événement progress (ProgressEvent.PROGRESS) est distribué. De même, une fois que le chargement est terminé, la barre de progression s'actualise pour confirmer à l'utilisateur la réussite du chargement. Le bouton d'annulation est alors désactivé jusqu'à ce que l'utilisateur lance un nouveau transfert de fichier.