Skip to content

AngularJS Aide-mémoire

Framework web front-end basé sur JavaScript (Angular 1.x).

01

Démarrage

Configuration et amorçage

AngularJS (1.x) s'inclut via une balise script. ng-app amorce l'application et ng-controller câble un contrôleur à un sous-arbre DOM. Les doubles accolades {{ }} sont des expressions Angular qui rendent les données du modèle.

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 et amorçage automatique

ng-app avec un nom de module amorce automatiquement AngularJS à DOMContentLoaded. ng-strict-di force les annotations de dépendances explicites, attrapant tôt les bugs de minification en développement. Un seul ng-app s'amorce automatiquement par page.

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

Amorçage manuel

Employez angular.bootstrap() quand vous devez différer le démarrage (ex. en attendant le chargement asynchrone de modules ou une config récupérée). On peut ainsi amorcer plusieurs apps Angular sur une même page, chacune sur son élément racine.

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>

Première liaison de données

Avec ng-app et sans nom de module, Angular tourne en mode 'auto' avec le module ng par défaut. ng-model lie l'input à une propriété nommée 'name' sur la portée implicite, et {{ }} la rend en direct. C'est la liaison de données bidirectionnelle dans sa forme la plus simple.

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

Bases des modules et contrôleurs

angular.module('nom', [deps]) crée un module ; angular.module('nom') récupère un existant. L'annotation tableau en ligne ['$scope', function($scope){}] garde le contrôleur sûr à la minification. Passez toujours explicitement les dépendances au module en le créant.

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

Modules

Créer vs récupérer un module

La forme à deux arguments angular.module(nom, deps) crée un nouveau module. La forme à un argument angular.module(nom) récupère un module défini précédemment. Passer [] deux fois par accident efface silencieusement les enregistrements du module.

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

Dépendances de module

Le tableau de dépendances liste les modules dont les providers s'injectent dans celui-ci. Les modules intégrés comme ngRoute sont optionnels et doivent être explicitement listés (avec leur script chargé). Les sous-modules permettent de découper une grande app en morceaux réutilisables.

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

Bloc config

config() tourne pendant l'enregistrement des providers, avant toute création d'instance de service. C'est le seul endroit où l'on peut injecter et configurer des Providers (ex. $routeProvider, $locationProvider). Employez-le pour installer les routes, activer le mode HTML5 ou enregistrer des validateurs personnalisés.

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

Bloc run

run() s'exécute après la création de l'injecteur et la configuration de tous les providers — le point d'entrée « main » de l'app. On y injecte des instances (pas des providers). Il sert couramment à enregistrer des écouteurs globaux de $rootScope pour les changements de route ou les vérifications d'authentification.

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

Constantes et valeurs

constant() enregistre une valeur injectable aussi dans les blocs config() — idéal pour la configuration dont les providers ont besoin. value() ne s'injecte que dans les constructions de la phase run (services, contrôleurs). Employez constant pour la config qui doit être disponible tôt.

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

Contrôleurs

Contrôleur de base

Les contrôleurs installent l'état initial de $scope et ajoutent du comportement (fonctions). Gardez les contrôleurs minces — la logique métier appartient aux services. Le constructeur du contrôleur tourne à chaque fois qu'une nouvelle instance est nécessaire (ex. à chaque usage 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;
  };
}]);

Syntaxe controllerAs

controllerAs publie l'instance du contrôleur sur la portée sous un alias (main). Employez-le au lieu de $scope pour propriétés et méthodes. Cela évite les pièges d'héritage de $scope et rend explicite le contrôleur d'où vient une propriété dans les vues imbriquées.

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 sûr à la minification

Les minifieurs renomment les paramètres de fonction, cassant l'inférence de dépendances par nom d'Angular. L'annotation tableau en ligne liste les noms de services en chaînes avant la fonction, les noms survivent donc à la minification. Employez toujours cette annotation 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) { /* ... */ });

Annotation par propriété $inject

Une alternative au tableau en ligne : attachez au constructeur un tableau $inject de noms de services. Cela garde la déclaration de fonction lisible et réutilisable. Les deux styles sont équivalents — choisissez-en un et soyez cohérent (ou automatisez avec 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);

Contrôleurs imbriqués et héritage

Les portées enfants héritent prototypalement des parents, donc un contrôleur enfant lit les propriétés parentes. Mais affecter une primitive sur l'enfant crée une nouvelle propriété locale qui masque le parent au lieu de le mettre à jour — un piège courant. Préférez les objets (notation point) ou controllerAs pour l'éviter.

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

Nettoyage du contrôleur ($destroy)

Écoutez l'événement $destroy sur $scope pour nettoyer quand la portée du contrôleur est démontée (ex. en naviguant ailleurs). Annulez les minuteurs $interval/$timeout, déliez les écouteurs fenêtre et libérez les références pour prévenir les fuites mémoire. Angular nettoie automatiquement ses propres watchers de portée.

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

Bases de $scope

$scope est la glu entre un contrôleur et la vue — il porte le modèle et le comportement auxquels le template se lie. Angular crée une nouvelle portée pour chaque contrôleur ; les expressions du template s'évaluent contre cette portée (et ses parents).

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()"

