Skip to content

AngularJS Folha de referência

Framework web front-end baseado em JavaScript (Angular 1.x).

01

Primeiros passos

Configuração e Bootstrap

O AngularJS (1.x) é incluído via tag script. O ng-app inicializa a aplicação e o ng-controller conecta um controller a uma subárvore do DOM. As chaves duplas {{ }} são expressões Angular que renderizam os dados do model.

angularjs
<!-- include AngularJS 1.8.x -->
<script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.8.2/angular.min.js"></script>

<body ng-app="myApp">
  <div ng-controller="MainCtrl">
    {{ message }}
  </div>
</body>

<script>
  var app = angular.module('myApp', []);
  app.controller('MainCtrl', function($scope) {
    $scope.message = 'Hello AngularJS!';
  });
</script>

ng-app e Auto-Bootstrap

O ng-app com um nome de módulo inicializa o AngularJS automaticamente no DOMContentLoaded. O ng-strict-di exige anotações explícitas de dependências, pegando bugs de minificação cedo no desenvolvimento. Apenas um ng-app é auto-inicializado por página.

angularjs
<!-- ng-app on <html> makes the whole page an Angular app -->
<html ng-app="myApp" ng-strict-di>
  <head><title>App</title></head>
  <body>
    <div>{{ 1 + 2 }}</div>
  </body>
</html>

<!-- ng-strict-di enforces dependency injection annotations -->
<!-- (errors if a service uses implicit DI without annotation) -->

Bootstrap manual

Use angular.bootstrap() quando precisar adiar o início (por exemplo, esperando o carregamento assíncrono de módulos ou uma config buscada). Assim você pode inicializar vários apps Angular na mesma página, cada um em seu próprio elemento raiz.

angularjs
<!-- HTML has NO ng-app attribute -->
<div id="appRoot">
  {{ message }}
</div>

<script>
  angular.element(document).ready(function() {
    angular.bootstrap(document.getElementById('appRoot'), ['myApp']);
  });
</script>

Primeira vinculação de dados

Com ng-app sem nome de módulo, o Angular roda em modo 'auto' com o módulo ng padrão. O ng-model vincula o input a uma propriedade chamada 'name' no scope implícito, e {{ }} a renderiza ao vivo. É o data binding bidirecional na sua forma mais simples.

angularjs
<div ng-app>
  <label>Your name:
    <input type="text" ng-model="name">
  </label>
  <p>Hello {{ name || 'stranger' }}!</p>
</div>

Básico de módulos e controllers

angular.module('name', [deps]) cria um módulo; angular.module('name') recupera um existente. A anotação inline de array ['$scope', function($scope){}] mantém o controller seguro contra minificação. Sempre passe as dependências explicitamente ao criar o módulo.

angularjs
var app = angular.module('myApp', []); // create module
//          ^name   ^dependencies

app.controller('GreetCtrl', ['$scope', function($scope) {
  $scope.user = { name: 'Ada' };
  $scope.greet = function() {
    return 'Hi ' + $scope.user.name;
  };
}]);
02

Módulos

Criar vs recuperar um módulo

A forma com dois argumentos angular.module(name, deps) cria um novo módulo. A forma com um argumento angular.module(name) recupera um módulo definido antes. Passar [] acidentalmente duas vezes apaga silenciosamente os registros do módulo.

angularjs
// CREATE a module (second arg = dependency array)
var app = angular.module('myApp', []);

// RETRIEVE an existing module (NO second arg)
// var app = angular.module('myApp');

// common mistake: passing [] again overwrites the module

Dependências do módulo

O array de dependências lista os módulos cujos providers serão injetados neste. Módulos embutidos como ngRoute são opcionais e precisam ser listados explicitamente (e seus scripts carregados). Submódulos permitem dividir um app grande em partes reutilizáveis.

angularjs
var app = angular.module('myApp', [
  'ngRoute',          // built-in routing
  'ngAnimate',        // animation hooks
  'ui.router',        // 3rd-party router
  'myApp.common',     // your own sub-module
]);

Bloco config

config() roda durante o registro dos providers, antes de qualquer instância de serviço ser criada. É o único lugar onde você pode injetar e configurar Providers (por exemplo, $routeProvider, $locationProvider). Use-o para configurar rotas, habilitar o modo HTML5 ou registrar validadores personalizados.

angularjs
app.config(['$routeProvider', function($routeProvider) {
  $routeProvider
    .when('/home', { templateUrl: 'home.html' })
    .when('/about', { templateUrl: 'about.html' })
    .otherwise({ redirectTo: '/home' });
}]);

Bloco run

run() executa depois que o injector é criado e os providers estão configurados — é o 'main' do app. Injete instâncias (não providers). É comum usá-lo para registrar listeners globais de $rootScope para mudanças de rota ou checagens de autenticação.

angularjs
app.run(['$rootScope', 'AuthService', function($rootScope, AuthService) {
  $rootScope.$on('$routeChangeStart', function(event, next) {
    if (!AuthService.isAuthenticated()) {
      event.preventDefault();
    }
  });
}]);

Constants e Values

constant() registra um valor que também pode ser injetado em blocos config() — ideal para configuração que os providers precisam. value() só pode ser injetado em construções da fase de run (services, controllers). Use constant para config que precisa estar disponível cedo.

angularjs
// constant: available in BOTH config and run phases
app.constant('API_BASE', 'https://api.example.com');

// value: available only in run phase (injectable as instance)
app.value('defaultPageSize', 20);

// usage in a service:
app.factory('UserSvc', ['API_BASE', function(API_BASE) {
  return { all: function() { /* use API_BASE */ } };
}]);
03

Controllers

Controller básico

Controllers definem o estado inicial do $scope e adicionam comportamento (funções). Mantenha os controllers enxutos — a lógica de negócio pertence aos services. O construtor do controller roda toda vez que uma nova instância é necessária (por exemplo, a cada uso de ng-controller).

angularjs
app.controller('TodoCtrl', ['$scope', function($scope) {
  $scope.todos = [
    { text: 'Learn AngularJS', done: true },
    { text: 'Build an app', done: false }
  ];

  $scope.addTodo = function() {
    $scope.todos.push({ text: $scope.todoText, done: false });
    $scope.todoText = '';
  };

  $scope.remaining = function() {
    return $scope.todos.filter(function(t) { return !t.done; }).length;
  };
}]);

Sintaxe controllerAs

controllerAs publica a instância do controller no scope sob um alias (main). Use this em vez de $scope para propriedades e funções. Isso evita as armadilhas de herança do $scope e deixa explícito de qual controller vem cada propriedade em views aninhadas.

angularjs
<div ng-controller="MainCtrl as main">
  <p>{{ main.title }}</p>
  <button ng-click="main.save()">Save</button>
</div>

<script>
app.controller('MainCtrl', function() {
  this.title = 'Controller As';
  this.save = function() { /* ... */ };
});
</script>

DI segura contra minificação

Minificadores renomeiam os parâmetros das funções, quebrando a inferência de dependências do Angular por nome. A anotação inline de array lista os nomes dos services como strings antes da função, então os nomes sobrevivem à minificação. Sempre use essa anotação ou ng-annotate / $inject.

angularjs
// SAFE: inline array annotation (parameter names are string literals)
app.controller('SafeCtrl', ['$scope', '$http', function($scope, $http) {
  $http.get('/api/items').then(function(res) { $scope.items = res.data; });
}]);

// UNSAFE: implicit DI breaks when minified
app.controller('UnsafeCtrl', function($scope, $http) { /* ... */ });

Anotação por propriedade $inject

Uma alternativa ao array inline: anexe um array $inject com os nomes dos services à função construtora. Isso mantém a declaração da função legível e reutilizável. Os dois estilos são equivalentes — escolha um e seja consistente (ou automatize com ng-annotate).

angularjs
function UserCtrl($scope, UserService) {
  UserService.list().then(function(users) {
    $scope.users = users;
  });
}
// explicit dependency list on the function
UserCtrl.$inject = ['$scope', 'UserService'];

app.controller('UserCtrl', UserCtrl);

Controllers aninhados e herança

Scopes filhos herdam por protótipo dos scopes pais, então um controller filho lê propriedades do pai. Porém, atribuir um primitivo no filho cria uma nova propriedade local que sombreia a do pai em vez de atualizá-la — uma pegadinha comum. Prefira objetos (notação de ponto) ou controllerAs para evitar isso.

angularjs
<div ng-controller="ParentCtrl">
  <p>{{ shared }}</p>      <!-- sees parent's 'shared' -->
  <div ng-controller="ChildCtrl">
    <p>{{ shared }}</p>    <!-- inherits, can shadow -->
    <p>{{ childOnly }}</p>
  </div>
</div>

app.controller('ParentCtrl', ['$scope', function($scope) {
  $scope.shared = 'from parent';
}]);
app.controller('ChildCtrl', ['$scope', function($scope) {
  $scope.childOnly = 'child only';
  $scope.shared = 'overridden by child'; // shadows parent
}]);

Limpeza do controller ($destroy)

Escute o evento $destroy no $scope para rodar a limpeza quando o scope do controller for destruído (por exemplo, ao navegar para outra página). Cancele timers de $interval/$timeout, desfaça listeners de window e libere referências para evitar vazamentos de memória. O Angular limpa automaticamente os watchers dos próprios scopes.

angularjs
app.controller('TimerCtrl', ['$scope', '$interval', function($scope, $interval) {
  var timer = $interval(function() { $scope.now = Date.now(); }, 1000);

  $scope.$on('$destroy', function() {
    $interval.cancel(timer); // free the resource
  });
}]);
04

$scope

Básico do $scope

O $scope é a cola entre um controller e a view — guarda o model e o comportamento aos quais o template se vincula. O Angular cria um novo scope para cada controller; as expressões do template são avaliadas nesse scope (e nos seus pais).

angularjs
app.controller('MsgCtrl', ['$scope', function($scope) {
  $scope.message = 'Hi';          // model on scope
  $scope.count = 0;
  $scope.inc = function() {
    $scope.count++;
  };
}]);

// In HTML: {{ message }}, {{ count }}, ng-click="inc()"

Herança de scope (prototipal)

