Tworzenie aplikacji za pomocą AngularJS

Ważne: Chrome przestanie obsługiwać Aplikacje Chrome na wszystkich platformach. Przeglądarka Chrome i sklep Chrome Web Store będą nadal obsługiwać rozszerzenia. Przeczytaj ogłoszenie i dowiedz się więcej o migracji aplikacji.

Ten przewodnik ułatwia tworzenie aplikacji Chrome za pomocą platformy MVC AngularJS. Aby pokazać, jak działa Angular, użyjemy aplikacji stworzonej z wykorzystaniem tej platformy – narzędzia do przesyłania plików na Dysku Google. Kod źródłowy jest dostępny na GitHubie.

Informacje o aplikacji

Program do przesyłania plików na Dysku Google umożliwia użytkownikom szybkie przeglądanie plików przechowywanych na ich kontach Dysku Google i interakcję z nimi, a także przesyłanie nowych plików za pomocą interfejsów HTML przeciągania i upuszczania. Jest to świetny przykład tworzenia aplikacji, która komunikuje się z jednym z interfejsów API Google, w tym przypadku z interfejsem Google Drive API.

Uwaga: możesz też tworzyć aplikacje komunikujące się z interfejsami API lub usługami innych firm obsługującymi protokół OAuth2. Przeczytaj artykuł o uwierzytelnianiu za pomocą konta innego niż Google.

Program do przesyłania wykorzystuje protokół OAuth2 do uzyskiwania dostępu do danych użytkownika. Interfejs chrome.identity API obsługuje pobieranie tokena OAuth dla zalogowanego użytkownika, dzięki czemu ciężka praca wykonujemy za nas. Po uzyskaniu długoterminowego tokena dostępu aplikacje uzyskują dostęp do danych użytkownika za pomocą interfejsu Google Drive API.

Najważniejsze funkcje wykorzystywane przez tę aplikację:

• Automatyczne wykrywanie przez AngularJS dla CSP
• Renderuj listę plików pobranych przez interfejs Google Drive API.
• HTML5 Filesystem API do przechowywania ikon plików w trybie offline
• Przeciąganie i upuszczanie w formacie HTML5 – do importowania/przesyłania nowych plików z komputera.
• XHR2 do wczytywania obrazów, między domenami
• chrome.identity API do autoryzacji OAuth.
• Ramki Chromeless określające wygląd i styl paska nawigacyjnego aplikacji

Tworzę plik manifestu

Wszystkie aplikacje Chrome wymagają pliku manifest.json zawierającego informacje potrzebne Chrome do uruchomienia aplikacji. Plik manifestu zawiera odpowiednie metadane oraz zawiera listę specjalnych uprawnień, których potrzebuje aplikacja.

Skrócona wersja pliku manifestu narzędzia do przesyłania wygląda tak:

{
  "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/"
  ]
}

Najważniejsze części tego pliku manifestu to sekcje „oauth2” i „permissions”.

Sekcja „oauth2” definiuje parametry wymagane przez OAuth2 do działania. Aby utworzyć identyfikator klienta, wykonaj instrukcje podane w artykule Uzyskiwanie identyfikatora klienta. „Zakresy” zawierają listę zakresów autoryzacji, dla których token OAuth będzie prawidłowy (np. interfejsy API, do których aplikacja chce mieć dostęp).

Sekcja „uprawnienia” zawiera adresy URL, do których aplikacja uzyskuje dostęp przez XHR2. Prefiksy URL są wymagane, aby przeglądarka Chrome wiedziała, które żądania z wielu domen są dozwolone.

Tworzenie strony wydarzenia

Wszystkie aplikacje Chrome wymagają skryptu lub strony w tle do uruchamiania aplikacji i reagowania na zdarzenia systemowe.

W skrypcie background.js narzędzie do przesyłania plików otwiera okno o wymiarach 500 x 600 pikseli ze stroną główną. Określa też minimalną wysokość i szerokość okna, dzięki czemu treść nie staje się zbyt zwinięta:

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

Okno zostanie utworzone jako okno chromeless (ramka: „brak”). Domyślnie okna są renderowane za pomocą domyślnego paska zamykania/rozwijania/minimalizowania systemu operacyjnego:

Program do przesyłania używa frame: 'none', aby renderować okno jako „pustą planszę” i tworzyć niestandardowy przycisk zamykania w main.html:

Cały obszar nawigacyjny jest otoczony

(patrz następną sekcję). Aby nieco uporządkować aplikację, niestandardowy przycisk zamykania jest ukryty do czasu, gdy użytkownik wejdzie w interakcję z tym obszarem:

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

W pliku app.js ten przycisk jest połączony z window.close().

Projektowanie aplikacji w sposób angular

Angular to platforma MVC, dlatego musimy zdefiniować aplikację tak, aby model, widok i kontroler logicznie z niej wychodziły. Na szczęście podczas korzystania z Angular nie jest to banalne.

Widok jest najprostszy, więc zacznijmy od niego.

Tworzenie widoku

main.html to litera „V” w MVC; gdzie definiujemy szablony HTML służące do renderowania danych. W Angular szablony to proste bloki kodu HTML ze specjalnym sosem.

Chcemy w ten sposób wyświetlić listę plików użytkownika. W tym celu wystarczy

ma sens. Bity kątowe są pogrubione:

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

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

Wygląda to dokładnie tak: „wyróżnić”

• dla każdego dokumentu w „dokumentacji” naszego modelu danych. Każdy element zawiera ikonę pliku, link umożliwiający otwarcie pliku w internecie oraz datę ostatniej aktualizacji.
  Uwaga: aby zapewnić poprawność kodu HTML szablonu, używamy atrybutów data-* dla iteratora ngRepeat w Angular, ale nie jest to konieczne. Możesz łatwo zapisać powtarzający się jako <li ng-repeat="doc in docs">.

  Następnie musimy określić, który kontroler będzie nadzorować renderowanie tego szablonu. W tym celu używamy dyrektywy ngController, w której wskazujemy DocsController, że ma panować nad szablonem:

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

  Pamiętaj, że niczego tutaj nie widzisz, czyli podłączanie detektorów zdarzeń lub usług na potrzeby wiązania danych. Angular wykonuje za nas całą pracę.

  Ostatnim krokiem jest podświetlenie szablonów w Angular. Zazwyczaj jest to konieczne do umieszczenia dyrektywy ngApp do końca :

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

  Możesz też ograniczyć aplikację do mniejszej części strony. Mamy tylko 1 kontroler w tej aplikacji, ale jeślibyśmy chcieli dodać go później, umieszczenie elementu ngApp w najwyższym elemencie sprawia, że cała strona jest gotowa do użycia w Angular.

  Ostateczna wersja produktu main.html wygląda mniej więcej tak:

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

  Kilka słów na temat Content Security Policy

  W przeciwieństwie do wielu innych platform MVC JS, Angular w wersji 1.1.0 lub nowszej nie wymaga wprowadzania zmian w rygorystycznym CSP. To po prostu działa.

  Jeśli jednak używasz starszej wersji Angular pomiędzy wersjami 1.0.1 a 1.1.0, musisz włączyć Angular w „trybie bezpieczeństwa treści”. Można to zrobić, dodając dyrektywę ngCsp do właściwości ngApp:

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

  Obsługa autoryzacji

  Model danych nie jest generowany przez samą aplikację. Zamiast tego jest wypełniany przez zewnętrzny interfejs API (Google Drive API). Wzbogacenie danych aplikacji wymaga trochę pracy.

  Zanim będziemy mogli wysłać żądanie do interfejsu API, musimy pobrać token OAuth dla konta Google użytkownika. Na potrzeby tego utworzyliśmy metodę opakowania wywołania chrome.identity.getAuthToken() i przechowywania accessToken, której możemy używać w przyszłych wywołaniach interfejsu Drive API.

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

  Uwaga: przekazanie opcjonalnego wywołania zwrotnego daje nam elastyczność, dzięki której możemy dowiedzieć się, kiedy token OAuth jest gotowy.
  Uwaga: aby ułatwić to zadanie, stworzyliśmy bibliotekę gdocs.js do obsługi zadań związanych z interfejsami API.

  Po otrzymaniu tokena możemy wysłać żądania do interfejsu Drive API i wypełnić model.

  Kontroler szkieletowy

  „Model” narzędzia do przesyłania to prosta tablica (nazywana dokumentacją) obiektów, która zostanie wyrenderowana