Héritage de portée (prototypal)

Les portées enfants héritent de la portée parente par la chaîne de prototypes de JavaScript. Lire une propriété parente fonctionne, mais affecter une primitive (ex. $scope.name = 'x') sur un enfant crée une copie locale qui masque le parent. Liez-vous à des objets (user.name) pour que les écritures remontent la chaîne.

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

$rootScope est le sommet de la hiérarchie de portées ; toute autre portée en descend. Les propriétés posées ici sont visibles dans tous les templates. Employez-le avec parcimonie pour de vraies valeurs globales (nom d'app, flag de session) — l'abus crée un couplage caché et rend l'état difficile à tracer.

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

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

Événements de portée : $emit / $broadcast / $on

$emit lance un événement qui remonte vers $rootScope ; $broadcast descend vers toutes les portées enfants. $on enregistre un écouteur et renvoie une fonction de dé-enregistrement. Passez les données en second argument. Déliez les écouteurs à $destroy pour éviter les fuites.

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) crée une portée enfant (ou isolée) ; $id est un id numérique unique ; $parent référence la portée parente. Surtout employés dans les directives. Appelez toujours $destroy() sur les portées créées manuellement pour retirer les watchers et éviter les fuites mémoire.

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

Portée isolée (aperçu des directives)

Régler scope: {} dans une directive crée une portée isolée qui n'hérite PAS prototypalement de son parent — essentiel pour les composants réutilisables. Le parent ne communique que par les liaisons déclarées (@, =, &). Cela empêche les composants de lire ou polluer par accident la portée environnante.

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

Expressions

Expressions de base

Les expressions Angular ressemblent à du JavaScript mais s'évaluent contre $scope (pas window). Elles gèrent arithmétique, concaténation de chaînes, accès aux membres et ternaires. Contrairement à JS, undefined/null s'affichent comme chaîne vide (pas de texte 'undefined'). L'opérateur de chaînage optionnel n'est PAS géré.

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

Expression vs JavaScript

Les expressions sont plus limitées que JS : pas d'instructions (if/for/while), pas de new/throw, pas de virgules, pas de définitions de fonctions, pas de bit à bit sur certaines versions. Elles s'évaluent avec $scope comme contexte et avalent silencieusement les erreurs (journalisées par $exceptionHandler). Cela garde le template sûr et déclaratif.

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

Liaison unique (::)

Le préfixe :: crée une liaison unique : Angular évalue l'expression et, une fois définie (non undefined), retire le watcher. Cela réduit drastiquement le nombre de watchers dans le cycle digest, améliorant la performance pour les données qui ne changent pas après le chargement initial.

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 et $parse

$scope.$eval(expr) parse et exécute une chaîne d'expression contre la portée. $parse compile une expression une fois en fonction getter/setter réutilisable — bien plus efficace que de réévaluer une chaîne répétément. Employez $parse dans les directives/services consommant des liaisons d'expression.

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

Filtres dans les expressions

Le pipe | applique un filtre à l'expression ; plusieurs filtres s'enchaînent de gauche à droite. Les arguments passent par deux-points. Les filtres sont commodes mais re-tournent à chaque digest — pour les grandes listes, filtrez dans le contrôleur via $filter ou une propriété calculée pour de meilleures performances.

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 et ng-cloak

Avant l'amorçage d'Angular, le navigateur montre le texte brut {{ }} (« flash de contenu non compilé »). ng-bind écrit la valeur dans le texte de l'élément seulement après l'exécution d'Angular, évitant le flash. ng-cloak combiné à une règle CSS masque les éléments jusqu'à leur compilation par Angular.

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 intégrées

ng-model (liaison bidirectionnelle)

ng-model lie les inputs de formulaire à une propriété de portée avec sync bidirectionnelle : les changements d'input mettent à jour le modèle, et les changements du modèle mettent à jour l'input. Il fonctionne sur input, textarea, select et checkbox/radio. Liez-vous toujours à une propriété pointée (user.name) pour éviter les problèmes de masquage de primitives.

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

ng-repeat clone l'élément pour chaque item d'une collection. $index, $first, $last, $middle, $even, $odd sont exposés. Employez toujours track by pour donner à Angular une identité stable afin de réemployer les nœuds DOM quand le tableau change — cela évite de tout re-rendre et corrige les erreurs de clés dupliquées.

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

ng-if insère/retire conditionnellement l'élément (et ses portées enfants) du DOM — coûteux à basculer mais bon marché quand caché. ng-show/ng-hide ne font que basculer une classe CSS, gardant l'élément dans le DOM — bon marché à basculer mais l'élément est toujours compilé. Préférez ng-if pour le contenu rarement montré.

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 et ng-style

ng-class accepte un objet (les clés vraies deviennent des classes), un tableau de noms de classes ou une chaîne. ng-style prend un objet mappant les noms de propriétés CSS aux valeurs. Tous deux se réévaluent à chaque digest, donc pour un style statique préférez un simple attribut class — réservez-les au style piloté par l'état.

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 et ng-init