Scopes filhos herdam do scope pai pela cadeia de protótipos do JavaScript. Ler uma propriedade do pai funciona, mas atribuir um primitivo (por exemplo, $scope.name = 'x') no filho cria uma cópia local que sombreia o pai. Vincule a objetos (user.name) para que as escritas propaguem pela cadeia.

angularjs
<!-- primitive on parent: child writes a NEW copy -->
<div ng-controller="ParentCtrl">
  <div ng-controller="ChildCtrl">
    <input ng-model="name"> <!-- shadows parent.name -->
  </div>
</div>

<!-- object avoids the shadowing gotcha -->
app.controller('ParentCtrl', ['$scope', function($scope) {
  $scope.user = { name: 'Ada' }; // child edits user.name -> updates parent
}]);

$rootScope

O $rootScope é o topo da hierarquia de scopes; os outros descem dele. Propriedades colocadas aqui ficam visíveis nos templates. Use com parcimônia para valores realmente globais (nome do app, flag de sessão) — o excesso cria acoplamento oculto e dificulta rastrear o estado.

angularjs
app.run(['$rootScope', function($rootScope) {
  $rootScope.appName = 'MyApp';     // available everywhere
  $rootScope.version = '1.0';
}]);

<!-- any template -->
<footer>© {{ appName }} {{ version }}</footer>

Eventos de scope: $emit / $broadcast / $on

$emit dispara um evento que sobe até o $rootScope; $broadcast desce até os scopes filhos. $on registra um listener e retorna uma função de cancelamento. Passe dados pelo segundo argumento. Desfaça os listeners no $destroy para evitar vazamentos.

angularjs
// travel UP toward $rootScope
$scope.$emit('userLoggedOut', { userId: 7 });

// travel DOWN to all descendant scopes
$scope.$broadcast('itemAdded', { id: 99 });

// listen for an event
var unbind = $scope.$on('itemAdded', function(event, args) {
  console.log('item', args.id);
});
// stop listening when scope is destroyed
$scope.$on('$destroy', unbind);

$new, $id, $parent

$new(isolated, parent) cria um scope filho (ou isolado); $id é um id numérico único; $parent referencia o scope pai. São usados principalmente dentro de directives. Sempre chame $destroy() em scopes criados manualmente para remover watchers e evitar vazamentos de memória.

angularjs
var child = $scope.$new();        // create a child scope
child.extra = 'child data';
console.log(child.$id);          // unique scope id
console.log(child.$parent === $scope); // true
// ...
child.$destroy();                // remove from hierarchy

Isolate scope (prévia de directive)

Definir scope: {} numa directive cria um isolate scope que NÃO herda por protótipo do pai — essencial para componentes reutilizáveis. O pai se comunica apenas pelas bindings declaradas (@, =, &). Isso evita que componentes leiam ou poluam acidentalmente o scope ao redor.

angularjs
app.directive('userCard', function() {
  return {
    scope: {              // ISOLATE scope: does NOT inherit parent
      user: '=',          // two-way binding
      onKick: '&'         // expression binding
    },
    template: '<p>{{ user.name }}</p>'
  };
});

<!-- usage -->
<user-card user="currentUser" on-kick="removeUser()"></user-card>
05

Expressões

Expressões básicas

Expressões Angular se parecem com JavaScript, mas são avaliadas contra o $scope (não o window). Suportam aritmética, concatenação de strings, acesso a membros e ternários. Diferente do JS, undefined/null são exibidos como string vazia (sem o texto 'undefined'). O operador de optional chaining NÃO é suportado.

angularjs
<p>{{ 1 + 2 }}</p>                <!-- 3 -->
<p>{{ 'Hello, ' + name }}</p>
<p>{{ user.name }}</p>
<p>{{ items.length }} items</p>
<p>{{ obj?.nested }}</p>           <!-- AngularJS does NOT support ?. -->

Expressão vs JavaScript

Expressões são mais limitadas que JS: sem statements (if/for/while), sem new/throw, sem vírgulas, sem definição de funções, sem bitwise em algumas versões. São avaliadas com o $scope como contexto e engolem erros silenciosamente (registrados no $exceptionHandler). Isso mantém o template seguro e declarativo.

angularjs
<!-- ALLOWED in expressions -->
{{ a + b }}
{{ cond ? 'yes' : 'no' }}
{{ user.getName() }}
{{ [1,2,3].length }}

<!-- NOT allowed: control flow, new, throw, comma operator -->
{{ if (x) { ... } }}     <!-- SyntaxError -->
{{ throw new Error() }}  <!-- not allowed -->

Binding única (::)

O prefixo :: cria uma binding única: o Angular avalia a expressão e, uma vez definida (não-undefined), remove o watcher. Isso reduz drasticamente o número de watchers no ciclo de digest, melhorando o desempenho de dados que não mudam após o carregamento inicial.

angularjs
<!-- AngularJS 1.3+ -->
<p>{{ ::user.name }}</p>           <!-- evaluated once, then unwatched -->
<li ng-repeat="item in ::items">{{ ::item.label }}</li>

<!-- good for static data that never changes -->
<h1>{{ ::conferenceTitle }}</h1>

$eval e $parse

$scope.$eval(expr) analisa e executa uma expressão em string contra o scope. $parse compila uma expressão uma vez em uma função getter/setter reutilizável — bem mais eficiente que reavaliar a string repetidamente. Use $parse em directives/services que consomem bindings de expressão.

angularjs
// evaluate an expression against $scope
var result = $scope.$eval('1 + 2 * count');   // 1 + 2*count
// $scope.$eval(expr, locals)

// compile once, reuse: more efficient for repeated eval
var getter = $parse('user.name');
var name = getter($scope);
getter.assign($scope, 'Ada'); // two-way: sets user.name

Filters em expressões

O pipe | aplica um filter à expressão; vários filters encadeiam da esquerda para a direita. Argumentos são passados com dois-pontos. Filters são convenientes, mas reexecutam a cada digest — para listas grandes, filtre no controller via $filter ou uma propriedade computada para melhor desempenho.

angularjs
<p>{{ price | currency }}</p>             <!-- $1.99 -->
<p>{{ today | date:'yyyy-MM-dd' }}</p>    <!-- 2025-01-01 -->
<p>{{ name | uppercase }}</p>
<p>{{ items | filter:query | orderBy:'name' }}</p>

<!-- chained with |, arguments after : -->

ng-bind e ng-cloak

Antes de o Angular inicializar, o navegador mostra o texto bruto {{ }} ('flash de conteúdo não compilado'). O ng-bind escreve o valor no texto do elemento só depois que o Angular roda, evitando o flash. O ng-cloak combinado com uma regra CSS esconde os elementos até que o Angular os compile.

angularjs
<!-- raw {{ }} may flash before Angular compiles -->
<p>{{ message }}</p>

<!-- ng-bind avoids the flash -->
<p ng-bind="message"></p>

<!-- ng-cloak hides elements until compiled -->
<style>[ng-cloak] { display: none; }</style>
<p ng-cloak>{{ message }}</p>
06

Directives embutidas

ng-model (binding bidirecional)

O ng-model vincula inputs de formulário a uma propriedade do scope com sincronização bidirecional: mudanças no input atualizam o model, e mudanças no model atualizam o input. Funciona em input, textarea, select e checkbox/radio. Sempre vincule a uma propriedade com ponto (user.name) para evitar problemas de sombreamento de primitivos.

angularjs
<input type="text" ng-model="user.name">
<p>Hello, {{ user.name }}</p>

<!-- checkbox binds to boolean -->
<input type="checkbox" ng-model="agree"> I agree

<!-- select binds the chosen option's value -->
<select ng-model="color">
  <option value="r">Red</option>
  <option value="g">Green</option>
</select>

ng-repeat

O ng-repeat clona o elemento para cada item de uma coleção. $index, $first, $last, $middle, $even, $odd ficam disponíveis. Sempre use track by para dar ao Angular uma identidade estável e reutilizar nós do DOM quando o array muda — isso evita re-renderizar tudo e corrige erros de chave duplicada.

angularjs
<ul>
  <li ng-repeat="item in items track by item.id">
    {{ $index }}: {{ item.name }}
    <span ng-if="$first">(first)</span>
    <span ng-if="$last">(last)</span>
  </li>
</ul>

<!-- ng-repeat over object -->
<li ng-repeat="(key, value) in config">{{ key }} = {{ value }}</li>

ng-if / ng-show / ng-hide

O ng-if insere/remove o elemento (e seus scopes filhos) do DOM condicionalmente — caro de alternar, mas barato quando oculto. ng-show/ng-hide apenas alternam uma classe CSS, mantendo o elemento no DOM — barato de alternar, mas o elemento é sempre compilado. Prefira ng-if para conteúdo raramente exibido.

angularjs
<!-- ng-if: removes/adds element from DOM -->
<div ng-if="user.isAdmin">Admin tools</div>

<!-- ng-show/ng-hide: toggles display:none only -->
<div ng-show="isLoading">Loading...</div>
<div ng-hide="isLoggedIn">Please log in</div>

ng-class e ng-style

ng-class aceita um objeto (chaves truthy viram classes), um array de nomes de classes ou uma string. ng-style recebe um objeto que mapeia nomes de propriedades CSS para valores. Ambos reavaliam a cada digest, então para estilos estáticos prefira um atributo class comum — use-os para estilos orientados a estado.

angularjs
<!-- object form: keys are classes, truthy values apply them -->
<div ng-class="{ active: tab === 1, disabled: !enabled }"></div>

<!-- array form -->
<div ng-class="[styleA, styleB]"></div>

<!-- ng-style: object of CSS properties -->
<div ng-style="{ color: theme.color, 'font-size': theme.size + 'px' }">
  Styled text
</div>

ng-bind-template e ng-init

O ng-bind-template vincula várias expressões ao texto de um elemento sem {{ }} bruto. O ng-init avalia uma expressão uma vez na inicialização do elemento — útil para demos, mas desencorajado em apps reais por colocar lógica na marcação. Defina o estado inicial no controller.

angularjs
<!-- bind multiple expressions to text -->
<p ng-bind-template="Hello {{ first }} {{ last }}"></p>

<!-- ng-init: set a local (use sparingly, prefer controller) -->
<div ng-init="qty = 1; cost = 5">
  Total: {{ qty * cost }}
</div>

ng-src / ng-href / ng-disabled

