Crea app con AngularJS

Importante: Chrome rimuoverà il supporto per le app di Chrome su tutte le piattaforme. Il browser Chrome e il Chrome Web Store continueranno a supportare le estensioni. Leggi l'annuncio e scopri di più sulla migrazione della tua app.

Questa guida ti insegna a iniziare a creare app di Chrome con il framework MVC AngularJS. Per illustrare Angular in azione, faremo riferimento a un'app effettiva creata utilizzando il framework, l'Uploader di Google Drive. Il codice sorgente è disponibile su GitHub.

Informazioni sull'app

L'Uploader di Google Drive consente agli utenti di visualizzare e interagire rapidamente con i file archiviati nel loro account Google Drive, nonché di caricare nuovi file utilizzando le API di trascinamento dell'HTML. È un ottimo esempio di creazione di un'app che comunica con una delle API di Google, in questo caso l'API Google Drive.

Nota: puoi anche creare app che comunicano con API/servizi di terze parti abilitati per OAuth2. Consulta la pagina relativa all'autenticazione di un Account non Google.

L'utente che carica il video utilizza OAuth2 per accedere ai dati dell'utente. L'API chrome.identity gestisce il recupero di un token OAuth per l'utente che ha eseguito l'accesso, quindi il lavoro più impegnativo spetta a noi. Una volta che disponiamo di un token di accesso di lunga durata, le app utilizzano l'API Google Drive per accedere ai dati dell'utente.

Funzionalità principali utilizzate da questa app:

• Rilevamento automatico di AngularJS per CSP
• Visualizza un elenco di file recuperati dall'API Google Drive
• API HTML5 Filesystem per memorizzare le icone dei file offline
• Trascinamento HTML5 per importare/caricare nuovi file dal desktop
• XHR2 per caricare immagini, interdominio
• API chrome.identity per l'autorizzazione OAuth
• Frame chromeless per definire l'aspetto e il design della barra di navigazione

Creazione del manifest

Tutte le app di Chrome richiedono un file manifest.json che contenga le informazioni necessarie a Chrome per avviare l'app. Il file manifest contiene metadati pertinenti ed elenca eventuali autorizzazioni speciali che l'app deve eseguire.

Una versione ridotta del file manifest dell'utente che carica il video ha il seguente aspetto:

{
  "name": "Google Drive Uploader",
  "version": "0.0.1",
  "manifest_version": 2,
  "oauth2": {
    "client_id": "665859454684.apps.googleusercontent.com",
    "scopes": [
      "https://www.googleapis.com/auth/drive"
    ]
  },
 ...
  "permissions": [
    "https://docs.google.com/feeds/",
    "https://docs.googleusercontent.com/",
    "https://spreadsheets.google.com/feeds/",
    "https://ssl.gstatic.com/",
    "https://www.googleapis.com/"
  ]
}

Le parti più importanti di questo manifest sono le sezioni "oauth2" e "permissions".

La sezione "oauth2" definisce i parametri richiesti da OAuth2 per fare la sua magia. Per creare un "client_id", segui le istruzioni in Ottenere il tuo ID client. Gli "ambiti" elencano gli ambiti di autorizzazione per i quali sarà valido il token OAuth (ad esempio, le API a cui l'app vuole accedere).

La sezione "autorizzazioni" include gli URL a cui l'app accederà tramite XHR2. I prefissi URL sono necessari per consentire a Chrome di sapere quali richieste interdominio consentire.

Creazione della pagina dell'evento

Tutte le app di Chrome richiedono uno script/una pagina in background per avviarle e rispondere agli eventi di sistema.

Nel suo script background.js, il programma di caricamento di Drive apre una finestra di 500 x 600 px nella pagina principale. Specifica inoltre un'altezza e una larghezza minime per la finestra, in modo che i contenuti non risultino eccessivamente elaborati:

chrome.app.runtime.onLaunched.addListener(function(launchData) {
  chrome.app.window.create('../main.html', {
    id: "GDriveExample",
    bounds: {
      width: 500,
      height: 600
    },
    minWidth: 500,
    minHeight: 600,
    frame: 'none'
  });
});

La finestra viene creata come finestra chromeless (frame: "none"). Per impostazione predefinita, il rendering delle finestre con la barra predefinita del sistema operativo di chiusura/espansione/riduci a icona:

L'utente che carica il video utilizza frame: 'none' per eseguire il rendering della finestra come "slate vuoto" e crea un pulsante di chiusura personalizzato in main.html:

L'intera area di navigazione è a capo

(vedi la sezione successiva). Per snellire leggermente l'app, il pulsante di chiusura personalizzato è nascosto fino a quando l'utente non interagisce con quest'area:

<style>
nav:hover #close-button {
  opacity: 1;
}