ng-bind-template lie plusieurs expressions au texte d'un élément sans {{ }} bruts. ng-init évalue une expression une fois à l'initialisation de l'élément — pratique pour les démos mais déconseillé dans les vraies apps car il met la logique dans le balisage. Réglez l'état initial dans le contrôleur.

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

Employez ng-src et ng-href au lieu de src='{{ }}' pour que le navigateur n'émette pas de requête vers l'URL littérale '{{ }}' avant l'interpolation par Angular. ng-disabled bascule l'attribut disabled selon une expression — parfait pour désactiver les boutons d'envoi quand le formulaire est invalide ou qu'une requête est en vol.

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 personnalisées

Directive de base

Une directive étend le HTML. restrict: 'E' en fait un élément personnalisé (<greeting>) ; 'A' un attribut. Les directives les plus simples renvoient juste un template. Employez par défaut les restrict Element/Attribute ; les restrict Class/Comment sont rares. La meilleure pratique moderne privilégie les composants pour les directives à 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> -->

Objet de définition de directive (DDO)

L'objet de définition de directive configure tous les aspects : restrict, scope (isolée ou non), template/templateUrl, transclude, controller et la fonction link. templateUrl charge le template via $http (mis en cache) ; template est en ligne. Gardez la manipulation du DOM dans link, la logique de view-model dans le contrôleur.

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

Liaisons de portée isolée (@ = &)

@ lit l'attribut en chaîne (unidirectionnel, parent->enfant, interpolé). = crée une liaison bidirectionnelle vers l'expression du parent. & expose une fonction exécutant une expression dans la portée parente — employée pour les callbacks d'événements. Ces trois liaisons sont le cœur des composants directives réutilisables.

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>

Fonction link

La fonction link tourne après la compilation de l'élément de la directive. Employez-la pour la manipulation directe du DOM, les écouteurs d'événements (via le .on de jQuery Lite) et l'observation des attributs interpolés avec attrs.$observe. scope est la portée de la directive, element le nœud DOM enveloppé jqLite, attrs les attributs normalisés.

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

Fonction compile

La fonction compile tourne une fois sur l'élément de template original avant qu'Angular ne le clone pour ng-repeat etc. Employez-la pour les transformations au niveau template sans besoin de portée. Elle renvoie une fonction link (ou un objet pre/post link). La plupart des directives n'ont pas besoin de compile — préférez link pour le travail par instance.

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 capture le contenu de l'élément original et l'insère dans le template là où apparaît ng-transclude. Le contenu transclu garde sa portée d'origine (parente), pas la portée isolée de la directive. Cela permet à une directive enveloppeuse (panneau, modale, carte) d'envelopper du contenu arbitraire fourni par l'appelant.

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

Filtres

Filtres intégrés

Angular livre number, currency, date, lowercase, uppercase, json, limitTo, orderBy et filter. L'argument après les deux-points configure le filtre. currency accepte un symbole ISO ou un caractère personnalisé. Les filtres re-tournent à chaque digest, mettez donc en cache les calculs lourds ou calculez dans le contrôleur.

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

Filtre date

Le filtre date formate un objet Date, une chaîne ISO 8601 ou des millisecondes d'époque. Les formats prédéfinis incluent 'short','medium','long','full','shortDate','mediumDate','shortTime'. Les formats personnalisés emploient des jetons : y (année), M (mois), d (jour), H (heure), m (minute), s (seconde), EEEE (jour de semaine complet).

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

Filtre filter (recherche de tableau)

Le filtre filter sélectionne les items de tableau matchant une chaîne, un objet ou une fonction prédicat. Un objet matche les items dont les champs précisés contiennent les valeurs données. Le troisième argument true optionnel impose la correspondance exacte. Pour les grands tableaux, filtrez dans le contrôleur pour éviter de re-tourner à chaque 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>

Filtre orderBy

orderBy trie un tableau par nom de champ (préfixe '-' pour décroissant), un tableau de tels champs, ou une fonction comparateur. Il crée un nouveau tableau trié à chaque digest — pour les grandes listes, triez une fois dans le contrôleur et réemployez. Combiné à filter, il motorise les UI de recherche+tri.

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>

Filtre personnalisé

Enregistrez une factory de filtre avec app.filter. La factory renvoie une fonction qui transforme l'entrée (la valeur avant le pipe) plus des arguments supplémentaires. Les filtres doivent être purs et sans effet de bord. Ils sont injectables, on peut donc dépendre d'autres services dans la 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 dans les contrôleurs

Injectez $filter pour appliquer un filtre dans le JS (contrôleurs, services). Appelez $filter('nom')(valeur, arg1, arg2). Cela évite de re-tourner le filtre à chaque digest et permet de réemployer le résultat. Utile quand on a besoin de la valeur filtrée dans la logique, pas seulement dans la vue.

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, ...)

Bases de $http

$http effectue des requêtes XHR et renvoie une Promise. La valeur résolue est un objet de réponse avec data, status, headers et config. .then traite le succès, .catch les erreurs. Depuis Angular 1.6, les callbacks .success/.error sont retirés — employez systématiquement les .then/.catch de promise.

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