Use ng-src e ng-href em vez de src='{{ }}' para que o navegador não faça uma requisição à URL literal '{{ }}' antes de o Angular interpolar. O ng-disabled alterna o atributo disabled com base numa expressão — perfeito para desabilitar botões de submit enquanto o formulário é inválido ou uma requisição está em andamento.

angularjs
<!-- avoid broken requests before binding resolves -->
<img ng-src="{{ user.avatarUrl }}" alt="avatar">
<a ng-href="{{ profileUrl }}">Profile</a>

<button ng-disabled="form.$invalid || saving">
  {{ saving ? 'Saving...' : 'Save' }}
</button>
07

Directives personalizadas

Directive básica

Uma directive estende o HTML. restrict: 'E' a torna um elemento personalizado (<greeting>); 'A' um atributo. As directives mais simples apenas retornam um template. Use restrict Element/Attribute por padrão; Class/Comment são raros. A prática moderna favorece components para directives baseadas em template.

angularjs
app.directive('greeting', function() {
  return {
    restrict: 'E',              // E=element, A=attr, C=class, M=comment
    template: '<h1>Hello there!</h1>'
  };
});

<!-- usage -->
<greeting></greeting>
<!-- or as attribute: <div greeting></div> -->

Directive Definition Object (DDO)

O Directive Definition Object configura tudo: restrict, scope (isolado ou não), template/templateUrl, transclude, controller e a função link. templateUrl carrega o template via $http (com cache); template é inline. Mantenha a manipulação do DOM no link e a lógica do view-model no controller.

angularjs
app.directive('card', function() {
  return {
    restrict: 'E',
    scope: {},                  // isolate scope
    templateUrl: 'card.html',
    transclude: true,
    controller: function() { /* ... */ },
    controllerAs: 'vm',
    bindToController: {},
    link: function(scope, el, attrs) { /* DOM work */ }
  };
});

Bindings de isolate scope (@ = &)

@ lê o atributo como string (unidirecional, pai->filho, interpolada). = cria uma binding bidirecional com a expressão do pai. & expõe uma função que executa uma expressão no scope do pai — usada para callbacks de eventos. Essas três bindings são o coração de componentes de directive reutilizáveis.

angularjs
app.directive('profile', function() {
  return {
    restrict: 'E',
    scope: {
      name: '@',          // read attribute as STRING (one-way)
      user: '=',          // two-way binding to expression
      onSave: '&'         // callback: evaluate expression in parent scope
    },
    template: '<p>{{ name }} / {{ user.email }}</p>'
  };
});

<profile name="{{ n }}" user="currentUser" on-save="save()"></profile>

Função link

A função link roda depois que o elemento da directive é compilado. Use-a para manipulação direta do DOM, listeners de eventos (via .on do jQuery Lite) e observação de atributos interpolados com attrs.$observe. scope é o scope da directive, element é o nó do DOM embrulhado em jqLite, attrs são os atributos normalizados.

angularjs
app.directive('highlight', function() {
  return {
    restrict: 'A',
    link: function(scope, element, attrs) {
      element.on('mouseenter', function() {
        element.css('background', 'yellow');
      });
      element.on('mouseleave', function() {
        element.css('background', '');
      });
      attrs.$observe('highlight', function(val) {
        // react to attribute interpolation changes
      });
    }
  };
});

Função compile

A função compile roda uma vez sobre o elemento original do template antes de o Angular cloná-lo para ng-repeat etc. Use-a para transformações no nível do template que não precisam do scope. Ela retorna uma função link (ou um objeto pre/post link). A maioria das directives não precisa de compile — prefira link para trabalho por instância.

angularjs
app.directive('repeatN', function() {
  return {
    restrict: 'E',
    compile: function(tElement, tAttrs) {
      // runs ONCE on the TEMPLATE element, before cloning
      var n = parseInt(tAttrs.count, 10);
      for (var i = 1; i < n; i++) {
        tElement.after(tElement.clone());
      }
      // optionally return a (post) link function
      return function link(scope, el, attrs) {
        el.addClass('repeated');
      };
    }
  };
});

Transclusion

transclude: true captura o conteúdo original do elemento e o insere no template onde ng-transclude aparece. O conteúdo transcluído mantém seu scope original (o pai), não o isolate scope da directive. Isso permite que uma directive wrapper (panel, modal, card) envolva conteúdo arbitrário fornecido pelo chamador.

angularjs
app.directive('panel', function() {
  return {
    restrict: 'E',
    transclude: true,
    template: '<div class="panel"><div class="panel-body" ng-transclude></div></div>'
  };
});

<!-- the inner content lands inside ng-transclude -->
<panel>
  <h3>Title</h3>
  <p>Body content goes here.</p>
</panel>
08

Filters

Filters embutidos

O Angular traz number, currency, date, lowercase, uppercase, json, limitTo, orderBy e filter. O argumento depois dos dois-pontos configura o filter. currency aceita um símbolo ISO ou caractere personalizado. Filters reexecutam a cada digest, então faça cache de cálculos pesados ou calcule no controller.

angularjs
<p>{{ 1234.5 | number:2 }}</p>          <!-- 1,234.50 -->
<p>{{ 9.99 | currency:'USD' }}</p>     <!-- $9.99 -->
<p>{{ 128 | currency:'&euro;' }}</p>   <!-- €128.00 -->
<p>{{ 'hi' | uppercase }}</p>          <!-- HI -->
<p>{{ 'HI' | lowercase }}</p>          <!-- hi -->
<p>{{ 'a b c' | limitTo:2 }}</p>       <!-- a  -->

Filter date

O filter date formata um objeto Date, string ISO 8601 ou milissegundos epoch. Formatos predefinidos incluem 'short','medium','long','full','shortDate','mediumDate','shortTime'. Formatos personalizados usam tokens: y (ano), M (mês), d (dia), H (hora), m (minuto), s (segundo), EEEE (dia da semana completo).

angularjs
<p>{{ now | date }}</p>                       <!-- Jan 1, 2025 -->
<p>{{ now | date:'yyyy-MM-dd' }}</p>        <!-- 2025-01-01 -->
<p>{{ now | date:'shortTime' }}</p>         <!-- 3:45 PM -->
<p>{{ now | date:'EEEE, MMMM d, y' }}</p>   <!-- Wednesday, January 1, 2025 -->

<!-- accepts a Date, ISO string, or millis timestamp -->

Filter filter (busca em array)

O filter filter seleciona itens do array que correspondem a uma string, objeto ou função predicado. Um objeto casa com itens cujos campos especificados contêm os valores dados. O terceiro argumento true opcional força correspondência exata. Para arrays grandes, filtre no controller para evitar reexecutar a cada digest.

angularjs
<!-- match any field containing the query string -->
<li ng-repeat="u in users | filter:query">{{ u.name }}</li>

<!-- match a specific field with an object -->
<li ng-repeat="u in users | filter:{ role: 'admin' }">{{ u.name }}</li>

<!-- strict equality on a field -->
<li ng-repeat="u in users | filter:{ id: 5 }:true">{{ u.name }}</li>

Filter orderBy

orderBy ordena um array por um nome de campo (prefixo '-' para decrescente), um array desses campos ou uma função comparadora. Ele cria um novo array ordenado a cada digest — para listas grandes, ordene uma vez no controller e reutilize. Combinado com filter, alimenta UIs de busca+ordenação.

angularjs
<!-- ascending by 'name' -->
<li ng-repeat="u in users | orderBy:'name'">{{ u.name }}</li>

<!-- descending -->
<li ng-repeat="u in users | orderBy:'-name'">{{ u.name }}</li>

<!-- multiple fields -->
<li ng-repeat="u in users | orderBy:['role','-age']">{{ u.name }}</li>

<!-- by a function -->
<li ng-repeat="u in users | orderBy:scoreFn">{{ u.name }}</li>

Filter personalizado

Registre uma factory de filter com app.filter. A factory retorna uma função que transforma a entrada (o valor antes do pipe) mais quaisquer argumentos extras. Filters devem ser puros e sem efeitos colaterais. São injetáveis, então você pode depender de outros services dentro da factory.

angularjs
app.filter('capitalize', function() {
  return function(input) {
    if (!input) return '';
    input = String(input);
    return input.charAt(0).toUpperCase() + input.slice(1).toLowerCase();
  };
});

<!-- usage -->
<p>{{ 'hELLo' | capitalize }}</p>   <!-- Hello -->

Service $filter nos controllers

Injete $filter para aplicar um filter dentro do JS (controllers, services). Chame $filter('name')(value, arg1, arg2). Isso evita reexecutar o filter a cada digest e permite reutilizar o resultado. Útil quando você precisa do valor filtrado na lógica, não só na view.

angularjs
app.controller('ListCtrl', ['$scope', '$filter', function($scope, $filter) {
  $scope.users = [/* ... */];

  // run the orderBy filter programmatically
  $scope.sorted = $filter('orderBy')($scope.users, 'name');

  // currency filter to format a number
  $scope.priceText = $filter('currency')(99.5, '$');
}]);
09

Services ($http, $location, ...)

Básico do $http

O $http faz requisições XHR e retorna uma Promise. O valor resolvido é um objeto de resposta com data, status, headers e config. .then trata sucesso, .catch erros. Desde o Angular 1.6, os callbacks .success/.error foram removidos — use promise .then/.catch de forma consistente.

angularjs
app.controller('ApiCtrl', ['$scope', '$http', function($scope, $http) {
  $http.get('/api/users')
    .then(function(response) {
      $scope.users = response.data;       // response: {data, status, headers, config}
    })
    .catch(function(error) {
      console.error('failed', error.status);
    });
}]);

$http POST/PUT com config

Existem funções de conveniência para get/post/put/delete/patch/jsonp/head. Para controle total, passe um objeto de config: params viram query string, headers define os cabeçalhos da requisição, responseType controla como o body é interpretado. O $http aplica as transforms padrão (parse de JSON) automaticamente.

angularjs
$http.post('/api/users', { name: 'Ada' })
  .then(function(res) { console.log('created', res.data); });

// with headers / query params / response type
$http({
  method: 'GET',
  url: '/api/report',
  params: { format: 'pdf' },
  headers: { 'X-Auth': token },
  responseType: 'arraybuffer'
}).then(function(res) { /* res.data is binary */ });

Service $location

