Esempio: Caricamento e scaricamento di file -- Flash CS3

Nell'esempio FileIO vengono illustrate le tecniche necessarie per eseguire lo scaricamento e il caricamento di file in Flash Player, descritte di seguito:

Per ottenere i file dell'applicazione per questo esempio, accedere all'indirizzo www.adobe.com/go/learn_programmingAS3samples_flash_it. I file dell'applicazione FileIO sono disponibili nella cartella Samples/FileIO. L'applicazione è costituita dai seguenti file:

File	Descrizione
FileIO.fla oppure FileIO.mxml	Il file principale dell'applicazione in Flash (FLA) o Flex (MXML)
com/example/programmingas3/fileio/FileDownload.as	Una classe che include i metodi per scaricare i file da un server.
com/example/programmingas3/fileio/FileUpload.as	Una classe che include i metodi per caricare i file su un server.

Sezioni

Panoramica dell'applicazione FileIO

L'applicazione FileIO include l'interfaccia utente che consente a un utente di caricare o scaricare file utilizzando Flash Player. L'applicazione definisce innanzitutto due componenti personalizzati, FileUpload e FileDownload, contenuti nel pacchetto com.example.programmingas3.fileio. Dopo l'invio dell'evento contentComplete da parte di ogni componente personalizzato, viene chiamato il metodo init() del componente e vengono passati i riferimenti a un'istanza dei componenti ProgressBar e Button, che consente agli utenti di visualizzare l'avanzamento del caricamento o dello scaricamento di un file o l'annullamento del trasferimento di file in corso.

Il codice pertinente del file FileIO.mxml è il seguente (si noti che nella versione Flash, il file FLA contiene dei componenti posizionati sullo stage, i cui nomi corrispondono a quelli dei componenti Flex descritti in questa operazione):

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

Il codice riportato di seguito illustra il pannello di caricamento dei file che contiene una barra di avanzamento e due pulsanti. Il primo pulsante, startUpload, chiama il metodo FileUpload.startUpload(), che a propria volta chiama il metodo FileReference.browse(). Di seguito è riportato un estratto del codice per il pannello di caricamento dei file:

<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>

Questo codice colloca un'istanza del componente ProgressBar e due istanze del componente Button sullo stage. Quando l'utente fa clic sul pulsante di caricamento (startUpload), viene aperta una finestra di dialogo del sistema operativo che consente all'utente di selezionare un file da caricare su un server remoto. L'altro pulsante, cancelUpload, è disattivato per impostazione predefinita, tuttavia quando un utente inizia il caricamento di un file, il pulsante viene attivato e consente di interrompere il trasferimento del file in qualsiasi momento.

<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>

Questo codice è molto simile a quello utilizzato per il caricamento dei file. Quando l'utente fa clic sul pulsante di scaricamento, (startDownload), viene chiamato il metodo FileDownload.startDownload() che inizia lo scaricamento del file specificato nella variabile FileDownload.DOWNLOAD_URL. Mentre il file viene scaricato, la barra di avanzamento viene aggiornata e mostra la percentuale del file già scaricata. L'utente può annullare lo scaricamento in qualsiasi momento facendo clic sul pulsante cancelDownload, che interrompe immediatamente l'avanzamento dell'operazione.

Scaricamento di file da un server remoto

Lo scaricamento dei file da un server remoto viene gestito dalla classe flash.net.FileReference e dalla classe personalizzata com.example.programmingas3.fileio.FileDownload. Quando l'utente fa clic sul pulsante di scaricamento, inizia automaticamente lo scaricamento del file specificato nella variabile DOWNLOAD_URL della classe FileDownload.

La classe FileDownload definisce innanzitutto quattro variabili contenute nel pacchetto com.example.programmingas3.fileio, come illustrato dal codice riportato di seguito:

    /**
     * Specifica a livello di codice l'URL del file da scaricare sul computer dell'utente.
     */
    private const DOWNLOAD_URL:String = "http://www.yourdomain.com/file_to_download.zip";

    /**
     * Crea un'istanza di FileReference per gestire lo scaricamento del file.
     */
    private var fr:FileReference;

    /**
     * Definisce il riferimento al componente ProgressBar di scaricamento.
     */
    private var pb:ProgressBar;

    /**
     * Definisce il riferimento al pulsante di annullamento che arresterà
     * immediatamente lo scaricamento attualmente in corso.
     */
    private var btn:Button;

