Esta página faz parte da documentação da plataforma Apps do Chrome, que foi descontinuada em 2020. Ele continua disponível para clientes das edições Enterprise e Education no ChromeOS pelo menos até janeiro de 2025. Saiba mais sobre como migrar seu app.

Esta página foi traduzida pela API Cloud Translation.

Criar apps com o AngularJS

Este guia ajuda você a começar a criar apps do Chrome com a estrutura MVC AngularJS. Para ilustrar o Angular em ação, faremos referência a um aplicativo real criado usando a estrutura, o Aplicativo de upload do Google Drive. O código-fonte está disponível no GitHub.

Sobre o app

Aplicativo de upload do Google Drive

O Aplicativo de upload do Google Drive permite que os usuários visualizem e interajam rapidamente com arquivos armazenados em seus conta do Google Drive, bem como fazer o upload de novos arquivos usando as APIs HTML Arrastar e soltar. É um um ótimo exemplo de como criar um app que se comunica com uma das APIs do Google; Nesse caso, o Google a API Drive.

O aplicativo de envio usa OAuth2 para acessar os dados do usuário. A chrome.identity API processa a busca de um É o token OAuth do usuário conectado, então o trabalho é feito para nós! Assim que temos uma longa vida token de acesso, o aplicativo usa a API Google Drive para acessar os dados do usuário.

Principais recursos usados pelo app:

Detecção automática do AngularJS para CSP
Renderizar uma lista de arquivos buscados na API Google Drive
API HTML5 Filesystem para armazenar ícones de arquivos off-line
Arrastar e soltar HTML5 para importar/fazer upload de novos arquivos a partir da área de trabalho
XHR2 para carregar imagens, vários domínios
API chrome.identity para autorização OAuth
Frames sem cromo para definir a aparência da barra de navegação do app

Criar o manifesto

Todos os apps do Chrome exigem um arquivo manifest.json com as informações necessárias para a inicialização do Chrome o app. O manifesto contém metadados relevantes e lista todas as permissões especiais necessárias para o aplicativo correr.

Uma versão reduzida do manifesto do aplicativo de upload tem a seguinte aparência:

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

As partes mais importantes desse manifesto são os arquivos "oauth2" e "permissões" em outras seções.

A biblioteca "oauth2" define os parâmetros exigidos pelo OAuth2 para fazer sua mágica. Para criar um "client_id", siga as instruções em Conseguir seu ID de cliente. Os "escopos" Liste os escopos de autorização para os quais o token OAuth será válido (por exemplo, as APIs para as quais o aplicativo deseja acesso).

As "permissões" inclui URLs que o aplicativo acessará via XHR2. Os prefixos de URL são para que o Chrome saiba quais solicitações de vários domínios permitir.

Criar a página do evento

Todos os apps do Chrome exigem uma página/script em segundo plano para iniciar o app e responder a eventos do sistema.

No script background.js, o aplicativo de upload do Google Drive abre uma janela de 500 x 600 pixels na página principal. Ela também especifica uma altura e largura mínimas para a janela para que o conteúdo não fique muito refinado:

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

A janela é criada como uma janela chromeless (frame: 'none'). Por padrão, as janelas renderizam com a Barra padrão para fechar/expandir/minimizar o SO:

Aplicativo de upload do Google Drive sem frame

O usuário que fez o envio usa frame: 'none' para renderizar a janela como uma "folha em branco". e cria um fechamento personalizado em main.html:

Aplicativo de upload do Google Drive com frame personalizado

Toda a área de navegação está envolvida em um

(consulte a próxima seção). Para organizar um pouco o app, o botão "Fechar" personalizado fica oculto até que o usuário interaja com esta área:

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

No app.js, esse botão é vinculado a window.close().

Como projetar o aplicativo do modo Angular

Como o Angular é uma estrutura MVC, precisamos definir o app de modo que um modelo, uma visualização e um descascar logicamente. Felizmente, isso é trivial ao usar o Angular.

A visualização é a mais fácil, então vamos começar por ela.

Como criar a visualização

main.html é o "V"; em MVC; em que definimos modelos HTML para renderizar dados. No Angular, Os modelos são blocos simples de HTML com um molho especial.

Por fim, queremos exibir a lista de arquivos do usuário. Para isso, um simples

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

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

O texto é exatamente o que parece: estampar uma

para cada documento em nosso modelo de dados "docs". Cada item contém um ícone de arquivo, um link para abrir o arquivo na web e a data da última atualização.

Observação:para tornar o modelo HTML válido, estamos usando atributos data-* para o ngRepeat, mas não é obrigatório. Você pode facilmente escrever o repetidor como <li ng-repeat="doc in docs">.

Em seguida, precisamos informar ao Angular qual controlador supervisionará a renderização desse modelo. Para isso, usar a diretiva ngController para dizer ao DocsController para ter controle sobre o modelo; :
```
<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>
```
Lembre-se de que o que você não vê aqui é conectar listeners de eventos ou propriedades para dados vinculação. O Angular faz esse trabalho pesado para nós.

A última etapa é fazer o Angular iluminar nossos modelos. A maneira comum de fazer isso é incluir o diretiva ngApp até :
```
<html data-ng-app="gDriveApp">
```
Também é possível restringir o escopo do aplicativo a uma parte menor da página, se você quiser. Temos apenas um controlador neste app. Porém, se adicionássemos mais tarde, colocar o ngApp no topo deixa a página inteira pronta para o Angular.