O $location é um wrapper sobre window.location que se mantém em sincronia com a URL do navegador e o ciclo de digest. Use-o para ler ou alterar path, parâmetros de busca e hash. Para habilitar URLs amigáveis em HTML5, configure $locationProvider.html5Mode(true) e adicione uma tag <base>.

angularjs
// read the URL
$location.path();          // '/users/42'
$location.search();        // { tab: 'edit' }
$location.hash();          // 'top'
$location.absUrl();        // full URL

// change without full reload
$location.path('/dashboard');
$location.search('q', 'angular');   // ?q=angular
$location.hash('section-2');

$timeout e $interval

$timeout e $interval são wrappers conscientes do digest em torno de setTimeout/setInterval — eles disparam $apply para que as atualizações do scope sejam percebidas. Sempre cancele-os no $destroy para evitar vazamentos e erros de 'digest em scope destruído'. Passe false como 3º argumento para pular o digest se não precisar dele.

angularjs
// $timeout: like setTimeout but triggers a $digest
var promise = $timeout(function() {
  $scope.status = 'ready';
}, 1000);

// cancel
$timeout.cancel(promise);

// $interval: like setInterval, also digest-aware
var ticker = $interval(function() { $scope.now = Date.now(); }, 5000);
$scope.$on('$destroy', function() { $interval.cancel(ticker); });

$log e $window / $document

O $log é um wrapper leve sobre console que suporta log/info/warn/error/debug e pode ser decorado para logging em produção. $window e $document embrulham os globais — sempre injete-os em vez de chamar window/document diretamente, para que testes possam mocká-los e seu código fique independente do ambiente.

angularjs
app.controller('LogCtrl', ['$log', '$window', function($log, $window) {
  $log.log('plain');
  $log.info('info');
  $log.warn('warning');
  $log.error('error');

  $window.alert('Hi');      // safer than bare alert()
  $window.innerWidth;
}]);

// $document wraps document; $window wraps window.
// Injecting them (instead of using globals) makes testing easy.

$rootScope.broadcast e eventos globais

Use $rootScope.$broadcast para eventos do app inteiro (login/logout, mudança de tema). Listeners em qualquer scope o recebem. Para eventos que só devem ser ouvidos por listeners do $rootScope, $rootScope.$emit é mais barato (não desce na hierarquia). Evite abusar de eventos globais — prefira services com APIs explícitas para a maioria das comunicações.

angularjs
// anywhere: broadcast a global event
$rootScope.$broadcast('auth:logout');

// in a controller: listen
$scope.$on('auth:logout', function() {
  $scope.currentUser = null;
});

// $emit on $rootScope = effectively global too
$rootScope.$emit('something', data); // only $rootScope.$on hears this
10

Factories, Services e Providers

factory()

factory() recebe uma função que retorna a instância do service — a factory roda uma vez (singleton) e o valor de retorno é compartilhado. É a forma mais comum de criar um service: ótima para encapsular estado privado atrás de uma API limpa. Tudo o que você retornar (objeto, função, primitivo) vira o service.

angularjs
app.factory('UserService', ['$http', function($http) {
  var current = null;            // private state

  return {
    login: function(creds) {
      return $http.post('/login', creds).then(function(res) {
        current = res.data;
        return current;
      });
    },
    getCurrent: function() { return current; },
    isLoggedIn: function() { return !!current; }
  };
}]);

service()

service() instancia o construtor com new, então você anexa propriedades ao this. Equivale a uma factory que retorna uma nova instância — ambos são singletons. Use service() quando preferir estilo construtor/classe; use factory() quando precisar retornar um objeto específico ou embrulhar algo.

angularjs
app.service('Counter', function() {
  // invoked with 'new' -> 'this' is the instance
  this.count = 0;
  this.inc = function() { this.count++; };
  this.reset = function() { this.count = 0; };
});

// usage: Counter.inc(); Counter.count;

provider()

provider() é a receita de nível mais baixo: expõe um objeto de config (com setters) e uma factory $get que constrói a instância. Só providers são injetáveis em blocos config() (sufixo 'Provider'). Use provider() quando um service precisa de configuração antes da instanciação; caso contrário, prefira factory().

angularjs
app.provider('Greeter', function() {
  // config-time: defaults settable from .config()
  this.greeting = 'Hello';        // default

  this.setGreeting = function(g) { this.greeting = g; };

  // factory that produces the service instance
  this.$get = function() {
    var self = this;
    return {
      greet: function(name) { return self.greeting + ', ' + name + '!'; }
    };
  };
});

// configure in a config block:
app.config(['GreeterProvider', function(GreeterProvider) {
  GreeterProvider.setGreeting('Bonjour');
}]);

constant() vs value()

Ambos registram um valor simples injetável. constant() está disponível na fase de config (então providers podem usá-lo) e é imutável. value() só está disponível na fase de run. Regra prática: use constant para configuração de que providers dependem; use value para dados compartilhados em runtime ou helpers.

angularjs
// constant: injectable in config AND run phases
app.constant('MAX_USERS', 1000);

// value: injectable in run phase only (not config)
app.value('toastConfig', { duration: 3000 });

// value can hold any type, even a function
app.value('logger', function(msg) { console.log(msg); });

factory vs service vs provider

Por baixo dos panos toda receita é um provider: a função da factory vira $get, service é uma factory que instancia o construtor com new. Escolha pela legibilidade: factory para a maioria dos casos, service para classes em estilo construtor, provider quando precisar de config pré-instanciação. Os componentes apenas consomem, então a escolha é interna.

angularjs
// all three are singletons; the difference is HOW the instance is built

// factory: function returns the instance
app.factory('A', function() { return { x: 1 }; });

// service: constructor is 'new'-ed
app.service('B', function() { this.x = 1; });

// provider: $get returns the instance (configurable)
app.provider('C', function() {
  this.$get = function() { return { x: 1 }; };
});

$provide.decorator()

decorator() intercepta a instanciação de um service existente — $delegate é a instância original, que você pode embrulhar, estender ou substituir. Use para preocupações transversais (logging, cache, relatório de erros) sem tocar no service original. Decorators rodam de forma lazy, só quando o service é injetado pela primeira vez.

angularjs
app.decorator('$log', ['$delegate', function($delegate) {
  // $delegate is the original $log instance
  var origError = $delegate.error;
  $delegate.error = function(msg) {
    // e.g., send to error tracking, then call original
    trackError(msg);
    origError.apply($delegate, arguments);
  };
  return $delegate;   // return the (modified) service
}]);
11

Roteamento (ngRoute e ui-router)

Configuração do ngRoute

O ngRoute é o router embutido (num arquivo separado angular-route.js). Registre rotas com .when(path, config) e um fallback com .otherwise(). O ng-view é a saída onde o template+controller correspondentes são renderizados. O ngRoute suporta apenas uma saída e URLs simples com :param — para views aninhadas use ui-router.

angularjs
<!-- include angular-route.js (separate file in 1.x) -->
<script src="angular-route.js"></script>

var app = angular.module('myApp', ['ngRoute']);

app.config(['$routeProvider', function($routeProvider) {
  $routeProvider
    .when('/home', { templateUrl: 'home.html', controller: 'HomeCtrl' })
    .when('/users/:id', { templateUrl: 'user.html', controller: 'UserCtrl' })
    .otherwise({ redirectTo: '/home' });
}]);

<!-- where the matched view renders -->
<div ng-view></div>

Parâmetros de rota do ngRoute

$routeParams expõe os segmentos da URL (:id) como um objeto com chaves string — os valores são sempre strings, então converta números com parseInt. Ele atualiza após a mudança de rota. Para links dinâmicos use ng-href. O prefixo hashbang padrão é #! (desde a 1.6); configure com $locationProvider.hashPrefix('').

angularjs
app.controller('UserCtrl', ['$routeParams', 'UserSvc',
  function($routeParams, UserSvc) {
    // URL /users/42  ->  $routeParams.id === '42' (always a string)
    this.user = UserSvc.get($routeParams.id);
  }]);

<!-- links -->
<a href="#!/users/42">View user 42</a>
<!-- with HTML5 mode, use a plain href="/users/42" -->

Eventos de ciclo de vida do ngRoute

O ngRoute difunde $routeChangeStart (cancelável via event.preventDefault), $routeChangeSuccess e $routeChangeError. Os argumentos 'next'/'current' carregam a config da rota (com os resultados de resolve). Use-os para guards de autenticação, indicadores de carregamento e títulos de breadcrumb. Rejeições de resolve disparam $routeChangeError.

angularjs
app.run(['$rootScope', function($rootScope) {
  $rootScope.$on('$routeChangeStart', function(event, next, current) {
    if (next.requireAuth && !AuthService.isLoggedIn()) {
      event.preventDefault();             // cancel navigation
    }
  });

  $rootScope.$on('$routeChangeSuccess', function(event, current, previous) {
    $rootScope.pageTitle = current.$$route.title;
  });

  $rootScope.$on('$routeChangeError', function(event, current, previous, rejection) {
    console.error('route failed', rejection);
  });
}]);

States do ui-router

O ui-router organiza o app em states nomeados (não em caminhos de URL). ui-sref cria links por nome de state e parâmetros, e ui-view é a saída. States podem ser aninhados e ter URLs próprias. Isso desacopla a navegação das URLs e suporta views múltiplas/nomeadas — bem mais poderoso que o ngRoute para apps reais.

angularjs
var app = angular.module('myApp', ['ui.router']);

app.config(['$stateProvider', function($stateProvider) {
  $stateProvider
    .state('home', { url: '/home', templateUrl: 'home.html' })
    .state('users', { url: '/users', templateUrl: 'users.html' })
    .state('users.detail', {
      url: '/:id',
      templateUrl: 'user-detail.html',
      controller: 'UserDetailCtrl'
    });
}]);

<!-- outlet -->
<div ui-view></div>
<!-- links: state name instead of URL -->
<a ui-sref="users.detail({ id: 42 })">User 42</a>

resolve e states aninhados do ui-router

resolve mapeia chaves para promises; o controller só é instanciado quando cada resolve conclui. Se um resolve rejeita, $stateChangeError dispara e o state não é acessado. Os valores de resolve são injetáveis no controller pelas suas chaves. States filhos herdam e podem acessar os resolves do pai — útil para pré-carregar dados.

