HTML5_FILE_API - Introduzione con esempi.

§ 1. Introduzione

HTML5 fornisce un metodo standard per interagire con i file locali, tramite l'API File.

L'API File definisce le interfacce:

Nota Per verificare se il browser supporta o meno una interfaccia basta eseguire il test: window.nomeInterfaccia.

Il tuo browser:

§ 1.1 FileList

FileList è l'oggetto restituito da un elemento html input di tipo file: <input type="file" id="FileSelezionati" multiple>, come il seguente:

.

La finestra che si apre premendo il pulsante "ScegliFile" consente di esplorare il file system accessibile all'utente corrente della pagina web e selezionare uno o più file.

Nota Se nell'elemento input avessimo omesso l'attributo "multiple" avremmo potuto selezionare solo un file alla volta.

Il seguente frammento di codice consente di illustrare le proprietà e i metodi dell'oggetto FileList restituito dall'elemento di input di questo paragrafo quando si selezionano uno o più file. 

document.getElementById("FileSelezionati").addEventListener("change", changeHandler, false);
function changeHandler(event){
   var prop = [];
   prop.push('<p>Tipo di oggetto restituito, (event.target.files)------------ > '+ event.target.files +'</p>');
   prop.push('<p>Numero di elementi in FileList, (event.target.files.length)- > '+ event.target.files.length+'</p>');
   for (var i=0; i < event.target.files.length; i++){
      prop.push('<p>event.target.files.item('+i+').name --------------------- > '+ event.target.files.item(i).name + "</p>"); 
   }
   document.getElementById('output1').innerHTML = prop.join('');
}
output 1

L'oggetto FileList è un array di nome files e quindi possiede la property length. I suoi elementi sono oggetti file o blob che possono essere referenziati direttamente tramite indice files[indice] o con il metodo item(indice), come mostrato sopra.

§ 1.2 Blob

Blob sta per Binary Large Object.
Un oggetto blob altro non è che una sequenza di byte dotata di un attributo size, che rappresenta il numero totale di byte che lo compone, e di un attributo type che rappresenta il tipo di media della sequenza di byte.
Viene qui introdotto perché gli oggetti file altro non sono che una estensione degli oggetti blob.

Blob possiede un metodo slice() che consente di creare un nuovo oggetto blob contente i dati in uno specificato range di byte del blob sorgente.

§ 1.2.1 Metodo slice

Sintassi

var blob=blobSorgente([start [, end [, contentType]]]);

Parametri

start |Opzionale. Indice del primo byte incluso nel nuovo blob. Valore di default 0. Ammette valori negativi nel qual caso è trattato come un offset rispetto alla fine del blob.

end |Opzionale. Indice del primo byte non incluso nel nuovo blob. Valore di default size. Ammette valori negativi nel qual caso è trattato come un offset rispetto alla fine del blob.

contentType |Opzionale. Content type del nuovo blob. Valore di default empty.

§ 1.3 File

L'interfaccia File permette a JavaScript di accedere al contenuto dei file.

Gli oggetti file possono essere restituiti dagli oggetti FileList in seguito alla selezione di file operata mediante un elemento html input come visto sopra, oppure da un oggetto DataDransfer in seguito ad un operazione di drag and drop.

Le property dell'oggetto file sono:

Il seguente frammento di codice consente di illustrare le proprietà dei file restituiti dell'oggetto FileList restituito dall'elemento di input che segue e che è stato così definito:

<input type="file" id="File">, come il seguente:

. 
document.getElementById("File").addEventListener("change", changeHandler, false);
function changeHandler(event){
   var prop = [];
   prop.push('<p>Nome: ' + event.target.files[0].name + '<p>');
   prop.push('<p>Size: ' + event.target.files[0].size + 'byte<p>');
   prop.push('<p>Type: ' + event.target.files[0].type + '<p>');
   prop.push('<p>Ultima modifica: ' + event.target.files[0].lastModified + ' / ' +event.target.files[0].lastModifiedDate.toLocalDateString() + '<p>');
   document.getElementById('output2').innerHTML = prop.join('');
}
output 2

§ 1.4 URL

URL sta per Uniform Resource Locator.
L'interfaccia URL rappresenta un oggetto dotato di metodi statici usati per creare oggetti URL.

la window.location:

§ 1.5 FileReader

L'oggetto FileReader permette alle applicazioni web di leggere in maniera asincrona il contenuto di file (o di buffer di dati) memorizzati nel computer dell'utente, usando gli oggetti File o Blob per specificare i dati da leggere.

Gli oggetti file possono essere restituiti dagli oggetti FileList in seguito alla selezione di file operata mediante un elemento html input come visto sopra, oppure da un oggetto DataDransfer in seguito ad un operazione di drag and drop.

Costruttore

Per creare un oggetto FileReader usare la seguente sintassi:

var reader= new FileReader();

Eventi

Un oggetto FileReader può generare i seguenti eventi:

Properties

Un oggetto FileReader possiede le seguenti properties:

Metodi

Un oggetto FileReader possiede i seguenti metodi:

Esempi di utilizzo di FileReader

Il seguente frammento di codice mostra come instanziare ed usare un FileReader per leggere il file dell'oggetto FileList restituito dall'elemento di input che segue e che è stato così definito:

<input type="file" id="FileQualsiasi">, come il seguente:

.
Qui saranno visualizzate le informazioni sul file selezionato:
Qui sarà visualizzato il contenuto dei file di tipo text o di tipo immagine.
Image preview... 

var f;
var reader = new FileReader()
reader.addEventListener('abort', suEventoAbort, false);
reader.addEventListener('error', suEventoError, false);
reader.addEventListener('load', suEventoLoad, false);
reader.addEventListener('loadstart', suEventoLoadStart, false);
reader.addEventListener('loadend', suEventoLoadEnd, false);
reader.addEventListener('progress', suEventoProgress, false);

function suEventoAbort(e){
  console.log('event ' + e.type + ' reader.readyState: ' + reader.readyState ); 
}
function suEventoError(e){
  console.log('event ' + e.type + ' reader.readyState: ' + reader.readyState ); 
}
function suEventoLoad(e){
   console.log('event ' + e.type + ' reader.readyState: ' + reader.readyState ); 
   console.log('event bubbles: ' + e.bubbles);
   console.log('event cancelable: ' + e.cancelable);
   console.log('e.target.result.length: '+ e.target.result.length);
   if (f.type.match('text.*')){
      document.getElementById('target').innerHTML = e.target.result.replace(/(?:\r\n|\r|\n)/g, '<br />');
   } else if(f.type.match('image.*')){
      document.getElementById('immagine').src = e.target.result;
   }
}
function suEventoLoadStart(e){
  console.log('event ' + e.type + ' reader.readyState: ' + reader.readyState ); 
}
function suEventoLoadEnd(e){
  console.log('event ' + e.type + ' reader.readyState: ' + reader.readyState ); 
}
function suEventoProgress(e){
  console.log('event ' + e.type + ' reader.readyState: ' + reader.readyState ); 
}
document.getElementById("FileQualsiasi").addEventListener("change", changeHandler, false);
function changeHandler(event){
   if (event.target.files.length>0){
      f=event.target.files[0];
      var prop = [];
      prop.push('<p>Nome: ' + f.name + '<p>');
      prop.push('<p>Tipo: ' + f.type + '<p>');
      document.getElementById('output4').innerHTML = prop.join('');
      if (f.type.match('image.*')){
         reader.readAsDataURL(f);         
      }else if(f.type.match('text.*')){
         reader.readAsText(f,'UTF 8');
      }else{
      alert ("file type non valido: " . f.type);
      } 
   }   
}