Des méthodes de commodité existent pour get/post/put/delete/patch/jsonp/head. Pour un contrôle total, passez un objet de config : params devient query string, headers règle les en-têtes de requête, responseType contrôle le parsing du corps. $http applique automatiquement les transforms par défaut (parsing JSON).

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

$location est un enveloppeur de window.location qui reste synchronisé avec l'URL du navigateur et le cycle digest. Employez-le pour lire ou changer chemin, paramètres de recherche et hash. Pour activer les jolies URLs HTML5, configurez $locationProvider.html5Mode(true) et ajoutez une balise <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 et $interval

$timeout et $interval sont des enveloppeurs conscients du digest de setTimeout/setInterval — ils déclenchent $apply pour que les mises à jour de portée soient prises en compte. Annulez-les toujours à $destroy pour prévenir les fuites et les erreurs « digest sur une portée détruite ». Passez false en 3e argument pour sauter le digest si inutile.

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 et $window / $document

$log est un fin enveloppeur de console gérant log/info/warn/error/debug et décorable pour la journalisation en production. $window et $document enveloppent les globaux — injectez-les toujours plutôt que d'appeler window/document directement, pour que les tests puissent les mocker et que votre code reste agnostique de l'environnement.

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 et événements globaux

Employez $rootScope.$broadcast pour les événements à l'échelle de l'app (connexion/déconnexion, changement de thème). Les écouteurs de toute portée le reçoivent. Pour des événements que seuls les écouteurs de $rootScope doivent entendre, $rootScope.$emit est moins coûteux (ne descend pas). Évitez l'abus d'événements globaux — préférez des services aux API explicites pour la plupart des communications.

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

factory()

factory() prend une fonction qui renvoie l'instance de service — la factory tourne une fois (singleton) et la valeur de retour est partagée. C'est la façon la plus courante de créer un service : parfaite pour encapsuler un état privé derrière une API propre. Tout ce que vous renvoyez (objet, fonction, primitive) devient le 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() instancie le constructeur avec new, on attache donc les propriétés à this. Équivalent à une factory renvoyant une nouvelle instance — les deux sont des singletons. Employez service() quand vous préférez le style constructeur/classe ; factory() quand vous devez renvoyer un objet précis ou envelopper quelque chose.

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() est la recette de plus bas niveau : elle expose un objet de phase config (avec setters) et une factory $get qui bâtit l'instance. Seuls les providers s'injectent dans les blocs config() (suffixe 'Provider'). Employez provider() quand un service a besoin d'une configuration avant instanciation ; sinon préférez 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()

Les deux enregistrent une simple valeur injectable. constant() est disponible pendant la phase config (les providers peuvent donc l'employer) et immuable. value() n'est disponible qu'en phase run. Règle empirique : constant pour la configuration dont les providers dépendent ; value pour les données d'exécution partagées ou les 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

Sous le capot, toute recette est un provider : la fonction de factory devient $get, service est une factory qui new le constructeur. Choisissez par lisibilité : factory pour la plupart des cas, service pour les classes façon constructeur, provider quand il faut de la config pré-instanciation. Les composants ne font que consommer, le choix est donc interne.

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() intercepte l'instanciation d'un service existant — $delegate est l'instance originale, qu'on peut envelopper, étendre ou remplacer. Employez-le pour les préoccupations transversales (logging, cache, rapport d'erreurs) sans toucher au service d'origine. Les décorateurs tournent paresseusement, seulement à la première injection du service.

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

Routage (ngRoute et ui-router)

Configuration de ngRoute

ngRoute est le routeur intégré (dans un fichier angular-route.js séparé). Enregistrez les routes avec .when(chemin, config) et un repli avec .otherwise(). ng-view est l'outlet où se rendent le template et le contrôleur appariés. ngRoute ne gère qu'un seul outlet et des URLs :param simples — pour des vues imbriquées, employez 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>

Paramètres de route ngRoute

$routeParams expose les segments d'URL (:id) en objet à clés chaîne — les valeurs sont toujours des chaînes, convertissez donc les nombres avec parseInt. Il se met à jour après un changement de route. Pour les liens dynamiques employez ng-href. Le préfixe hashbang par défaut est #! (depuis 1.6) ; configurez avec $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" -->

Événements de cycle de vie ngRoute

ngRoute diffuse $routeChangeStart (annulable via event.preventDefault), $routeChangeSuccess et $routeChangeError. Les arguments 'next'/'current' portent la config de route (avec les résultats de resolve). Employez-les pour les guards d'auth, les indicateurs de chargement et les titres de fil d'Ariane. Les rejets de resolve déclenchent $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);
  });
}]);

États ui-router

ui-router organise l'app en états nommés (pas des chemins d'URL). ui-sref lie par nom d'état et paramètres, et ui-view est l'outlet. Les états peuvent s'imbriquer et porter leurs propres URLs. Cela découple la navigation des URLs et gère les vues multiples/nommées — bien plus puissant que ngRoute pour les vraies apps.

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 et états imbriqués ui-router