angularjs
$stateProvider.state('users.detail', {
  url: '/:id',
  templateUrl: 'user-detail.html',
  controller: 'UserDetailCtrl',
  controllerAs: 'vm',
  resolve: {
    // injected into the controller; waits for these before activating
    user: ['UserSvc', '$stateParams', function(UserSvc, $stateParams) {
      return UserSvc.get($stateParams.id);   // returns a promise
    }]
  }
});

app.controller('UserDetailCtrl', ['user', function(user) {
  this.user = user;   // already resolved
}]);

Views nomeadas múltiplas do ui-router

O ui-router pode renderizar várias saídas ui-view nomeadas por state. As chaves do map views correspondem aos nomes dos ui-view no template; a chave de string vazia aponta para a saída sem nome. Isso permite que um único state componha várias regiões (header, sidebar, main) — impossível com o único ng-view do ngRoute.

angularjs
$stateProvider.state('dashboard', {
  url: '/dashboard',
  views: {
    '':        { templateUrl: 'dashboard/main.html' },
    'sidebar': { templateUrl: 'dashboard/sidebar.html', controller: 'SideCtrl' },
    'header':  { templateUrl: 'dashboard/header.html' }
  }
});

<!-- index.html -->
<div ui-view="header"></div>
<div ui-view="sidebar"></div>
<div ui-view></div>          <!-- the unnamed '' view -->
12

Formulários e validação

Formulário com ng-model

Dê ao formulário um atributo name para expor seu estado de validação no scope. novalidate desliga os balões nativos do navegador para que o Angular controle a validação. Cada input nomeado publica seu próprio estado (myForm.email.$valid, $dirty, $error). O ng-model é necessário para a validação acompanhar o input.

angularjs
<form name="myForm" novalidate>
  <input name="email" type="email" ng-model="user.email" required>
  <input name="age" type="number" ng-model="user.age" min="18" required>

  <button ng-disabled="myForm.$invalid" ng-click="save()">Save</button>
</form>

<!-- novalidate disables the browser's native validation so Angular handles it -->

Estados de validação

Cada input expõe $pristine/$dirty (mudou?), $touched/$untouched (perdeu o foco?), $valid/$invalid e $error (um mapa dos validadores que falharam). O formulário agrega tudo: myForm.$invalid é true se qualquer input for inválido. Mostre mensagens só depois de $touched ou $dirty para não apontar erros antes de o usuário digitar.

angularjs
<input name="email" ng-model="user.email" required>
<p ng-show="myForm.email.$touched && myForm.email.$error.required">
  Email is required.
</p>

<!-- states available on each input / the form -->
<!-- $pristine, $dirty, $touched, $untouched, $valid, $invalid, $error -->

Validadores embutidos

Validadores embutidos: required, type=email/url/number, min/max, ng-minlength/ng-maxlength, ng-pattern. Cada validador que falha define uma chave em $error (por exemplo, $error.required, $error.minlength, $error.pattern). Escape as barras invertidas nas regex do ng-pattern dentro de atributos HTML.

angularjs
<input name="email" type="email" ng-model="user.email" required>
<input name="age" type="number" ng-model="user.age" min="18" max="120">
<input name="code" ng-model="user.code"
       ng-minlength="4" ng-maxlength="8" required>
<input name="url" type="url" ng-model="user.url">
<input name="zip" ng-model="user.zip" ng-pattern="/^\d{5}$/">

Validador personalizado (directive)

Adicione validadores personalizados com uma directive que requer ngModel e registra uma função em ctrl.$validators. Retorne true para válido, false para inválido — a falha aparece em $error sob a sua chave (aqui 'even'). Para validação assíncrona, use ctrl.$asyncValidators retornando uma promise.

angularjs
app.directive('evenNumber', function() {
  return {
    require: 'ngModel',
    link: function(scope, el, attrs, ctrl) {
      ctrl.$validators.even = function(modelValue, viewValue) {
        if (ctrl.$isEmpty(modelValue)) return true;   // let 'required' handle empty
        return parseInt(modelValue, 10) % 2 === 0;
      };
    }
  };
});

<input ng-model="n" even-number>
<p ng-show="form.n.$error.even">Must be even!</p>

ngMessages

O ngMessages mostra o primeiro erro correspondente (ou vários de uma vez com ng-messages-multiple). Bem mais limpo que empilhar ng-if para cada validador. Extraia mensagens compartilhadas para um partial e inclua com ng-messages-include='messages.html'. Funciona bem com chaves de validadores embutidos e personalizados.

angularjs
<!-- include angular-messages.js, add module 'ngMessages' -->
<script src="angular-messages.js"></script>

<div ng-messages="myForm.email.$error" ng-if="myForm.email.$touched">
  <div ng-message="required">Email is required.</div>
  <div ng-message="email">Enter a valid email.</div>
  <div ng-message="server">That email is taken.</div>
</div>

<!-- a template can be reused across fields with ng-messages-include -->

Envio do formulário

ng-submit dispara quando o formulário é enviado (tecla Enter ou um botão type='submit') e só se as validações do ng-model passarem, a menos que você sobrescreva. Passe myForm.$valid ao handler como checagem de segurança. novalidate garante que o Angular (não o navegador) conduza a validação. Desabilite o botão com ng-disabled para evitar submits duplicados.

angularjs
<form name="myForm" ng-submit="save(myForm.$valid)" novalidate>
  <input name="email" ng-model="user.email" required>
  <button type="submit" ng-disabled="myForm.$invalid">Save</button>
</form>

app.controller('FormCtrl', ['$scope', function($scope) {
  $scope.save = function(isValid) {
    if (!isValid) return;
    // ...submit to server
  };
}]);
13

Eventos (ng-click, ng-change, ...)

ng-click

ng-click avalia uma expressão quando o elemento é clicado. $event é o evento nativo do DOM, então você pode chamar stopPropagation/preventDefault nele — embora seja preferível usar ng-submit para formulários e directives embutidas quando possível. ng-click funciona em qualquer elemento, não só em botões.

angularjs
<button ng-click="count = count + 1">Inc</button>
<span>{{ count }}</span>

<!-- call a scope method -->
<button ng-click="save()">Save</button>

<!-- pass the native event with $event -->
<button ng-click="save($event)">Save</button>
<button ng-click="save($event); $event.stopPropagation()">Save</button>

ng-change

ng-change dispara depois que o ng-model atualizou o model — então $scope.country já é o novo valor. Exige ng-model no mesmo elemento. Use-o para reagir a mudanças em input/select/checkbox (dropdowns em cascata, filtragem ao vivo) sem montar seu próprio listener de change.

angularjs
<select ng-model="country" ng-change="onCountryChange()">
  <option value="us">US</option>
  <option value="uk">UK</option>
</select>

app.controller('LocCtrl', ['$scope', function($scope) {
  $scope.onCountryChange = function() {
    // fires AFTER ng-model updates $scope.country
    $scope.cities = CityService.forCountry($scope.country);
  };
}]);

ng-submit e família ng-focus/blur

ng-submit trata o envio do formulário. O Angular também expõe directives de eventos para muitos eventos do DOM: ng-focus, ng-blur, ng-change, ng-copy, ng-cut, ng-paste, ng-keydown/up/press, ng-mousedown/up/enter/over/leave/move e ng-dblclick. Cada uma avalia uma expressão, com $event disponível.

angularjs
<!-- ng-submit: on form submission -->
<form ng-submit="search()">
  <input ng-model="query">
</form>

<!-- the ng-focus / ng-blur / ng-copy / ng-cut / ng-paste directives -->
<input ng-model="q" ng-focus="onFocus()" ng-blur="onBlur()">
<input ng-copy="copied = true">

Eventos de teclado e mouse

O Angular fornece ng-keydown/ng-keypress/ng-keyup e ng-mousedown/up/enter/leave/over/move, além de ng-dblclick. Cada um passa $event, então você pode inspecionar $event.keyCode ou $event.shiftKey. Para atalhos no app inteiro, vincule no $document ou $window dentro de um service em vez de espalhar handlers pelos templates.

angularjs
<!-- keyboard events -->
<input ng-keydown="onKey($event)">
<input ng-keypress="onKey($event)">

<!-- mouse events -->
<div ng-mouseenter="hover = true" ng-mouseleave="hover = false">
  {{ hover ? 'Hovering' : 'Not hovering' }}
</div>
<button ng-dblclick="open()">Double-click</button>

Objeto $event

$event é o evento nativo do DOM repassado ao seu handler. Você pode ler target, coordenadas, teclas modificadoras e chamar preventDefault/stopPropagation. Evite lógica pesada em handlers de clique — chame uma função do controller/service em vez disso. $event está disponível em toda directive de evento.

angularjs
<button ng-click="onClick($event)">Click</button>

app.controller('ClickCtrl', ['$scope', function($scope) {
  $scope.onClick = function(event) {
    console.log(event.target);    // clicked element
    console.log(event.clientX, event.clientY);
    event.preventDefault();
    event.stopPropagation();
  };
}]);

Modificadores de evento (manuais)

Diferente do Vue/Angular 2+, o AngularJS não tem modificadores .stop/.prevent/.once — você chama as funções do evento manualmente dentro do handler. Isso é mais verboso, mas explícito. Para comportamentos frequentes (preventDefault automático no submit), o ng-submit já faz isso para formulários.

angularjs
<!-- AngularJS has NO built-in modifiers like .stop / .prevent.
     Call the method on $event instead. -->
<a href="/delete" ng-click="del($event)">Delete</a>

app.controller('DelCtrl', ['$scope', function($scope) {
  $scope.del = function(event) {
    event.preventDefault();   // stop the link navigation
    $scope.removeItem();
  };
}]);
14

$watch / $digest / $apply

$scope.$watch

$watch registra um listener que roda sempre que o valor observado muda durante um digest. O primeiro argumento pode ser uma expressão em string ou uma função; o callback recebe (newVal, oldVal). $watch retorna uma função de cancelamento — chame-a para parar de observar e evitar vazamentos, especialmente em directives.

angularjs
app.controller('WatchCtrl', ['$scope', function($scope) {
  $scope.user = { name: 'Ada' };

  // watch a path expression (string)
  var unbind = $scope.$watch('user.name', function(newVal, oldVal) {
    console.log('name changed', oldVal, '->', newVal);
  });

  // stop watching (frees resources)
  unbind();
}]);