La prima variabile, DOWNLOAD_URL, contiene il percorso del file che viene scaricato nel computer dell'utente quando quest'ultimo fa clic sul pulsante di scaricamento nel file dell'applicazione principale.

La seconda variabile, fr, è un oggetto FileReference che viene inizializzato nel metodo FileDownload.init() e gestisce lo scaricamento del file remoto nel computer dell'utente.

Le ultime due variabili, pb e btn, contengono i riferimenti alle istanze dei componenti ProgressBar e Button sullo stage, che vengono inizializzate dal metodo FileDownload.init().

Inizializzazione del componente FileDownload

Il componente FileDownload viene inizializzato mediante la chiamata al metodo init() nella classe FileDownload. Questo metodo accetta due parametri, pb e btn, che corrispondono rispettivamente alle istanze dei componenti ProgressBar e Button.

    /**
     * Imposta i riferimenti ai componenti e aggiunge i listener per gli  
     * eventi OPEN, PROGRESS e COMPLETE.
     */
    public function init(pb:ProgressBar, btn:Button):void
    {
        // Imposta i riferimenti alla barra di avanzamento e al pulsante di 
        // annullamento, che vengono passati dallo script chiamante.
        this.pb = pb;
        this.btn = btn;

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

Inizio dello scaricamento del file

Quando l'utente fa clic sull'istanza del componente Download Button sullo stage, il metodo startDownload() inizia il processo di scaricamento del file. Nell'estratto di codice riportato di seguito viene illustrato il metodo startDownload():

    /**
     * Inizia a scaricare il file specificato nella costante DOWNLOAD_URL.
     */
    public function startDownload():void
    {
        var request:URLRequest = new URLRequest();
        request.url = DOWNLOAD_URL;
        fr.download(request);
    }

Il metodo startDownload() crea innanzitutto un nuovo oggetto URLRequest e imposta l'URL di destinazione sul valore specificato dalla variabile DOWNLOAD_URL. Viene quindi chiamato il metodo FileReference.download() e l'oggetto URLRequest appena creato viene passato come parametro. Viene quindi aperta una finestra di dialogo del sistema operativo sul computer dell'utente che richiede di selezionare un percorso in cui salvare il documento richiesto. Dopo che l'utente ha selezionato un percorso, viene inviato l'evento open (Event.OPEN) e viene richiamato il metodo openHandler().

Il metodo openHandler() imposta il formato di testo per la proprietà label del componente ProgressBar e attiva il pulsante di annullamento che consente all'utente di arrestare immediatamente lo scaricamento in corso. Di seguito è riportato il metodo openHandler():

    /**
     * Quando viene inviato l'evento OPEN, modificare l'etichetta della barra 
     * di avanzamento e attivare il pulsante di annullamento che consente  
     * all'utente di interrompere l'operazione di scaricamento.
     */
    private function openHandler(event:Event):void
    {
        pb.label = "DOWNLOADING %3%%";
        btn.enabled = true;
    }

Controllo dell'avanzamento dell'operazione di scaricamento di un file

Mentre viene scaricato un file da un server remoto nel computer dell'utente, viene inviato a intervalli regolari l'evento progress (ProgressEvent.PROGRESS). Ogni volta che viene inviato l'evento progress, viene richiamato il metodo progressHandler() e l'istanza del componente ProgressBar sullo stage viene aggiornata. Di seguito è riportato il codice per il metodo progressHandler():

    /**
     * Durante lo scaricamento del file, aggiornare lo stato della barra di avanzamento.
     */
    private function progressHandler(event:ProgressEvent):void
    {
        pb.setProgress(event.bytesLoaded, event.bytesTotal);
    }

L'evento progress ha due proprietà, bytesLoaded e bytesTotal, che vengono utilizzate per aggiornare il componente ProgressBar sullo stage e mostrano all'utente la quantità di file scaricata rispetto alla quantità rimanente. L'utente può interrompere il trasferimento del file in qualsiasi momento facendo clic sul pulsante di annullamento sotto la barra di avanzamento.

Se il file viene scaricato correttamente, l'evento complete (Event.COMPLETE) richiama il metodo completeHandler(), che comunica all'utente che lo scaricamento del file è stato completato e disattiva il pulsante di annullamento. Di seguito è riportato il codice per il metodo completeHandler():

    /**
     * Una volta completato lo scaricamento, modificare per l'ultima volta 
     * l'etichetta della barra di avanzamento e disabilitare il pulsante  
     * "Annulla", poiché lo scaricamento è già stato completato.
     */
    private function completeHandler(event:Event):void
    {
        pb.label = "DOWNLOAD COMPLETE";
        btn.enabled = false;
    }

Annullamento dello scaricamento del file

L'utente può interrompere il trasferimento del file e interrompere lo scaricamento di ulteriori byte in qualsiasi momento facendo clic sul pulsante di annullamento presente sullo stage. Di seguito è riportato un estratto del codice per annullare lo scaricamento:

    /**
     * Annullare lo scaricamento corrente del file.
     */
    public function cancelDownload():void
    {
        fr.cancel();
        pb.label = "DOWNLOAD CANCELLED";
        btn.enabled = false;
    }

Innanzi tutto, il codice interrompe immediatamente il trasferimento del file impedendo lo scaricamento di ulteriori dati. Quindi, la proprietà label della barra di avanzamento viene aggiornata per informare l'utente che lo scaricamento è stato annullato. Infine, il pulsante di annullamento viene disattivato, impedendo all'utente di fare clic sul pulsante finché non tenterà di nuovo di scaricare il file.

Caricamento di file su un server remoto

Il processo di caricamento dei file è molto simile a quello per lo scaricamento. La classe FileUpload dichiara le stesse quattro variabili, come illustrato nel codice seguente:

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 differenza della variabile FileDownload.DOWNLOAD_URL, la variabile UPLOAD_URL contiene l'URL per lo script sul lato server che caricherà il file dal computer dell'utente. Il comportamento delle tre variabili è analogo a quello delle relative controparti nella classe FileDownload.

Inizializzazione del componente FileUpload

Il componente FileUpload contiene un metodo init(), che viene chiamato dall'applicazione principale. Questo metodo accetta due parametri, pb e btn, che fanno riferimento rispettivamente a un'istanza dei componenti ProgressBar e Button sullo stage. Quindi il metodo init() inizializza l'oggetto FileReference definito precedentemente nella classe FileUpload. Infine, il metodo assegna quattro listener di eventi all'oggetto FileReference. Di seguito è riportato il codice per il metodo init():

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

Inizio del caricamento del file

Il caricamento del file ha inizio quando l'utente fa clic sul pulsante di caricamento sullo stage, che richiama il metodo the FileUpload.startUpload(). Questo metodo chiama il metodo browse() della classe FileReference, che attiva la visualizzazione di una finestra di dialogo del sistema operativo in cui viene richiesto all'utente di selezionare un file da caricare sul server remoto. Di seguito è riportato un estratto del codice per il metodo startUpload():

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

Dopo che l'utente ha selezionato un file da caricare, viene inviato l'evento select (Event.SELECT) che richiama il metodo selectHandler(). Il metodo selectHandler() crea un nuovo oggetto URLRequest e imposta la proprietà URLRequest.url sul valore dalla costante UPLOAD_URL definito precedentemente nel codice. Infine, l'oggetto FileReference carica il file selezionato nello script sul lato server specificato. Di seguito è riportato il codice per il metodo selectHandler():

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

Il codice rimanente nella classe FileUpload è lo stesso di quello definito nella classe FileDownload. Se in qualsiasi momento l'utente desidera terminare il caricamento, può fare clic sul pulsante di annullamento, che imposta l'etichetta sulla barra di avanzamento e interrompe immediatamente il trasferimento del file. La barra di avanzamento viene aggiornata ogni volta che viene inviato l'evento progress (ProgressEvent.PROGRESS). In modo analogo, una volta completato il caricamento, la barra di avanzamento viene aggiornata per informare l'utente che il file è stato caricato. Il pulsante di annullamento viene quindi disattivato finché l'utente non inizia un nuovo trasferimento di file.