resolve mappe des clés à des promesses ; le contrôleur n'est pas instancié tant que tout resolve n'est pas achevé. Si un resolve rejette, $stateChangeError se déclenche et l'état n'est pas atteint. Les valeurs de resolve s'injectent dans le contrôleur par leur clé. Les états enfants héritent et peuvent accéder aux resolves parents — utile pour le préchargement de données.

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

Vues nommées multiples ui-router

ui-router peut rendre plusieurs outlets ui-view nommés par état. Les clés de la map views correspondent aux noms des ui-view du template ; la clé chaîne vide vise l'outlet sans nom. Cela permet à un seul état de composer plusieurs régions (header, sidebar, main) — impossible avec le ng-view unique de 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

Formulaires et validation

Formulaire avec ng-model

Donnez au formulaire un attribut name pour exposer son état de validation sur la portée. novalidate désactive les bulles intégrées du navigateur pour qu'Angular contrôle la validation. Chaque input nommé publie son propre état (myForm.email.$valid, $dirty, $error). ng-model est requis pour que la validation suive l'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 -->

États de validation

Chaque input expose $pristine/$dirty (changé ?), $touched/$untouched (flouté ?), $valid/$invalid et $error (une map des validateurs en échec). Le formulaire les agrège : myForm.$invalid vaut true si un input est invalide. Montrez les messages seulement après $touched ou $dirty pour ne pas engueuler les utilisateurs avant qu'ils tapent.

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

Validateurs intégrés

Validateurs intégrés : required, type=email/url/number, min/max, ng-minlength/ng-maxlength, ng-pattern. Chaque validateur en échec pose une clé dans $error (ex. $error.required, $error.minlength, $error.pattern). Échappez les backslashes des regex ng-pattern dans les attributs 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}$/">

Validateur personnalisé (directive)

Ajoutez des validateurs personnalisés via une directive qui exige ngModel et enregistre une fonction sur ctrl.$validators. Renvoyez true si valide, false si invalide — l'échec apparaît dans $error sous votre clé (ici 'even'). Pour la validation asynchrone, employez ctrl.$asyncValidators qui renvoie une promesse.

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

ngMessages montre la première erreur correspondante (ou toutes avec ng-messages-multiple). Bien plus propre qu'empiler des ng-if par validateur. Extrayez les messages partagés dans un partial et incluez-le avec ng-messages-include='messages.html'. Il s'entend avec les clés de validateurs intégrés comme personnalisés.

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

Soumission de formulaire

ng-submit se déclenche à la soumission du formulaire (touche Entrée ou bouton type='submit') et seulement si les validations ng-model passent, sauf surcharge. Passez myForm.$valid au handler comme garde-fou. novalidate garantit qu'Angular (pas le navigateur) pilote la validation. Désactivez le bouton avec ng-disabled pour prévenir les doubles envois.

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

Événements (ng-click, ng-change, ...)

ng-click

ng-click évalue une expression au clic sur l'élément. $event est l'événement DOM natif, on peut donc appeler stopPropagation/preventDefault dessus — mais préférez ng-submit pour les formulaires et les directives intégrées quand possible. ng-click fonctionne sur tout élément, pas seulement les boutons.

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 se déclenche après que ng-model a mis à jour le modèle — $scope.country vaut donc déjà la nouvelle valeur. Il exige ng-model sur le même élément. Employez-le pour réagir aux changements d'input/select/checkbox (menus déroulants en cascade, filtrage en direct) sans installer votre propre écouteur de changement.

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 et famille ng-focus/blur

ng-submit traite l'envoi du formulaire. Angular expose aussi des directives d'événements pour beaucoup d'événements DOM : ng-focus, ng-blur, ng-change, ng-copy, ng-cut, ng-paste, ng-keydown/up/press, ng-mousedown/up/enter/over/leave/move et ng-dblclick. Chacune évalue une expression, avec $event disponible.

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

Événements clavier et souris

Angular fournit ng-keydown/ng-keypress/ng-keyup et ng-mousedown/up/enter/leave/over/move plus ng-dblclick. Chacune passe $event, on peut donc inspecter $event.keyCode ou $event.shiftKey. Pour des raccourcis à l'échelle de l'app, liez sur $document ou $window dans un service plutôt que de semer des handlers dans les 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>

Objet $event

$event est l'événement DOM natif transmis à votre handler. On peut lire target, les coordonnées, les touches modificatrices et appeler preventDefault/stopPropagation. Résistez à la logique lourde dans les handlers de clic — appelez plutôt une méthode du contrôleur/service. $event est disponible dans chaque directive d'événement.

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

Modificateurs d'événements (manuels)

Contrairement à Vue/Angular 2+, AngularJS n'a pas de modificateurs .stop/.prevent/.once — on appelle soi-même les méthodes d'événement dans le handler. Plus verbeux mais explicite. Pour les comportements fréquents (preventDefault auto à la soumission), ng-submit le fait déjà pour les formulaires.

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 enregistre un écouteur qui tourne à chaque changement de la valeur surveillée pendant un digest. Le premier argument peut être une expression chaîne ou une fonction ; le callback reçoit (newVal, oldVal). $watch renvoie une fonction de dé-enregistrement — appelez-la pour cesser de surveiller et éviter les fuites, surtout dans les 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 surveille un niveau d'un tableau ou objet : il se déclenche quand des items sont ajoutés/retirés/remplacés, mais ne compare PAS profondément les propriétés des items. Bien moins coûteux que le $watch profond (troisième argument true). Employez-le pour les tableaux de primitives ou quand seule l'appartenance à la liste compte, pas le contenu profond.

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 profond (troisième argument)