$watchCollection

$watchCollection observa um nível de um array ou objeto: dispara quando itens são adicionados/removidos/substituídos, mas NÃO compara profundamente as propriedades dos itens. Bem mais barato que o $watch profundo (terceiro argumento true). Use para arrays de primitivos ou quando só importa a composição da lista, não o conteúdo profundo.

angularjs
$scope.items = [1, 2, 3];

// watch array/object shallowly: detects add/remove/replace but NOT deep mutation
$scope.$watchCollection('items', function(newItems, oldItems) {
  console.log('collection changed', newItems);
});

// fires on push/splice, or when an item is replaced,
// but NOT when an item's own properties change.

$watch profundo (terceiro argumento)

Passar true como terceiro argumento faz o $watch comparar valores em profundidade — dispara quando qualquer propriedade aninhada muda. Isso é caro (percorre o objeto inteiro a cada digest). Prefira observar um caminho específico ou usar $watchCollection. Reserve o watch profundo para objetos pequenos onde você realmente precisa.

angularjs
$scope.config = { ui: { theme: 'dark' } };

// third arg true -> deep comparison by value (expensive!)
$scope.$watch('config', function(n, o) {
  console.log('config (deep) changed');
}, true);

// prefer watching a specific path when possible:
$scope.$watch('config.ui.theme', function(n, o) { /* cheaper */ });

$scope.$apply

Código fora do mundo Angular (setTimeout puro, XHR sem $http, eventos jQuery, callbacks de Promise) atualiza o model mas o Angular não sabe — chame $apply() para disparar um $digest. A forma com função embrulha e trata exceções das mudanças e roda um único digest. Dentro dos services do Angular ($http, $timeout) o $apply já é feito — não aplique duas vezes.

angularjs
// NON-Angular async callback (e.g., a 3rd-party library) won't trigger a digest
externalLib.onReady(function() {
  $scope.message = 'Ready!';

  // tell Angular to run a digest so the view updates
  $scope.$apply();
});

// or wrap the change so errors are caught and digest runs once
$scope.$apply(function() {
  $scope.message = 'Ready!';
  $scope.ready = true;
});

$evalAsync e $timeout (apply seguro)

Prefira $evalAsync ou $timeout(fn, 0) a um $apply manual quando não tiver certeza se um digest já está em andamento — eles evitam erros de 'digest already in progress'. $evalAsync agrupa no digest atual; $timeout adia para o próximo tick. Use $timeout quando também precisar que o DOM já tenha renderizado.

angularjs
// $evalAsync: schedule work later in the SAME digest if one is running,
//             otherwise start a new one. Safer than $apply.
$scope.$evalAsync(function() {
  $scope.computed = heavyCompute();
});

// $timeout(..., 0) always runs in a fresh digest — useful when you
// need the DOM updated before your code runs.
$timeout(function() {
  $scope.deferred = true;
}, 0);

O ciclo $digest explicado

$digest é o loop que propaga mudanças do model para a view: reavalia cada watcher até que os valores parem de mudar (dirty-checking), com limite de 10 iterações. Como cada watcher roda a cada digest, o desempenho escala com a quantidade de watchers. Reduza watchers com binding única (::), track by e movendo cálculos para o controller.

angularjs
// a $digest iterates over ALL watchers on $scope and its children:
//   1. read each watched value, compare to previous
//   2. if changed, call the listener
//   3. listeners may change other watched values -> re-run
//   4. repeat until stable (max 10 iterations -> error)

// so: keep watchers cheap and few.
// track by, one-time binding (::), and compute in controllers help.
15

Components (.component())

Básico do .component()

.component() é um açúcar sobre directive, otimizado para componentes baseados em template. Por padrão usa restrict 'E', isolate scope e controllerAs '$ctrl' — então use this (com alias $ctrl) em vez de $scope. bindings substitui scope:{...}; '<' (entrada unidirecional) é preferido a '=' para inputs desde a 1.5.

angularjs
app.component('heroDetail', {
  template: '<h2>{{$ctrl.hero.name}}</h2><p>{{$ctrl.hero.power}}</p>',
  bindings: {
    hero: '<'        // one-way ('<'), two-way ('='), string ('@'), expr ('&')
  }
});

<!-- usage -->
<hero-detail hero="selectedHero"></hero-detail>

Component com controller e bindings

O controller de um component usa this (com alias $ctrl no template). bindings declara entradas ('<', '=') e saídas ('&'). O '<' unidirecional é preferido para entradas. Saídas usam '&' — chame-as com um objeto de argumento que vira as locals da expressão do pai: onChange({ value: ... }).

angularjs
app.component('counter', {
  bindings: {
    start: '<',
    onChange: '&'
  },
  template: `
    <button ng-click="$ctrl.dec()">-</button>
    <span>{{ $ctrl.count }}</span>
    <button ng-click="$ctrl.inc()">+</button>
  `,
  controller: function() {
    this.$onInit = function() { this.count = this.start || 0; };
    this.inc = function() { this.count++; this.onChange({ value: this.count }); };
    this.dec = function() { this.count--; this.onChange({ value: this.count }); };
  }
});

Hooks de ciclo de vida do component

Os hooks de component do AngularJS 1.5+ espelham o ciclo de vida do Angular 2+: $onInit (inicialização), $onChanges (mudanças de bindings, com isFirstChange), $doCheck (a cada digest), $postLink (depois do link do DOM filho), $onDestroy (destruição). Use-os em vez de enfiar lógica no construtor — tornam o comportamento do componente explícito e testável.

angularjs
app.component('editor', {
  bindings: { doc: '<', onClose: '&' },
  controller: function() {
    this.$onInit = function() { /* after bindings, before first render */ };
    this.$onChanges = function(changes) {
      // changes.doc: { currentValue, previousValue, isFirstChange() }
    };
    this.$doCheck = function() { /* every digest: custom dirty checking */ };
    this.$onDestroy = function() { /* cleanup: timers, listeners */ };
    this.$postLink = function() { /* after child linking, DOM ready */ };
  }
});

Detalhes do $onChanges

$onChanges dispara sempre que a referência de uma binding unidirecional ('<') muda, com um objeto changes: cada chave tem currentValue, previousValue e isFirstChange(). Ele NÃO dispara para mutações do mesmo objeto (a referência não mudou) — para isso use $doCheck. Sempre dispara uma vez na inicialização com isFirstChange() true.

angularjs
app.component('userView', {
  bindings: { user: '<' },
  controller: function() {
    this.$onChanges = function(changesObj) {
      // changesObj is keyed by binding name
      if (changesObj.user) {
        var c = changesObj.user;
        console.log(c.previousValue, '->', c.currentValue);
        console.log('first time?', c.isFirstChange());
      }
    };
  }
});

Transclusion em components

Defina transclude: true e inclua ng-transclude no template para permitir que quem usa o componente injete conteúdo. Em components, transclusion multi-slot também é suportada via transclude: { slotName: 'elementName' }. A transclusion permite construir wrappers reutilizáveis (panels, modals, cards) cujo corpo é fornecido pelo pai.

angularjs
app.component('modal', {
  transclude: true,
  template: `
    <div class="modal">
      <div class="modal-body" ng-transclude></div>
    </div>
  `,
  bindings: { title: '@' }
});

<!-- caller's content lands in ng-transclude -->
<modal title="Confirm">
  <p>Are you sure?</p>
  <button>Yes</button>
</modal>

Component vs Directive

Use components para tudo que renderiza um template — são mais simples e aproximam você do modelo do Angular 2+ (isolate scope, this/controllerAs, hooks de ciclo de vida). Reserve directives para comportamentos em formato de atributo sem template (autofocus, gatilho de tooltip, máscara de input) e manipulação direta do DOM no link.

angularjs
// COMPONENT: template-based, isolate scope, controllerAs by default
app.component('userCard', {
  template: '...',
  bindings: { user: '<' }
});

// DIRECTIVE: still needed for attribute behavior / DOM manipulation
app.directive('autoFocus', function() {
  return { restrict: 'A', link: function(scope, el) { el[0].focus(); } };
});
16

Service de promises $q

Básico do $q.defer()

$q é a implementação de Promise do Angular (Promises/A+). Crie com $q.defer(), depois resolve(value) ou reject(reason). A promise é consciente do digest: a resolução dispara um $digest para a view atualizar. Prefira $q à Promise nativa quando precisar do auto-digest do Angular; caso contrário, a Promise nativa também funciona.

angularjs
app.factory('AsyncWork', ['$q', function($q) {
  return function() {
    var deferred = $q.defer();

    setTimeout(function() {
      if (success) deferred.resolve('done');
      else         deferred.reject(new Error('failed'));
    }, 100);

    return deferred.promise;     // { then, catch, finally }
  };
}]);

// consume
AsyncWork().then(function(v) { console.log(v); })
          .catch(function(e) { console.error(e); });

$q.when / $q.all / $q.reject

$q.when embrulha um valor simples ou uma promise que não é do $q. $q.all espera um array ou objeto de promises e resolve com os resultados na mesma forma. $q.reject(reason) é uma forma conveniente de retornar uma promise rejeitada (por exemplo, para validação antecipada numa cadeia). Cada um respeita o digest.

angularjs
// $q.when: wrap a value (or foreign promise) in an Angular promise
$q.when(42).then(function(v) { /* v === 42 */ });

// $q.all: wait for many promises in parallel
$q.all([getUser(), getPosts(), getFriends()]).then(function(results) {
  var user = results[0], posts = results[1], friends = results[2];
});

// $q.all with an object (named results)
$q.all({ user: getUser(), posts: getPosts() }).then(function(r) {
  r.user; r.posts;
});

// $q.reject: shortcut to return a rejected promise
return $q.reject(new Error('bad input'));

Encadeando promises

Retornar um valor de .then o passa ao próximo handler; retornar uma promise faz a cadeia esperar. Um único .catch trata qualquer rejeição a montante. .finally roda tanto em sucesso quanto em falha — perfeito para esconder loaders. Cada handler roda dentro do digest do Angular, então atualizações de scope simplesmente funcionam.

angularjs
getUser(id)
  .then(function(user) {
    return getOrders(user);    // return a promise -> chain waits
  })
  .then(function(orders) {
    return orders.filter(paid); // return a value -> next step
  })
  .then(function(paidOrders) {
    $scope.paid = paidOrders;
  })
  .catch(function(err) {
    // any rejection above lands here
    console.error(err);
  })
  .finally(function() {
    $scope.loading = false;    // runs regardless
  });