O produto final de main.html vai ficar assim:
```
<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>
```
Informações sobre a Política de Segurança de Conteúdo

Ao contrário de muitas outras estruturas JS MVC, o Angular v1.1.0+ não exige ajustes para funcionar dentro de um sistema estrito CSP. Ele funciona desde o início!

No entanto, se você estiver usando uma versão mais antiga do Angular entre as versões 1.0.1 e 1.1.0, precisará informar Angular para ser executado no "modo de segurança de conteúdo". Para isso, inclua a diretiva ngCsp. com ngApp:
```
<html data-ng-app data-ng-csp>
```
Processamento da autorização

O modelo de dados não é gerado pelo próprio app. Em vez disso, ele é preenchido por uma API externa (a a API Google Drive). Portanto, é necessário um pouco de trabalho para preencher os dados do aplicativo.

Antes de fazer uma solicitação à API, precisamos buscar um token OAuth para a Conta do Google do usuário. Para isso, criamos um método para unir a chamada ao chrome.identity.getAuthToken() e armazenar o accessToken, que pode ser reutilizado para chamadas futuras à 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);
  }
};
```
Observação: a transmissão do retorno de chamada opcional nos dá a flexibilidade de saber quando o token OAuth é pronta.

Observação:para simplificar um pouco, criamos uma biblioteca gdocs.js para lidar com tarefas de API.

Depois de conseguir o token, é hora de fazer solicitações na API Drive e preencher o modelo.

Controle de esqueleto

O "modelo" para a ferramenta de upload é uma matriz simples (chamada docs) de objetos que serão renderizados

no modelo:

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

}

Observe que gdocs.auth() é chamado como parte do construtor DocsController. Quando o comportamento internos criam o controlador, temos o assegurado de um novo token OAuth esperando pelo usuário.

Buscando dados

Modelo apresentado. O controle é usado na estrutura. Token OAuth em mãos. E agora?

É hora de definir o método do controlador principal, fetchDocs(). É o trabalho do controlador, responsável por solicitar os arquivos do usuário e preencher a matriz docs com dados das respostas da 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);
};

O fetchDocs() usa o serviço $http do Angular para extrair o feed principal no XHR. O acesso ao OAuth é incluído no cabeçalho Authorization com outros cabeçalhos e parâmetros personalizados.

O successCallback processa a resposta da API e cria um novo objeto de documento para cada entrada na se alimentam.

Se você executar fetchDocs() agora, tudo vai funcionar, e a lista de arquivos vai aparecer:

Lista de arquivos buscada no app de upload do Google Drive

Eba!

Espera, estamos sentindo falta dos ícones de arquivos. What gives? Uma verificação rápida do console mostra de erros relacionados à CSP:

Erros de CSP no console do desenvolvedor

O motivo é que estamos tentando definir os ícones img.src para URLs externos. Isso viola a CSP. Por exemplo: https://ssl.gstatic.com/docs/doclist/images/icon_10_document_list.png. Para corrigir isso, nós precisa extrair esses ativos remotos localmente para o aplicativo.

Importação de recursos de imagem remota

Para que o CSP pare de gritar conosco, usamos XHR2 para "importar" os ícones do arquivo como Blobs, depois defina os img.src para um blob: URL criado pelo app.

Confira o successCallback atualizado com o código XHR adicionado:

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

Agora que o CSP está feliz com a gente de novo, temos bons ícones de arquivo:

Ferramenta de upload do Google Drive com ícones de arquivo

Ficar off-line: armazenamento em cache de recursos externos

A otimização óbvia que precisa ser feita: não fazer centenas de solicitações XHR para cada ícone de arquivo todas as chamadas para fetchDocs(). Verifique isso no console de Ferramentas para Desenvolvedores pressionando o botão "Atualizar" várias vezes. Sempre que n imagens são buscadas:

Vamos modificar o successCallback para adicionar uma camada de armazenamento em cache. As adições são destacadas em negrito:

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

No callback webkitResolveLocalFileSystemURL(), estamos chamando $scope.$apply() quando a última entrada é vista. Normalmente, chamar $apply() não é necessário. O Angular detecta mudanças nos dados modelos automaticamente. No entanto, no nosso caso, temos uma camada adicional de callback assíncrono que O Angular não está ciente. Precisamos informar explicitamente ao Angular quando o modelo for atualizado.

Na primeira execução, os ícones não estarão no sistema de arquivos HTML5 e as chamadas para window.webkitResolveLocalFileSystemURL() fará com que o callback de erro seja invocado. Para isso nesse caso, podemos reutilizar a técnica anterior e buscar as imagens. A única diferença desta vez é que cada blob é gravado no sistema de arquivos (consulte writeFile()). O console verifica isso comportamento:

Na próxima execução (ou ao pressionar o botão "Atualizar"), o URL transmitido para webkitResolveLocalFileSystemURL() existe porque o arquivo foi armazenado em cache anteriormente. O app define o doc.icon ao filesystem: URL do arquivo e evita criar o caro XHR para o ícone.

Envio de arrastar e soltar

Um app de upload é considerado uma publicidade falsa se não consegue fazer upload de arquivos.

O app.js lida com esse recurso implementando uma pequena biblioteca com recursos de arrastar e soltar HTML5 chamada DnDFileController Permite arrastar e fazer upload de arquivos da área de trabalho para o Google Drive.

Basta adicionar este código ao serviço 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;
});