Passer true en troisième argument fait faire à $watch une comparaison de valeur profonde — il se déclenche quand une propriété imbriquée quelconque change. Coûteux (parcourt tout l'objet à chaque digest). Préférez surveiller un chemin précis ou employer $watchCollection. Réservez la surveillance profonde aux petits objets où elle est vraiment nécessaire.

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

Le code hors du monde d'Angular (setTimeout brut, XHR sans $http, événements jQuery, callbacks de Promise) met à jour le modèle mais Angular l'ignore — appelez $apply() pour déclencher un $digest. La forme fonction enveloppe et gère les exceptions des changements et exécute un seul digest. Dans les services Angular ($http, $timeout), $apply est déjà fait — ne doublez pas.

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 et $timeout (apply sûr)

Préférez $evalAsync ou $timeout(fn, 0) à un $apply manuel quand vous ignorez si un digest est déjà en cours — ils évitent les erreurs « digest déjà en cours ». $evalAsync regroupe dans le digest courant ; $timeout diffère au prochain tick. Employez $timeout quand vous avez aussi besoin que le DOM soit rendu.

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

Le cycle $digest expliqué

$digest est la boucle qui propage les changements de modèle à la vue : elle réévalue chaque watcher jusqu'à ce que les valeurs cessent de changer (dirty-checking), plafonnée à 10 itérations. Comme chaque watcher tourne à chaque digest, la performance dépend du nombre de watchers. Réduisez-les via la liaison unique (::), track by et le déplacement des calculs dans le contrôleur.

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

Composants (.component())

Bases de .component()

.component() est du sucre sur directive, optimisé pour les composants à template. Il vaut restrict 'E', portée isolée et controllerAs '$ctrl' — employez donc this (aliasé $ctrl) au lieu de $scope. bindings remplace scope:{...} ; '<' (entrée unidirectionnelle) est préféré à '=' pour les inputs depuis la 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>

Composant avec contrôleur et bindings

Le contrôleur d'un composant emploie this (aliasé $ctrl dans le template). bindings déclare les inputs ('<', '=') et outputs ('&'). Le unidirectionnel '<' est préféré pour les inputs. Les outputs emploient '&' — appelez-les avec un objet d'argument qui devient les locals de l'expression du parent : 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 cycle de vie du composant

Les hooks de composant d'AngularJS 1.5+ reflètent ceux d'Angular 2+ : $onInit (init), $onChanges (changements de liaisons, avec isFirstChange), $doCheck (à chaque digest), $postLink (après liaison du DOM enfant), $onDestroy (démontage). Employez-les au lieu de coller la logique dans le constructeur — ils rendent le comportement du composant explicite et testable.

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

Détail de $onChanges

$onChanges se déclenche à chaque changement de référence d'une liaison unidirectionnelle ('<'), avec un objet changes : chaque clé porte currentValue, previousValue et isFirstChange(). Il ne se déclenche PAS pour les mutations du même objet (la référence est inchangée) — employez $doCheck pour cela. Il se déclenche toujours une fois à l'init avec isFirstChange() vrai.

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 dans les composants

Réglez transclude: true et incluez ng-transclude dans le template pour laisser les appelants injecter du contenu. Dans les composants, la transclusion multi-emplacements est aussi gérée via transclude: { nomSlot: 'nomElement' }. La transclusion permet de bâtir des enveloppeurs réutilisables (panneaux, modales, cartes) dont le corps est fourni par le parent.

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>

Composant vs directive

Employez les composants pour tout ce qui rend un template — plus simples et poussant vers le modèle d'Angular 2+ (portée isolée, this/controllerAs, hooks de cycle de vie). Réservez les directives au comportement façon attribut sans template (autofocus, déclencheur de tooltip, masque d'input) et à la manipulation directe du DOM dans 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 promesses $q

Bases de $q.defer()

$q est l'implémentation de Promise d'Angular (Promises/A+). Créez avec $q.defer(), puis resolve(value) ou reject(reason). La promesse est consciente du digest : la résolution déclenche un $digest pour que la vue se mette à jour. Préférez $q à la Promise native quand vous avez besoin de l'auto-digest d'Angular ; sinon la Promise native marche aussi.

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 enveloppe une valeur simple ou une promesse non $q. $q.all attend un tableau ou objet de promesses et se résout avec la même forme de résultats. $q.reject(reason) est une façon commode de renvoyer une promesse rejetée (ex. pour une validation précoce dans une chaîne). Tout est conscient du 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'));

Enchaîner des promesses

Renvoyer une valeur depuis .then la transmet au handler suivant ; renvoyer une promesse fait attendre la chaîne. Un seul .catch traite tout rejet amont. .finally tourne au succès comme à l'échec — parfait pour masquer les loaders. Chaque handler tourne dans le digest d'Angular, les mises à jour de portée fonctionnent donc d'emblée.

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 renvoie des promesses