$http retorna promises

O $http já retorna uma promise do $q, então encadeie .then para transformar a resposta (frequentemente extraindo .data) e retornar um valor mais limpo. Embrulhar o $http num service dá aos chamadores uma API organizada e centraliza o tratamento de URL/base-url/erros. Interceptors são outra forma de aplicar comportamento transversal ao $http.

angularjs
app.factory('UserApi', ['$http', function($http) {
  return {
    list: function() { return $http.get('/users').then(function(r) { return r.data; }); },
    get:  function(id) { return $http.get('/users/' + id).then(function(r) { return r.data; }); }
  };
}]);

// caller doesn't deal with response.data, just the user
UserApi.get(42).then(function(user) { $scope.user = user; });

Construtor $q (estilo ES6)

Desde a 1.6, o $q suporta a forma do construtor Promise do ES6: $q(function(resolve, reject){...}). É mais conciso que $q.defer() e combina com a sintaxe da Promise nativa. Use ao embrulhar uma única API assíncrona. A promise resultante continua consciente do digest, então a view atualiza automaticamente ao resolver.

angularjs
// Angular 1.6+ supports the resolver-style constructor, like native Promise
app.factory('loadImg', ['$q', function($q) {
  return function(src) {
    return $q(function(resolve, reject) {
      var img = new Image();
      img.onload  = function() { resolve(img); };
      img.onerror = function() { reject(new Error('load failed')); };
      img.src = src;
    });
  };
}]);

$q vs Promise nativa

A diferença principal: $q dispara um $digest ao resolver, a Promise nativa não. Em apps AngularJS modernos em navegadores evergreen, você pode usar Promise nativa, mas precisa embrulhar as atualizações de model em $apply (ou $evalAsync). Por consistência e conveniência, prefira $q dentro do código Angular.

angularjs
// native Promise: no auto-digest; you must $apply manually
Promise.resolve().then(function() {
  $scope.x = 1;
  $scope.$apply();           // otherwise the view won't update
});

// $q promise: resolves inside a $digest automatically
$q.when().then(function() { $scope.x = 1; });   // view updates
17

Animações (ngAnimate)

Configuração do ngAnimate

O ngAnimate é um módulo separado (arquivo JS próprio). Uma vez adicionado como dependência, ele automaticamente aumenta as directives embutidas para que adicionem classes CSS durante transições de enter/leave/move — você só escreve CSS. Sem JS para o caso comum. Sem o ngAnimate, essas directives mudam o DOM instantaneamente.

angularjs
<!-- include angular-animate.js, then depend on 'ngAnimate' -->
<script src="angular-animate.js"></script>

var app = angular.module('myApp', ['ngAnimate']);

<!-- ngAnimate now adds classes automatically to:
     ng-repeat (enter/leave/move), ng-if, ng-show, ng-hide,
     ng-class, ng-view, ng-include, ui-view -->

Classes de transição CSS

O ngAnimate adiciona duas classes por evento: uma classe inicial (por exemplo, .ng-enter) e uma classe -active (.ng-enter-active) um frame depois. Defina uma transição CSS na classe inicial e o estado final na classe active — o Angular remove ambas quando a transição termina. Esta é a abordagem de animação mais simples e performática.

angularjs
/* .ng-enter / .ng-leave / .ng-move are added automatically */
.fade.ng-enter        { transition: opacity 0.3s; opacity: 0; }
.fade.ng-enter-active { opacity: 1; }

.fade.ng-leave        { transition: opacity 0.3s; opacity: 1; }
.fade.ng-leave-active { opacity: 0; }

<!-- apply the .fade class to your ng-if / ng-repeat element -->
<div class="fade" ng-if="show">Hello</div>

Animações CSS @keyframes

Você pode usar animações CSS @keyframes em vez de transições — o ngAnimate alterna as mesmas classes .ng-enter/.ng-leave/.ng-move, e o keyframe roda. Com keyframes você só precisa da classe inicial (não precisa da -active) porque a animação conduz toda a sequência. Bom para efeitos de bounce/spring.

angularjs
/* use @keyframes; ngAnimate still toggles the classes */
.pop.ng-enter { animation: pop-in 0.3s; }

@keyframes pop-in {
  0%   { transform: scale(0); }
  100% { transform: scale(1); }
}

<div class="pop" ng-if="visible">Pop!</div>

ng-repeat enter / leave / move

Os itens do ng-repeat recebem as classes .ng-enter (novo), .ng-leave (removido) e .ng-move (reordenado). Use track by para que o Angular consiga casar itens entre mudanças e animar movimentos corretamente. Animações escalonadas são possíveis com .ng-enter-stagger / .ng-leave-stagger para atrasar cada item — ótimo para efeitos de revelação de listas.

angularjs
/* list items animate when added, removed, or reordered */
.list-item.ng-enter        { transition: all 0.3s; opacity: 0; transform: translateY(-10px); }
.list-item.ng-enter-active { opacity: 1; transform: translateY(0); }

.list-item.ng-leave-active { opacity: 0; transform: translateX(20px); }

/* .ng-move animates reordering (track by recommended) */
.list-item.ng-move        { transition: transform 0.3s; }
.list-item.ng-move-active { }

<ul><li class="list-item" ng-repeat="t in todos track by t.id">{{ t.text }}</li></ul>

Service $animate (animações em JS)

app.animation(cssSelector, factory) registra uma animação JS para elementos que casam com o seletor. As funções enter/leave/move/class recebem o elemento e um callback done. Útil quando CSS não basta (por exemplo, jQuery.animate ou uma biblioteca de física). Retorne uma função cancel para limpeza. Animações JS são mais pesadas que CSS — prefira CSS quando possível.

angularjs
app.animation('.fade-js', ['$animate', function($animate) {
  return {
    enter: function(element, done) {
      element.css('opacity', 0);
      element.animate({ opacity: 1 }, 300, done);
      return function(cancelled) { /* cleanup if cancelled */ };
    },
    leave: function(element, done) {
      element.animate({ opacity: 0 }, 300, done);
    }
  };
}]);

<div class="fade-js" ng-if="show">Hello</div>

Desabilitando animações

Desligue animações globalmente ou por subárvore com $animate.enabled, ou via classe ng-animate-disabled. Isso é útil para desempenho em listas grandes ou para desabilitar animações em testes. O ng-animate-children permite que um pai opte por animar os filhos juntos (por padrão, uma animação do pai pula as animações dos filhos).

angularjs
<!-- ng-animate-ref / ng-animate-sref control animation between routes -->

<!-- opt out per-element -->
<div ng-if="x" ng-animate-children>...</div>
<div ng-if="y" class="ng-animate-disabled">...</div>

// programmatically
$animate.enabled(false);                    // globally off
$animate.enabled(false, element);           // off for subtree
$animate.enabled(true, element);            // back on
18

Testes (Karma e Jasmine)

Esboço de config do Karma

O Karma é o test runner padrão do AngularJS: abre navegadores reais, carrega seus scripts mais o angular-mocks e reporta os resultados do Jasmine. O angular-mocks fornece os helpers module() e inject() e services mock ($httpBackend). singleRun:true sai após uma execução (CI); omita para modo watch.

angularjs
// karma.conf.js (sketch)
module.exports = function(config) {
  config.set({
    frameworks: ['jasmine'],
    files: [
      'node_modules/angular/angular.js',
      'node_modules/angular-mocks/angular-mocks.js',
      'src/**/*.js',
      'test/**/*.spec.js'
    ],
    browsers: ['ChromeHeadless'],
    singleRun: true
  });
};

// run: karma start karma.conf.js

Básico do Jasmine

O Jasmine fornece describe (suíte), it (spec), beforeEach/afterEach (setup/teardown) e expect com matchers (toBe, toEqual, toContain, toBeTruthy, toThrow, etc.). xit/xdescribe pulam specs. Testes são síncronos por padrão; para assíncronos, use callback done ou o suporte a async/await do Jasmine.

angularjs
describe('UserService', function() {
  beforeEach(function() { /* setup */ });
  afterEach(function() { /* teardown */ });

  it('isLoggedIn is false by default', function() {
    var svc = makeService();
    expect(svc.isLoggedIn()).toBe(false);
  });

  it('greets by name', function() {
    expect(greet('Ada')).toEqual('Hi, Ada');
  });

  // pending / disabled
  xit('not yet implemented', function() {});
});

Testando um controller

module('myApp') carrega o módulo Angular; inject() resolve os services (frequentemente com aliases com underscores no início/fim). Crie um controller com $controller('Name', { $scope: scope }) passando dependências falsas. Depois faça asserções sobre o scope. Esse padrão também funciona com controllerAs: passe funções vinculadas ao this e inspecione a instância retornada.

angularjs
describe('TodoCtrl', function() {
  beforeEach(module('myApp'));

  var $controller, $scope;
  beforeEach(inject(function(_$controller_, _$rootScope_) {
    $scope = _$rootScope_.$new();
    $controller = _$controller_;
  }));

  it('starts with two todos', function() {
    $controller('TodoCtrl', { $scope: $scope });
    expect($scope.todos.length).toBe(2);
  });

  it('addTodo pushes and clears the input', function() {
    $controller('TodoCtrl', { $scope: $scope });
    $scope.todoText = 'New';
    $scope.addTodo();
    expect($scope.todos.length).toBe(3);
    expect($scope.todoText).toBe('');
  });
});

Testando um service

Injete o service sob teste e o $httpBackend do angular-mocks. expectGET(url).respond(data) monta uma resposta falsa; flush() resolve as requisições pendentes de forma síncrona. verifyNoOutstandingExpectation() no afterEach pega expectativas não atendidas. Isso torna services baseados em $http totalmente testáveis sem servidor real.

angularjs
describe('UserService', function() {
  var UserService, $httpBackend;

  beforeEach(module('myApp'));
  beforeEach(inject(function(_UserService_, _$httpBackend_) {
    UserService = _UserService_;
    $httpBackend = _$httpBackend_;
  }));

  afterEach(function() { $httpBackend.verifyNoOutstandingExpectation(); });

  it('list() fetches users', function() {
    $httpBackend.expectGET('/api/users').respond([{ name: 'Ada' }]);
    var users;
    UserService.list().then(function(u) { users = u; });
    $httpBackend.flush();          // resolve the pending request
    expect(users.length).toBe(1);
  });
});