• s w szablonie:

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

  Zwróć uwagę, że element gdocs.auth() jest wywoływany w ramach konstruktora DocsController. Gdy oprogramowanie wewnętrzne Angular tworzy kontroler, mamy pewność, że na użytkownika czeka nowy token OAuth.

  Pobieram dane

  Szablon został opracowany. Rusztowanie kontrolera. Token OAuth jest w ręku. Co dalej?

  Pora zdefiniować główną metodę kontrolera: fetchDocs(). To koń roboczy kontrolera odpowiedzialny za żądania plików użytkownika i zapisywanie danych w tablicy dokumentów danymi z odpowiedzi interfejsu 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() używa usługi $http Angular do pobierania głównego kanału przez XHR. Token dostępu OAuth jest zawarty w nagłówku Authorization wraz z innymi niestandardowymi nagłówkami i parametrami.

  successCallback przetwarza odpowiedź interfejsu API i tworzy nowy obiekt dokumentu dla każdego wpisu w pliku danych.

  Jeśli teraz uruchomisz fetchDocs(), wszystko działa, a pojawi się lista plików:

  

  Hurra!

  Czekaj, brakuje nam tych dobrze widocznych ikon plików. Dlaczego? Szybkie sprawdzenie konsoli pokazuje kilka błędów związanych z CSP:

  

  Próbujemy ustawić ikony img.src na zewnętrzne adresy URL. Narusza to CSP. Przykład: https://ssl.gstatic.com/docs/doclist/images/icon_10_document_list.png. Aby rozwiązać ten problem, musimy pobrać te zasoby zdalne lokalnie do aplikacji.

  Importuję komponenty z obrazem zdalnym

  Aby CSP przestał na nas krzyczeć, używamy XHR2 do „importowania” ikon plików jako obiektów blob, a następnie ustawiamy img.src na blob: URL utworzony przez aplikację.

  Oto zaktualizowany successCallback z dodanym kodem XHR:

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

  Gdy CSP znowu będzie z nami zadowolony, otrzymujemy ładne ikony plików:

  

  Przejście do trybu offline: zapisywanie zasobów zewnętrznych w pamięci podręcznej

  Oczywista optymalizacja, która należy wprowadzić: nie wysyłaj setek żądań XHR na każdą ikonę pliku przy każdym wywołaniu funkcji fetchDocs(). Sprawdź to w konsoli Narzędzi dla programistów, klikając kilka razy przycisk „Odśwież”. Za każdym razem zostanie pobranych n obrazów:

  

  Zmodyfikujmy successCallback, aby dodać warstwę pamięci podręcznej. Te elementy są wyróżnione pogrubieniem:

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

  Zwróć uwagę, że w wywołaniu zwrotnym webkitResolveLocalFileSystemURL(), gdy pojawia się ostatni wpis, wywołujemy $scope.$apply(). Normalnie dzwonienie pod numer $apply() nie jest konieczne. Angular automagicznie wykrywa zmiany w modelach danych. W naszym przypadku mamy jednak dodatkową warstwę asynchronicznego wywołania zwrotnego, o którym Angular nie wie. Musimy wyraźnie informować Angular o zaktualizowaniu naszego modelu.

  Przy pierwszym uruchomieniu ikony nie będą znajdować się w systemie plików HTML5, a wywołania funkcji window.webkitResolveLocalFileSystemURL() spowodują wywołanie wywołania zwrotnego błędu. W takim przypadku ponownie użyjemy metody z poprzedniej metody i pobierzemy zdjęcia. Jedyną różnicą w tym czasie jest to, że każdy obiekt blob jest zapisywany w systemie plików (patrz writeFile()). Konsola weryfikuje to działanie:

  

  Po następnym uruchomieniu (lub naciśnięciu przycisku „Odśwież”) adres URL przekazany do webkitResolveLocalFileSystemURL() istnieje, ponieważ plik został wcześniej zapisany w pamięci podręcznej. Aplikacja ustawia w elemencie doc.icon wartość filesystem: URL pliku i unika kosztownego XHR za ikonę.

  Przeciągnij i upuść przesyłanie

  Aplikacja do przesyłania, która nie może przesyłać plików, to fałszywa reklama.

  Plik app.js obsługuje tę funkcję, implementując małą bibliotekę przeciągania i upuszczania w HTML5 o nazwie DnDFileController. Umożliwia przeciąganie plików z pulpitu i przesyłanie ich na Dysk Google.

  Wystarczy dodać ten element do usługi gdocs:

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