$http renvoie déjà une promesse $q, on peut donc enchaîner .then pour transformer la réponse (souvent extraire .data) et renvoyer une valeur plus propre. Envelopper $http dans un service donne aux appelants une API nette et centralise URL/base-url/gestion d'erreurs. Les intercepteurs sont une autre voie pour appliquer un comportement $http transversal.

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

Constructeur $q (façon ES6)

Depuis 1.6, $q gère la forme du constructeur Promise ES6 : $q(function(resolve, reject){...}). Plus concis que $q.defer() et conforme à la syntaxe de Promise native. Employez-le pour envelopper une seule API asynchrone. La promesse résultante reste consciente du digest, les mises à jour de vue se déclenchent donc automatiquement à la résolution.

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 native

La différence clé : $q déclenche un $digest à la résolution, pas la Promise native. Dans les apps AngularJS modernes tournant sur navigateurs evergreen, on peut employer la Promise native mais il faut envelopper les mises à jour du modèle dans $apply (ou $evalAsync). Pour la cohérence et la commodité, préférez $q dans le code 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

Animations (ngAnimate)

Configuration de ngAnimate

ngAnimate est un module séparé (son propre fichier JS). Une fois ajouté comme dépendance, il augmente automatiquement les directives intégrées pour qu'elles ajoutent des classes CSS pendant les transitions enter/leave/move — vous n'avez qu'à écrire du CSS. Pas de JS pour le cas courant. Sans ngAnimate, ces directives changent le DOM instantanément.

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

ngAnimate ajoute deux classes par événement : une classe de départ (ex. .ng-enter) et une classe -active (.ng-enter-active) une frame plus tard. Définissez une transition CSS sur la classe de départ et l'état final sur la classe active — Angular retire les deux à la fin de la transition. C'est l'approche d'animation la plus simple et performante.

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>

Animations keyframes CSS

On peut employer des animations CSS @keyframes au lieu de transitions — ngAnimate bascule les mêmes classes .ng-enter/.ng-leave/.ng-move, et le keyframe tourne. Avec les keyframes, une seule classe de départ suffit (pas besoin de -active) car l'animation pilote toute la séquence. Bien pour les effets rebond/ressort.

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

Les items de ng-repeat reçoivent les classes .ng-enter (nouveau), .ng-leave (retiré) et .ng-move (réordonné). Employez track by pour qu'Angular apparie les items entre les changements et anime correctement les mouvements. Les animations décalées sont possibles avec .ng-enter-stagger / .ng-leave-stagger pour retarder chaque item — parfait pour les effets de révélation de liste.

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 (animations JS)

app.animation(sélecteurCSS, factory) enregistre une animation JS pour les éléments matchant le sélecteur. Les méthodes enter/leave/move/class reçoivent l'élément et un callback done. Utile quand le CSS ne suffit pas (ex. jQuery.animate ou une bibliothèque physique). Renvoyez une fonction cancel pour le nettoyage. Les animations JS sont plus lourdes que le CSS — préférez le CSS quand possible.

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>

Désactiver les animations

Coupez les animations globalement ou par sous-arbre avec $animate.enabled, ou via la classe ng-animate-disabled. Utile pour la performance sur les grandes listes ou pour désactiver les animations pendant les tests. ng-animate-children laisse un parent faire participer ses enfants à l'animation (par défaut, une animation parent saute les animations enfants).

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

Tests (Karma et Jasmine)

Esquisse de config Karma

Karma est le runner de tests standard d'AngularJS : il lance de vrais navigateurs, charge vos scripts plus angular-mocks et rapporte les résultats Jasmine. angular-mocks fournit les helpers module() et inject() et des services mock ($httpBackend). singleRun:true sort après une exécution (CI) ; omettez-le pour le mode surveillance.

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

Bases de Jasmine

Jasmine fournit describe (suite), it (spec), beforeEach/afterEach (mise en place/démontage) et expect avec des matchers (toBe, toEqual, toContain, toBeTruthy, toThrow, etc.). xit/xdescribe sautent les specs. Les tests sont synchrones par défaut ; pour l'asynchrone, employez le callback done ou le support async/await de 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() {});
});

Tester un contrôleur