Testando uma directive

Compile um trecho de HTML com $compile(html)(scope), depois rode scope.$digest() para avaliar as bindings e linkar as directives. Faça asserções sobre o elemento jqLite resultante (el.find, el.text, el.attr). Para templateUrl, use $httpBackend.expectGET para fornecer o template e faça flush antes do digest. Teste o isolate scope via el.isolateScope().

angularjs
describe('greeting directive', function() {
  var $compile, $rootScope;
  beforeEach(module('myApp'));
  beforeEach(inject(function(_$compile_, _$rootScope_) {
    $compile = _$compile_; $rootScope = _$rootScope_;
  }));

  it('renders the template', function() {
    var scope = $rootScope.$new();
    scope.name = 'Ada';
    var el = $compile('<greeting name="name"></greeting>')(scope);
    scope.$digest();              // process watchers / bindings
    expect(el.find('h1').text()).toContain('Ada');
  });
});

Mocking com $httpBackend

expectGET (e expectPOST/etc.) afirma que a requisição foi feita e falha se não foi; whenGET retorna dados silenciosamente se chamado, ignorando se não. Use expect para asserções de 'isso deve acontecer' e when para setup. flush() resolve as requisições pendentes em ordem. Sempre chame verifyNoOutstanding* no afterEach para pegar discrepâncias.

angularjs
// EXPECT: a specific request must happen (asserts it was made)
$httpBackend.expectGET('/api/users').respond(200, [{ id: 1 }]);
// WHEN:  just stub a request if it happens (no assertion)
$httpBackend.whenGET('/api/users').respond(200, [{ id: 1 }]);

// flush triggers all pending requests:
$httpBackend.flush();

// verify nothing was left unflushed:
$httpBackend.verifyNoOutstandingExpectation();
$httpBackend.verifyNoOutstandingRequest();
19

Injeção de dependência

Básico da DI

A DI do Angular resolve dependências inspecionando os nomes dos parâmetros das funções. Esse estilo 'implícito' é conciso mas quebra com minificação (os nomes dos parâmetros são encurtados). Serve para protótipos/demos. Em produção, use um dos estilos de anotação — array inline ou $inject — ou automatize com ng-annotate.

angularjs
// services are injected by NAME into the constructor's parameters
app.controller('A', function($scope, $http, UserService) { /* ... */ });

// Angular inspects the parameter names to resolve dependencies.
// works in development but BREAKS after minification (see below).

Anotação de array inline

O estilo mais comum e seguro contra minificação: passe um array cujos elementos são os nomes dos services (como strings), com o construtor por último. As strings sobrevivem à minificação, então o Angular resolve corretamente. Use sempre para código que será minificado. É trabalhoso manter à mão — ng-annotate ou plugins do babel podem adicioná-lo automaticamente.

angularjs
app.controller('A', ['$scope', '$http', 'UserService',
  function($scope, $http, UserService) {
    // parameter names no longer matter; the strings drive DI
    $scope.users = UserService.list();
  }
]);

Anotação por propriedade $inject

Anexe um array $inject de nomes de services (como strings) à função construtora. O Angular o lê para resolver as dependências, ignorando os nomes dos parâmetros. Isso mantém a declaração da função legível e permite reutilizar o mesmo construtor. O ng-annotate pode gerar o $inject automaticamente a partir dos nomes dos parâmetros durante o build.

angularjs
function ACtrl($scope, UserService) {
  $scope.users = UserService.list();
}
ACtrl.$inject = ['$scope', 'UserService'];   // explicit list

app.controller('A', ACtrl);

// equivalent to the inline array form; useful when you want
// a separately-declared, reusable constructor function.

Service $injector

$injector é o contêiner de DI: .get(name) retorna um singleton, .annotate(fn) retorna a lista de dependências, .instantiate/.invoke constroem/chamam funções com suas dependências. Raramente necessário no código do app, mas útil em cenários dinâmicos (carregar services por nome) e dentro de directives personalizadas ou resolve de router.

angularjs
// resolve and instantiate on demand
var svc = $injector.get('UserService');          // retrieve singleton
var fn  = $injector.annotate(MyCtrl);            // [' $scope', ...] via reflection
var inst = $injector.instantiate(MyCtrl);        // 'new' with DI
var res  = $injector.invoke(MyCtrl, context);    // call with DI

// list all registered service names (debug)
// $injector has modules / providers info

ng-annotate (tempo de build)

ng-annotate é uma ferramenta de build que adiciona anotações de array inline automaticamente, então você escreve DI implícita limpa e entrega código seguro contra minificação. Use /* @ngInject */ para desambiguar casos complicados. Integra com gulp, grunt, webpack, babel. O sucessor ng-annotate-patched mantém o suporte a toolchains modernos.

angularjs
// Write clean code with a hint comment:
app.controller('A', /* @ngInject */ function($scope, UserService) {
  $scope.users = UserService.list();
});

// ng-annotate (run by your build tool) rewrites it to:
app.controller('A', ['$scope', 'UserService', function($scope, UserService) {
  $scope.users = UserService.list();
}]);

Modo strict DI

ng-strict-di faz a injeção de dependência implícita (sem anotação) lançar erro em runtime, então você pega código inseguro contra minificação no desenvolvimento em vez de na produção. Mantenha ativo em dev e testes. Impacta levemente o desempenho (checagens extras), então normalmente é removido nos builds de produção.

angularjs
<html ng-app="myApp" ng-strict-di>
  ...
</html>

// or when bootstrapping manually:
angular.bootstrap(root, ['myApp'], { strictDi: true });

// in strict-DI mode, any service using IMPLICIT (unannotated) DI
// throws an error, catching minification bugs during development.
20

Boas práticas e desempenho

Use controllerAs

controllerAs deixa explícito qual controller possui cada propriedade, evita o sombreamento de primitivos da herança de scopes e aproxima você do modelo de 'componentes' do Angular 2+. Vincule ao this (com alias) em vez do $scope. Para components, $ctrl é o alias padrão — use-o de forma consistente.

angularjs
<!-- prefer controllerAs over $scope -->
<div ng-controller="UsersCtrl as users">
  <li ng-repeat="u in users.list">{{ u.name }}</li>
</div>

app.controller('UsersCtrl', function(UserService) {
  // 'this' is exposed as 'users' in the template
  this.list = UserService.list();
  this.remove = function(id) { UserService.remove(id); };
});

Binding única (::)

Prefixe uma expressão com :: para torná-la uma binding única: o Angular avalia uma vez e, quando definida, remove o watcher. Para dados que não mudam (títulos, timestamps, listas estáticas), isso corta bastante a contagem de watchers — a maior vitória de desempenho em apps AngularJS.

angularjs
<!-- static data: bind once, drop the watcher -->
<h1>{{ ::conference.name }}</h1>
<span>{{ ::user.createdAt | date }}</span>

<!-- ng-repeat over a static list -->
<li ng-repeat="item in ::staticItems">{{ item.label }}</li>

<!-- less watchers = faster digest for the whole app -->

track by no ng-repeat

Sem track by, o Angular usa um $$hashKey interno para casar itens — quando o array muda, ele pode re-renderizar e recriar o DOM de itens que não mudaram de fato, perdendo estado dos filhos. track by u.id dá uma identidade estável para o Angular reutilizar nós. Essencial para desempenho em listas grandes e corrige erros de 'ng-repeat duplicates'.

angularjs
<!-- BAD: Angular uses $$hashKey, re-renders everything on change -->
<li ng-repeat="u in users">{{ u.name }}</li>

<!-- GOOD: stable identity -> Angular reuses DOM nodes -->
<li ng-repeat="u in users track by u.id">{{ u.name }}</li>

<!-- for primitives, use $index (only if list doesn't reorder) -->
<li ng-repeat="n in nums track by $index">{{ n }}</li>

Mova a lógica para services

Controllers são difíceis de testar e amarrados ao $scope; services são singletons, injetáveis e testáveis por unidade. Empurre a lógica de negócio, o acesso a dados e o estado compartilhado para os services, e mantenha os controllers focados em ligar a view a esses services. Essa separação também permite que vários controllers compartilhem a mesma lógica.

angularjs
// BAD: logic crammed in the controller
app.controller('BadCtrl', function($scope) {
  $scope.calc = function() { /* 50 lines of business logic */ };
});

// GOOD: controller delegates to a testable service
app.controller('GoodCtrl', function(PriceService) {
  this.total = PriceService.calcTotal(this.items);   // thin
});

app.factory('PriceService', function() {
  return { calcTotal: function(items) { /* ... */ } };
});

Bind única / reduza watchers

Cada {{ }} e a maioria das bindings criam um watcher que roda a cada digest. Evite chamadas de função dentro de bindings (elas reexecutam a cada digest mesmo sem mudanças nos inputs) — pré-calcule e armazene o resultado. Combine binding única (::), track by e cálculo no controller para manter a contagem de watchers baixa em páginas grandes.

angularjs
<!-- compute once in the controller, render many times -->
app.controller('Ctrl', function() {
  this.sortedUsers = this.users.slice().sort(byName); // do it once
});

<!-- avoid function calls in bindings: they re-run each digest -->
<!-- BAD:  {{ heavyCompute() }} -->
<!-- GOOD: compute once, bind the result -->
<p>{{ cachedResult }}</p>

Organização de módulos

Organize por funcionalidade (não por tipo de arquivo) para que cada funcionalidade seja um módulo autocontido com seu controller, service, template, rotas e testes. O módulo raiz do app apenas compõe os módulos de funcionalidade. Isso mantém código relacionado junto, torna funcionalidades reutilizáveis entre apps e escala bem melhor que um único módulo gigante.

angularjs
// split features into sub-modules, each self-contained
angular.module('myApp.users', ['myApp.common']);
angular.module('myApp.posts', ['myApp.common']);
angular.module('myApp', ['myApp.users', 'myApp.posts', 'ngRoute']);

// file layout per feature:
//   users/users.module.js
//   users/users.controller.js
//   users/users.service.js
//   users/users.html
//   users/users.routes.js
//   users/users.spec.js

Was this helpful?