HTML5 File API – Fondamenti

In questa lezione ci occuperemo di un’altra importante specifica relativa ad HTML5, descritta in un documento separato che potete consultare a questo indirizzo, si tratta File APIs che permettono di gestire i files lato client.

File APIs

Poiché lavorare con i files è un task quotidiano, anche sul web, HTML5 finalmente ci fornisce delle APIs standard per farlo. La specifica permette di leggere, scrivere, rimuovere file locali, sincronamente e soprattutto asincronamente.

Pensiamo ad un form che preveda l’invio al server di un file locale tramite un elemento input file: grazie alle APIs avremo finalmente la possibilità di controllare il MIME type lato client prima di inviarlo al server, leggerlo e persino decidere che i contenuti non sono quelli che ci aspettavamo, il tutto senza chiamare in causa il server.

Ci concentreremo sulle operazioni asincrone, quindi parleremo dell’interfaccia FileReader e non di FileReadersync perchè lo stesso draft dice chiaramente:

It is desirable to read data from file systems asynchronously in the main thread of user agents.

L’intero meccanismo gira intorno a quattro oggetti:

FileList

interface FileList {
  getter File? item(unsigned long index);
  readonly attribute unsigned long length;
};

FileList possiede un attributo length che contiene il numero dei files nella lista e un metodo item(index) che ritorna l’oggetto File sito alla posizione index.

Blob

interface Blob {
  
  readonly attribute unsigned long long size;
  readonly attribute DOMString type;
  
  //slice Blob into byte-ranged chunks
  
  Blob slice(optional long long start,
             optional long long end,
             optional DOMString contentType); 

};

Blob rappresenta dati grezzi immutabili. Fornisce il metodo slice per sezionare i dati in pezzi di lunghezza definita. Espone un attributo size (dimensione del Blob) e type (il MIME type del Blob).

File

interface File : Blob {

      readonly attribute DOMString name;
      readonly attribute Date lastModifiedDate;
};

Rappresenta un singolo File nella lista, ottenuto dal filesystem; possiede gli attributi name e la data di ultima modifica lastModifiedDate. File eredita da Blob.

FileReader

[Constructor]
interface FileReader: EventTarget {

  // async read methods
  void readAsArrayBuffer(Blob blob);
  void readAsBinaryString(Blob blob);
  void readAsText(Blob blob, optional DOMString encoding);
  void readAsDataURL(Blob blob);

  void abort();

  // states
  const unsigned short EMPTY = 0;
  const unsigned short LOADING = 1;
  const unsigned short DONE = 2;


  readonly attribute unsigned short readyState;

  // File or Blob data
  readonly attribute any result;

  readonly attribute DOMError error;

  // event handler attributes
  attribute [TreatNonCallableAsNull] Function? onloadstart;
  attribute [TreatNonCallableAsNull] Function? onprogress;
  attribute [TreatNonCallableAsNull] Function? onload;
  attribute [TreatNonCallableAsNull] Function? onabort;
  attribute [TreatNonCallableAsNull] Function? onerror;
  attribute [TreatNonCallableAsNull] Function? onloadend;

};

FileReader espone metodi per leggere oggetti File o Blob in memoria e di accedere ai dati attraverso eventi; permette letture asincrone su oggetti Blob singoli lanciando eventi progress (gestiti dagli event handlers associati) mano a mano che la lettura procede.

Gli event handlers previsti sono:

• onloadstart
• onprogress
• onabort
• onerror
• onload
• onloadend

L’oggetto prevede tre stati, lo stato corrente è ottenibili tramite l’attributo readyState.

• EMPTY (0): l’oggetto è istanziato a enon ci sono letture in corso; è lo stato iniziale.
• LOADING (1): è in corso la lattura di una File o di un Blob tramite uno dei metodi di lettura.
• DONE (2): la lettura del File o Blob è terminata oppure si è verificato un errore oppure la lettura è stata interrotta tramite la chiamata ad abort().

FileReader espone quattro metodi per leggere File e Blob in modo asincrono, ciascuno di essi valorizzerà l’attributo result al termine delle operazioni:

• readAsArrayBuffer: result conterrà i dati del File o del Blob sottoforma di un oggetto ArrayBuffer.
• readAsBinaryString(blob) deprecato in favore di readAsArrayBuffer(blob); result conterrà i dati sottoforma di una bynary string.
• readAsText: result conterrà i dati del File o del Blob sottoforma di stringa (testo) decodificata di default in UTF-8 o nel formato indicato.
• readAsDataURL: result conterrà i dati del File o del Blob sottoforma di URL data.

Una volta invocato uno di questi metodi gli handlers intercetteranno gli avanzamenti dell’operazione.