#close-button {
  float: right;
  padding: 0 5px 2px 5px;
  font-weight: bold;
  opacity: 0;
  transition: all 0.3s ease-in-out;
}
</style>

<button class="btn" id="close-button" title="Close">x</button>

In app.js, questo pulsante è collegato a window.close().

Progettare l'app in modo angolare

Angular è un framework MVC, quindi dobbiamo definire l'app in modo che un modello, una vista e un controller ne escano logicamente. Fortunatamente, questo è banale quando si utilizza Angular.

La visualizzazione è la più semplice, iniziamo da qui.

Creazione della vista

main.html è la "V" in MVC, in cui definiamo i modelli HTML in cui eseguire il rendering dei dati. In Angular, i modelli sono semplici blocchi di HTML con un tocco speciale.

In definitiva, vogliamo mostrare l'elenco di file dell'utente. Per questo motivo,

. I bit Angular sono evidenziati in grassetto:

<ul>
  <li data-ng-repeat="doc in docs">
    <img data-ng-src=""> <a href=""></a>

    <span class="date"></span>
  </li>
</ul>

Ecco come appare: esprimi un

• per ogni documento nel nostro modello di dati "documenti". Ogni elemento contiene un'icona del file, un link per aprire il file sul web e l'ultimo aggiornamento data.
  Nota: per rendere il modello HTML valido, stiamo utilizzando gli attributi data-* per l'iteratore ngRepeat di Angular, ma non è obbligatorio. Puoi facilmente scrivere il ripetitore come <li ng-repeat="doc in docs">.

  Successivamente, dobbiamo indicare ad Angular quale controller supervisionerà il rendering di questo modello. Per questo motivo, utilizziamo l'istruzione ngController per indicare a DocsController di controllare il modello:

  <body data-ng-controller="DocsController">
  <section id="main">
    <ul>
      <li data-ng-repeat="doc in docs">
        <img data-ng-src=""> <a href=""></a> 
        <span class="date"></span>
      </li>
    </ul>
  </section>
  </body>
  

  Tieni presente che ciò che non vedi qui è che colleghiamo i listener di eventi o le proprietà per l'associazione dei dati. Angular ci sta facendo la differenza!

  L'ultimo passaggio consiste nel rendere Angular illuminare i nostri modelli. In genere questo è possibile includere l'istruzione ngApp fino a :

  <html data-ng-app="gDriveApp">
  

  Se vuoi, puoi anche ridurre l'ambito dell'app a una parte più piccola della pagina. Abbiamo un solo controller in questa app, ma se dovessimo aggiungerne altri in seguito, mettendo ngApp nell'elemento più in alto, l'intera pagina sarà pronta per Angular.

  Il prodotto finale per main.html ha il seguente aspetto:

  <html data-ng-app="gDriveApp">
  <head>
    …
  
    <base target="_blank">
  </head>
  <body data-ng-controller="DocsController">
  <section id="main">
    <nav>
      <h2>Google Drive Uploader</h2>
      <button class="btn" data-ng-click="fetchDocs()">Refresh</button>
      <button class="btn" id="close-button" title="Close"></button>
    </nav>
    <ul>
      <li data-ng-repeat="doc in docs">
        <img data-ng-src=""> <a href=""></a>  
        <span class="date"></span>
      </li>
    </ul>
  </section>
  

  Due parole sui criteri di sicurezza del contenuto

  A differenza di molti altri framework JS MVC, Angular v1.1.0 e versioni successive non richiede modifiche per funzionare all'interno di un rigoroso CSP. Funziona immediatamente.

  Tuttavia, se utilizzi una versione precedente di Angular tra le versioni 1.0.1 e 1.1.0, dovrai indicare ad Angular di eseguirla in "modalità di sicurezza dei contenuti". Per farlo, includi l'istruzione ngCsp insieme a ngApp:

  <html data-ng-app data-ng-csp>
  

  Gestione dell'autorizzazione

  Il modello dei dati non viene generato dall'app stessa. ma viene compilato da un'API esterna (l'API Google Drive). Di conseguenza, è necessario un po' di lavoro per completare i dati dell'app.

  Prima di poter effettuare una richiesta API, dobbiamo recuperare un token OAuth per l'Account Google dell'utente. Per questo abbiamo creato un metodo per eseguire il wrapping della chiamata a chrome.identity.getAuthToken() e archiviare l'accessToken, che possiamo riutilizzare per future chiamate all'API Drive.

  GDocs.prototype.auth = function(opt_callback) {
    try {
      chrome.identity.getAuthToken({interactive: false}, function(token) {
        if (token) {
          this.accessToken = token;
          opt_callback && opt_callback();
        }
      }.bind(this));
    } catch(e) {
      console.log(e);
    }
  };
  

  Nota: se passi il callback facoltativo, puoi sapere quando il token OAuth è pronto.
  Nota: per semplificare un po' le cose, abbiamo creato una libreria, gdocs.js, per gestire le attività delle API.

  Una volta ottenuto il token, è il momento di effettuare richieste tramite l'API Drive e compilare il modello.

  Controller scheletro

  Il "modello" per l'Uploader è un semplice array (chiamato documenti) di oggetti che verrà visualizzato come

• s nel modello:

  var gDriveApp = angular.module('gDriveApp', []);
  
  gDriveApp.factory('gdocs', function() {
    var gdocs = new GDocs();
    return gdocs;
  });
  
  function DocsController($scope, $http, gdocs) {
    $scope.docs = [];
  
    $scope.fetchDocs = function() {
       ...
    };
  
    // Invoke on ctor call. Fetch docs after we have the oauth token.
    gdocs.auth(function() {
      $scope.fetchDocs();
    });
  
  }
  

  Nota che gdocs.auth() viene chiamato come parte del costruttore DocsController. Quando gli interni di Angular creano il controller, usufruiamo di un nuovo token OAuth in attesa dell'utente.

  Recupero dati

  Modello strutturato. Controller impalcato. Il token OAuth in uso. Ti chiedi cosa fare adesso?

  È il momento di definire il metodo principale del controller, fetchDocs(). È il cavallo di lavoro del controller, responsabile della richiesta dei file dell'utente e dell'archiviazione dell'array di documenti con i dati delle risposte dell'API.

  $scope.fetchDocs = function() {
    $scope.docs = []; // First, clear out any old results
  
    // Response handler that doesn't cache file icons.
    var successCallback = function(resp, status, headers, config) {
      var docs = [];
      var totalEntries = resp.feed.entry.length;
  
      resp.feed.entry.forEach(function(entry, i) {
        var doc = {
          title: entry.title.$t,
          updatedDate: Util.formatDate(entry.updated.$t),
          updatedDateFull: entry.updated.$t,
          icon: gdocs.getLink(entry.link,
                              'http://schemas.google.com/docs/2007#icon').href,
          alternateLink: gdocs.getLink(entry.link, 'alternate').href,
          size: entry.docs$size ? '( ' + entry.docs$size.$t + ' bytes)' : null
        };
  
        $scope.docs.push(doc);
  
        // Only sort when last entry is seen.
        if (totalEntries - 1 == i) {
          $scope.docs.sort(Util.sortByDate);
        }
      });
    };
  
    var config = {
      params: {'alt': 'json'},
      headers: {
        'Authorization': 'Bearer ' + gdocs.accessToken,
        'GData-Version': '3.0'
      }
    };
  
    $http.get(gdocs.DOCLIST_FEED, config).success(successCallback);
  };
  

  fetchDocs() utilizza il servizio $http di Angular per recuperare il feed principale tramite XHR. Il token di accesso OAuth è incluso nell'intestazione Authorization insieme ad altri parametri e intestazioni personalizzati.

  successCallback elabora la risposta API e crea un nuovo oggetto doc per ogni voce nel feed.

  Se al momento esegui fetchDocs(), tutto funziona e viene visualizzato l'elenco dei file:

  

  Evviva!

  Aspetta, ci mancano queste bellissime icone di file. What gives? Un rapido controllo della console mostra una serie di errori relativi a CSP:

  

  Il motivo è che stiamo cercando di impostare le icone img.src su URL esterni. Ciò costituisce una violazione delle norme CSP. Ad esempio: https://ssl.gstatic.com/docs/doclist/images/icon_10_document_list.png. Per risolvere il problema, dobbiamo recuperare questi asset remoti localmente nell'app.

  Importazione di asset di immagini remote

  Affinché CSP smetta di urlare contro di noi, utilizziamo XHR2 per "importare" le icone dei file come BLOB, quindi impostiamo img.src su un blob: URL creato dall'app.

  Ecco il successCallback aggiornato con il codice XHR aggiunto:

  var successCallback = function(resp, status, headers, config) {
    var docs = [];
    var totalEntries = resp.feed.entry.length;
  
    resp.feed.entry.forEach(function(entry, i) {
      var doc = {
        ...
      };
  
      $http.get(doc.icon, {responseType: 'blob'}).success(function(blob) {
        console.log('Fetched icon via XHR');
  
        blob.name = doc.iconFilename; // Add icon filename to blob.
  
        writeFile(blob); // Write is async, but that's ok.
  
        doc.icon = window.URL.createObjectURL(blob);
  
        $scope.docs.push(doc);
  
        // Only sort when last entry is seen.
        if (totalEntries - 1 == i) {
          $scope.docs.sort(Util.sortByDate);
        }
      });
    });
  };
  

  Ora che CSP è di nuovo soddisfatto di noi, otteniamo simpatiche icone di file:

  

  Andare offline: memorizzazione nella cache di risorse esterne

  L'ovvio ottimizzazione da apportare: non effettuare centinaia di richieste XHR per ogni icona di file in ogni chiamata a fetchDocs(). Verifica questa preferenza nella console Strumenti per sviluppatori premendo più volte il pulsante "Aggiorna". Ogni volta, vengono recuperate n immagini:

  

  Modifichiamo successCallback per aggiungere un livello di memorizzazione nella cache. Le aggiunte sono evidenziate in grassetto:

  $scope.fetchDocs = function() {
    ...
  
    // Response handler that caches file icons in the filesystem API.
    var successCallbackWithFsCaching = function(resp, status, headers, config) {
      var docs = [];
      var totalEntries = resp.feed.entry.length;
  
      resp.feed.entry.forEach(function(entry, i) {
        var doc = {
          ...
        };
  
        // 'https://ssl.gstatic.com/doc_icon_128.png' -> 'doc_icon_128.png'
        doc.iconFilename = doc.icon.substring(doc.icon.lastIndexOf('/') + 1);
  
        // If file exists, it we'll get back a FileEntry for the filesystem URL.
        // Otherwise, the error callback will fire and we need to XHR it in and
        // write it to the FS.
        var fsURL = fs.root.toURL() + FOLDERNAME + '/' + doc.iconFilename;
        window.webkitResolveLocalFileSystemURL(fsURL, function(entry) {
          doc.icon = entry.toURL(); // should be === to fsURL, but whatevs.
  
          $scope.docs.push(doc); // add doc to model.
  
          // Only want to sort and call $apply() when we have all entries.
          if (totalEntries - 1 == i) {
            $scope.docs.sort(Util.sortByDate);
            $scope.$apply(function($scope) {}); // Inform angular that we made changes.
          }
  
        }, function(e) {
          // Error: file doesn't exist yet. XHR it in and write it to the FS.
  
          $http.get(doc.icon, {responseType: 'blob'}).success(function(blob) {
            console.log('Fetched icon via XHR');
  
            blob.name = doc.iconFilename; // Add icon filename to blob.
  
            writeFile(blob); // Write is async, but that's ok.
  
            doc.icon = window.URL.createObjectURL(blob);
  
            $scope.docs.push(doc);
  
            // Only sort when last entry is seen.
            if (totalEntries - 1 == i) {
              $scope.docs.sort(Util.sortByDate);
            }
          });
  
        });
      });
    };
  
    var config = {
      ...
    };
  
    $http.get(gdocs.DOCLIST_FEED, config).success(successCallbackWithFsCaching);
  };
  

  Nota che nel callback webkitResolveLocalFileSystemURL() stiamo chiamando il numero $scope.$apply() quando viene visualizzata l'ultima voce. Di solito, non è necessario chiamare il numero $apply(). Angular rileva automaticamente le modifiche ai modelli dati. Tuttavia, nel nostro caso, abbiamo un ulteriore livello di callback asincrono di cui Angular non è a conoscenza. Dobbiamo informare esplicitamente Angular quando il nostro modello è stato aggiornato.

  Alla prima esecuzione, le icone non saranno presenti nel file system HTML5 e le chiamate a window.webkitResolveLocalFileSystemURL() causeranno il richiamo del callback di errore. In questo caso, possiamo riutilizzare la tecnica precedente e recuperare le immagini. Questa volta l'unica differenza è che ogni blob viene scritto nel file system (vedi writeFile()). La console verifica questo comportamento:

  

  Alla successiva esecuzione (o alla pressione del pulsante "Aggiorna"), l'URL trasmesso a webkitResolveLocalFileSystemURL() esiste perché il file è stato precedentemente memorizzato nella cache. L'app imposta doc.icon sul valore filesystem: URL del file ed evita di creare il costoso XHR per l'icona.

  Caricamento tramite trascinamento

  L'app che carica il video fa pubblicità ingannevole se non è in grado di caricare file.

  app.js gestisce questa funzionalità implementando una piccola libreria per il trascinamento HTML5 denominata DnDFileController. Consente di trascinare i file dal desktop per caricarli su Google Drive.

  La semplice aggiunta al servizio gdocs funziona come segue:

  gDriveApp.factory('gdocs', function() {
    var gdocs = new GDocs();
  
    var dnd = new DnDFileController('body', function(files) {
      var $scope = angular.element(this).scope();
      Util.toArray(files).forEach(function(file, i) {
        gdocs.upload(file, function() {
          $scope.fetchDocs();
        });
      });
    });
  
    return gdocs;
  });