module('myApp') charge le module Angular ; inject() résout les services (souvent aliasés d'underscores en tête/queue). Créez un contrôleur avec $controller('Nom', { $scope: scope }) en passant des dépendances factices. Affirmez ensuite sur la portée. Ce pattern marche aussi pour controllerAs : passez les méthodes liées à this et inspectez l'instance renvoyée.

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

Tester un service

Injectez le service testé et $httpBackend d'angular-mocks. expectGET(url).respond(data) installe une réponse factice ; flush() résout les requêtes en attente de façon synchrone. verifyNoOutstandingExpectation() dans afterEach attrape les attentes non remplies. Cela rend les services à base de $http pleinement testables sans vrai serveur.

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

Tester une directive

Compilez un morceau de HTML avec $compile(html)(scope), puis lancez scope.$digest() pour évaluer les liaisons et lier les directives. Affirmez sur l'élément jqLite résultant (el.find, el.text, el.attr). Pour templateUrl, employez $httpBackend.expectGET pour fournir le template, puis flush avant le digest. Testez la portée isolée 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 avec $httpBackend

expectGET (et expectPOST/etc.) affirment que la requête est faite et échouent sinon ; whenGET renvoie silencieusement les données si appelé, sans tenir compte sinon. Employez expect pour les assertions « ceci devrait arriver », when pour l'installation. flush() résout les requêtes en attente dans l'ordre. Appelez toujours verifyNoOutstanding* dans afterEach pour attraper les décalages.

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

Injection de dépendances

Bases de la DI

La DI d'Angular résout les dépendances en inspectant les noms des paramètres de fonction. Ce style « implicite » est concis mais casse à la minification (les noms de paramètres se raccourcissent). Acceptable pour prototypes/démos. En production, employez un des styles d'annotation — tableau en ligne ou $inject — ou automatisez avec 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).

Annotation tableau en ligne

Le style le plus courant sûr à la minification : passez un tableau dont les éléments sont les noms de services (en chaînes), avec le constructeur en dernier. Les chaînes survivent à la minification, Angular résout donc correctement. Employez-le toujours pour tout code qui sera minifié. Pénible à maintenir à la main — ng-annotate ou les plugins babel peuvent l'ajouter automatiquement.

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

Annotation par propriété $inject

Attachez au constructeur un tableau $inject de chaînes de noms de services. Angular le lit pour résoudre les dépendances, ignorant les noms de paramètres. Cela garde la déclaration de fonction lisible et permet de réemployer le même constructeur. ng-annotate peut générer $inject automatiquement depuis les noms de paramètres pendant le 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 est le conteneur DI : .get(nom) renvoie un singleton, .annotate(fn) renvoie la liste des dépendances, .instantiate/.invoke bâti/appelle des fonctions avec leurs dépendances. Rarement nécessaire dans le code d'app, mais utile dans des scénarios dynamiques (charger des services par nom) et dans les directives personnalisées ou les resolves de routeur.

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 (au build)

ng-annotate est un outil de build qui ajoute automatiquement les annotations tableau en ligne, pour écrire une DI implicite propre et livrer du code sûr à la minification. Employez /* @ngInject */ pour lever l'ambiguïté des cas délicats. Il s'intègre à gulp, grunt, webpack, babel. Le successeur ng-annotate-patched maintient le support des chaînes d'outils modernes.

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

Mode strict DI

ng-strict-di fait lever à l'exécution l'injection de dépendances implicite (non annotée), attrapant ainsi pendant le développement le code non sûr à la minification au lieu d'en production. Gardez-le actif en dev et tests. Il impacte légèrement la performance (vérifications supplémentaires), on le retire donc souvent des builds de production.

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

Bonnes pratiques et performance

Employer controllerAs

controllerAs rend explicite le contrôleur propriétaire de chaque propriété, évite le masquage de primitives par héritage de portée et rapproche du modèle « composant » d'Angular 2+. Liez-vous à this (aliasé) plutôt qu'à $scope. Pour les composants, $ctrl est l'alias par défaut — employez-le de façon cohérente.

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

Liaison unique (::)

Préfixez une expression de :: pour en faire une liaison unique : Angular l'évalue une fois et, une fois définie, retire son watcher. Pour les données qui ne changent pas (titres, horodatages, listes statiques), cela coupe fortement le compte de watchers — le plus grand gain de performance des 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 dans ng-repeat

Sans track by, Angular emploie un $$hashKey interne pour apparier les items — quand le tableau change, il peut re-rendre et recréer le DOM d'items qui n'ont pas réellement changé, perdant l'état des enfants. track by u.id donne une identité stable pour qu'Angular réemploie les nœuds. Essentiel pour la performance des grandes listes et corrige les erreurs « 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>

Déplacer la logique vers les services

Les contrôleurs sont durs à tester et liés à $scope ; les services sont des singletons, injectables et testables unitairement. Poussez la logique métier, l'accès aux données et l'état partagé vers les services, et gardez les contrôleurs concentrés sur le câblage de la vue à ces services. Cette séparation laisse aussi plusieurs contrôleurs partager la même logique.

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) { /* ... */ } };
});

Lier une fois / réduire les watchers

Chaque {{ }} et la plupart des liaisons ajoutent un watcher qui tourne à chaque digest. Évitez les appels de fonction dans les liaisons (ils re-tournent à chaque digest même si les entrées ne changent pas) — précalculez et stockez le résultat. Combinez liaison unique (::), track by et calcul côté contrôleur pour garder le compte de watchers bas sur les grandes pages.

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>

Organisation des modules

Organisez par fonctionnalité (pas par type de fichier) pour que chaque fonctionnalité soit un module autonome avec son contrôleur, service, template, routes et tests. Le module racine de l'app ne fait que composer les modules de fonctionnalités. Cela garde le code lié ensemble, rend les fonctionnalités réutilisables entre apps et passe bien mieux à l'échelle qu'un unique module géant.

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?