Skip to content

AngularJS Шпаргалка

Фреймворк для фронтенда на JavaScript (Angular 1.x).

01

Начало работы

Настройка и bootstrap

AngularJS (1.x) подключается тегом script. ng-app запускает приложение, а ng-controller привязывает контроллер к поддереву DOM. Двойные фигурные скобки {{ }} — Angular-выражения, отображающие данные модели.

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 и автозапуск

ng-app с именем модуля автоматически запускает AngularJS на DOMContentLoaded. ng-strict-di требует явных аннотаций зависимостей и помогает поймать ошибки минификации ещё в разработке. На странице автозапускается только один ng-app.

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

Используйте angular.bootstrap(), когда нужно отложить старт (например, дождаться асинхронной загрузки модулей или конфигурации). Так на одной странице можно запустить несколько Angular-приложений, каждое на своём корневом элементе.

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>

Первая привязка данных

С ng-app без имени модуля Angular работает в режиме 'auto' с модулем ng по умолчанию. ng-model привязывает input к свойству 'name' неявного scope, а {{ }} отображает его в реальном времени. Это двусторонняя привязка данных в самом простом виде.

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

Основы модулей и контроллеров

angular.module('name', [deps]) создаёт модуль; angular.module('name') получает существующий. Инлайн-аннотация массивом ['$scope', function($scope){}] защищает контроллер от минификации. Всегда явно передавайте зависимости модулю при создании.

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

Модули

Создание и получение модуля

Форма с двумя аргументами angular.module(name, deps) создаёт новый модуль. Форма с одним аргументом angular.module(name) получает ранее определённый. Случайно переданный второй раз [] молча стирает все регистрации модуля.

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

Зависимости модуля

Массив зависимостей перечисляет модули, чьи провайдеры внедряются в этот модуль. Встроенные модули вроде ngRoute необязательны — их нужно явно перечислить (и подключить их скрипт). Подмодули позволяют разбить большое приложение на переиспользуемые части.

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

Блок config

config() выполняется во время регистрации провайдеров, до создания экземпляров сервисов. Единственное место, где можно внедрять и настраивать провайдеры (например, $routeProvider, $locationProvider). Используйте его для настройки маршрутов, включения HTML5-режима или регистрации валидаторов.

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

Блок run

run() выполняется после создания инжектора и конфигурации всех провайдеров — это «main» приложения. Внедряются экземпляры (не провайдеры). Обычно здесь регистрируют глобальные слушатели $rootScope для смены маршрута или проверки аутентификации.

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

Constants и Values

constant() регистрирует значение, которое можно внедрять и в блоки config() — идеально для конфигурации, нужной провайдерам. value() доступен только конструкциям фазы run (сервисам, контроллерам). Используйте constant для конфигурации, которая нужна рано.

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

Контроллеры

Базовый контроллер

Контроллеры задают начальное состояние $scope и добавляют поведение (функции). Держите контроллеры тонкими — бизнес-логика живёт в сервисах. Конструктор контроллера выполняется при каждом создании нового экземпляра (например, при каждом использовании 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;
  };
}]);

Синтаксис Controller As

controllerAs публикует экземпляр контроллера в scope под псевдонимом (main). Используйте this вместо $scope для свойств и методов. Это избегает ловушек наследования $scope и делает явным, из какого контроллера приходит свойство во вложенных представлениях.

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, безопасный при минификации

Минификаторы переименовывают параметры функций, ломая вывод зависимостей по именам в Angular. Инлайн-аннотация массивом перечисляет имена сервисов строками перед функцией, поэтому имена переживают минификацию. Всегда используйте эту аннотацию или 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) { /* ... */ });

Аннотация через $inject

Альтернатива инлайн-массиву: прикрепите к конструктору массив $inject с именами сервисов. Объявление функции остаётся читаемым и переиспользуемым. Оба стиля эквивалентны — выберите один и придерживайтесь его (или автоматизируйте 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);

Вложенные контроллеры и наследование

Дочерние scope наследуются от родительских через прототип, поэтому дочерний контроллер читает свойства родителя. Но присваивание примитива в ребёнке создаёт новое локальное свойство, затеняющее родительское, а не обновляющее его — частая ловушка. Предпочитайте объекты (точечная нотация) или controllerAs.

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

Очистка контроллера ($destroy)

Слушайте событие $destroy на $scope, чтобы выполнить очистку при разрушении scope контроллера (например, уходе со страницы). Отменяйте таймеры $interval/$timeout, снимайте слушателей window и освобождайте ссылки, чтобы избежать утечек памяти. Собственные вотчеры scope Angular чистит автоматически.

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

Основы $scope

$scope — связующее звено между контроллером и представлением: он хранит модель и поведение, к которым привязывается шаблон. Angular создаёт новый scope для каждого контроллера; выражения в шаблоне вычисляются относительно этого scope (и его родителей).

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

Наследование scope (прототипное)

Дочерние scope наследуют родительские через цепочку прототипов JavaScript. Чтение свойства родителя работает, но присваивание примитива (например, $scope.name = 'x') в ребёнке создаёт локальную копию, затеняющую родителя. Привязывайтесь к объектам (user.name), чтобы записи распространялись вверх по цепочке.

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 — вершина иерархии scope; все остальные scope происходят от него. Свойства здесь видны во всех шаблонах. Используйте экономно для действительно глобальных значений (имя приложения, флаг сессии) — злоупотребление создаёт скрытые связи и затрудняет отслеживание состояния.

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

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

События scope: $emit / $broadcast / $on

$emit порождает событие, идущее вверх до $rootScope; $broadcast — вниз по всем дочерним scope. $on регистрирует слушателя и возвращает функцию отписки. Данные передаются вторым аргументом. Отписывайтесь на $destroy, чтобы избежать утечек.

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) создаёт дочерний (или изолированный) scope; $id — уникальный числовой идентификатор; $parent ссылается на родительский scope. Всё это в основном используется внутри директив. Для вручную созданных scope всегда вызывайте $destroy(), чтобы убрать вотчеры и избежать утечек.

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

Изолированный scope (превью директив)

scope: {} в директиве создаёт изолированный scope, который НЕ наследуется от родителя прототипно — необходимо для переиспользуемых компонентов. Родитель взаимодействует только через объявленные привязки (@, =, &). Это не даёт компонентам случайно читать или загрязнять окружающий scope.

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

Выражения

Базовые выражения

Angular-выражения похожи на JavaScript, но вычисляются относительно $scope (не window). Поддерживаются арифметика, конкатенация строк, доступ к свойствам, тернарный оператор. В отличие от JS, undefined/null отображаются пустой строкой (без текста 'undefined'). Оператор опциональной цепочки НЕ поддерживается.

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

Выражения против JavaScript

Выражения ограниченнее JS: нет инструкций (if/for/while), нет new/throw, нет запятых, нет определений функций, на некоторых версиях нет побитовых операций. Они вычисляются с $scope в качестве контекста и молча глотают ошибки (логируются через $exceptionHandler). Это держит шаблон безопасным и декларативным.

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

Однократная привязка (::)

Префикс :: создаёт однократную привязку: Angular вычисляет выражение и, как только оно определено (не undefined), удаляет вотчер. Это радикально сокращает число вотчеров в digest-цикле, повышая производительность данных, не меняющихся после начальной загрузки.

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

$scope.$eval(expr) разбирает и выполняет строковое выражение относительно scope. $parse компилирует выражение один раз в переиспользуемую функцию getter/setter — намного эффективнее, чем повторно вычислять строку. Используйте $parse внутри директив/сервисов, потребляющих привязки-выражения.

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

Фильтры в выражениях

Пайп | применяет фильтр к выражению; несколько фильтров объединяются слева направо. Аргументы передаются через двоеточие. Фильтры удобны, но пересчитываются на каждом digest — для больших списков фильтруйте в контроллере через $filter или вычисляемое свойство.

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

До запуска Angular браузер показывает сырой текст {{ }} («вспышка необработанного контента»). ng-bind записывает значение в текст элемента только после запуска Angular, избегая вспышки. ng-cloak в паре с CSS-правилом скрывает элементы, пока 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

Встроенные директивы

ng-model (двусторонняя привязка)

ng-model привязывает поля формы к свойству scope с двусторонней синхронизацией: изменения input обновляют модель, изменения модели обновляют input. Работает с input, textarea, select и checkbox/radio. Всегда привязывайтесь к свойству через точку (user.name), чтобы избежать затенения примитивов.

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 клонирует элемент для каждого элемента коллекции. Доступны $index, $first, $last, $middle, $even, $odd. Всегда используйте track by, чтобы дать Angular стабильную идентичность элементов и переиспользовать DOM-узлы при изменении массива — это избегает полного перерендера и ошибок дублирующихся ключей.

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 условно вставляет/удаляет элемент (и его дочерние scope) из DOM — дорогое переключение, но дёшево, когда скрыто. ng-show/ng-hide лишь переключают CSS-класс, оставляя элемент в DOM — дёшево переключать, но элемент всегда компилируется. Предпочитайте ng-if для редко показываемого контента.

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

ng-class принимает объект (ключи с истинным значением становятся классами), массив имён классов или строку. ng-style принимает объект, сопоставляющий CSS-свойства значениям. Оба пересчитываются на каждом digest, поэтому для статичных стилей лучше обычный атрибут class — эти директивы для стилизации по состоянию.

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

ng-bind-template привязывает несколько выражений к тексту элемента без сырых {{ }}. ng-init вычисляет выражение один раз при инициализации элемента — удобно для демо, но не рекомендуется в реальных приложениях, потому что логика попадает в разметку. Начальное состояние задавайте в контроллере.

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

Используйте ng-src и ng-href вместо src='{{ }}', чтобы браузер не отправлял запрос на литеральный URL '{{ }}' до интерполяции Angular. ng-disabled переключает атрибут disabled по выражению — идеально для блокировки кнопки отправки, пока форма невалидна или запрос в полёте.

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

Пользовательские директивы

Базовая директива

Директива расширяет HTML. restrict: 'E' делает её кастомным элементом (<greeting>); 'A' — атрибутом. Простейшие директивы просто возвращают шаблон. По умолчанию используйте Element/Attribute; Class/Comment редки. Современная практика отдаёт предпочтение компонентам для шаблонных директив.

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

Объект определения директивы (DDO)

DDO настраивает все аспекты: restrict, scope (изолированный или нет), template/templateUrl, transclude, controller и функцию link. templateUrl загружает шаблон через $http (с кешированием); template инлайнится. Манипуляции с DOM — в link, логику модели представления — в контроллер.

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

Привязки изолированного scope (@ = &)

@ читает атрибут как строку (однонаправленно, родитель->потомок, с интерполяцией). = создаёт двустороннюю привязку к выражению родителя. & открывает функцию, выполняющую выражение в scope родителя — для колбэков событий. Эти три привязки — сердце переиспользуемых директив-компонентов.

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>

Функция link

Функция link выполняется после компиляции элемента директивы. Используйте её для прямых манипуляций с DOM, слушателей событий (через .on из jQuery Lite) и наблюдения за интерполируемыми атрибутами через attrs.$observe. scope — scope директивы, element — DOM-узел в обёртке jqLite, attrs — нормализованные атрибуты.

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

Функция compile

Функция compile выполняется один раз на исходном шаблоне до клонирования Angular (например, для ng-repeat). Используйте её для преобразований уровня шаблона, не требующих scope. Она возвращает функцию link (или объект pre/post link). Большинству директив compile не нужен — для работы с экземплярами предпочитайте link.

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

Трансклюзия

transclude: true захватывает содержимое исходного элемента и вставляет его в шаблон там, где стоит ng-transclude. Трансклюдированный контент сохраняет свой исходный (родительский) scope, а не изолированный scope директивы. Это позволяет директиве-обёртке (панель, модалка, карточка) оборачивать произвольный контент вызывающего.

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

Фильтры

Встроенные фильтры

Angular поставляется с number, currency, date, lowercase, uppercase, json, limitTo, orderBy и filter. Аргумент после двоеточия настраивает фильтр. currency принимает ISO-символ или свой знак. Фильтры пересчитываются на каждом digest — кешируйте тяжёлые вычисления или считайте в контроллере.

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

Фильтр date

Фильтр date форматирует объект Date, строку ISO 8601 или миллисекунды эпохи. Предопределённые форматы: 'short','medium','long','full','shortDate','mediumDate','shortTime'. Пользовательские форматы используют токены: y (год), M (месяц), d (день), H (час), m (минута), s (секунда), EEEE (полное название дня недели).

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 отбирает элементы массива по строке, объекту или функции-предикату. Объект сопоставляется с элементами, у которых указанные поля содержат заданные значения. Необязательный третий аргумент true требует точного совпадения. Для больших массивов фильтруйте в контроллере, чтобы не пересчитывать на каждом 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>

Фильтр orderBy

orderBy сортирует массив по имени поля (префикс '-' — по убыванию), массиву таких полей или функции-компаратору. Он создаёт новый отсортированный массив на каждом digest — для больших списков сортируйте один раз в контроллере и переиспользуйте. В связке с filter питает интерфейсы поиска и сортировки.

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>

Пользовательский фильтр

Регистрируйте фабрику фильтра через app.filter. Фабрика возвращает функцию, преобразующую вход (значение перед пайпом) и дополнительные аргументы. Фильтры должны быть чистыми и без побочных эффектов. Они внедряются, поэтому внутри фабрики можно зависеть от других сервисов.

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

Сервис $filter в контроллерах

Внедрите $filter, чтобы применять фильтр внутри JS (контроллеров, сервисов). Вызов: $filter('name')(value, arg1, arg2). Это избегает пересчёта фильтра на каждом digest и позволяет переиспользовать результат. Полезно, когда отфильтрованное значение нужно в логике, а не только в представлении.

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

Сервисы ($http, $location, ...)

Основы $http

$http выполняет XHR-запросы и возвращает Promise. Разрешённое значение — объект ответа с data, status, headers и config. .then обрабатывает успех, .catch — ошибки. С Angular 1.6 колбэки .success/.error удалены — используйте последовательно промисные .then/.catch.

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 с конфигурацией

Есть удобные методы get/post/put/delete/patch/jsonp/head. Для полного контроля передайте объект конфигурации: params превращаются в query-строку, headers задаёт заголовки запроса, responseType управляет разбором тела. $http автоматически применяет трансформации по умолчанию (парсинг 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 */ });

Сервис $location

$location — обёртка над window.location, синхронизированная с URL браузера и digest-циклом. Используйте её для чтения/изменения пути, параметров поиска и хеша. Для красивых HTML5-URL настройте $locationProvider.html5Mode(true) и добавьте тег <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 и $interval

$timeout и $interval — обёртки над setTimeout/setInterval, знающие о digest: они вызывают $apply, поэтому обновления scope подхватываются. Всегда отменяйте их на $destroy, чтобы избежать утечек и ошибок «digest на разрушенном scope». Третий аргумент false пропускает digest, если он не нужен.

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

$log — тонкая обёртка над console с log/info/warn/error/debug; её можно декорировать для логирования в продакшене. $window и $document оборачивают глобальные объекты — всегда внедряйте их, а не вызывайте window/document напрямую: тесты смогут подменить их, а код останется независимым от окружения.

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 и глобальные события

Используйте $rootScope.$broadcast для событий уровня приложения (вход/выход, смена темы). Его получают слушатели на любом scope. Для событий, которые должны слышать только слушатели $rootScope, $rootScope.$emit дешевле (не спускается вниз). Не злоупотребляйте глобальными событиями — для большинства коммуникаций лучше сервисы с явными API.

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

Фабрики, сервисы и провайдеры

factory()

factory() принимает функцию, возвращающую экземпляр сервиса — фабрика выполняется один раз (синглтон), и возвращаемое значение разделяется всеми. Самый распространённый способ создания сервиса: отлично инкапсулирует приватное состояние за чистым API. Всё, что вы вернёте (объект, функцию, примитив), становится сервисом.

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() создаёт конструктор через new, поэтому свойства прикрепляются к this. Эквивалентно фабрике, возвращающей новый экземпляр — оба являются синглтонами. Используйте service(), если нравится стиль конструктора/класса; factory() — когда нужно вернуть конкретный объект или обернуть что-то.

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() — самый низкоуровневый рецепт: он открывает объект фазы config (с сеттерами) и фабрику $get, создающую экземпляр. Только провайдеры внедряются в блоки config() (суффикс 'Provider'). Используйте provider(), когда сервису нужна конфигурация до создания экземпляра; иначе предпочитайте 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() против value()

Оба регистрируют простой внедряемый объект. constant() доступен в фазе config (поэтому провайдеры могут его использовать) и неизменяем. value() доступен только в фазе run. Правило: constant — для конфигурации, от которой зависят провайдеры; value — для общих runtime-данных или хелперов.

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

Под капотом каждый рецепт — провайдер: функция фабрики становится $get, service — это фабрика, создающая конструктор через new. Выбирайте по читаемости: factory для большинства случаев, service для классов в стиле конструктора, provider — когда нужна конфигурация до создания экземпляра. Компоненты лишь потребляют, так что выбор внутренний.

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() перехватывает создание существующего сервиса — $delegate это исходный экземпляр, который можно обернуть, расширить или заменить. Используйте для сквозной функциональности (логирование, кеширование, отчёты об ошибках) без правки исходного сервиса. Декораторы выполняются лениво — только при первом внедрении сервиса.

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

Маршрутизация (ngRoute и ui-router)

Настройка ngRoute

ngRoute — встроенный роутер (в отдельном файле angular-route.js). Регистрируйте маршруты через .when(path, config), запасной — через .otherwise(). ng-view — outlet, где рендерятся шаблон и контроллер совпавшего маршрута. ngRoute поддерживает только один outlet и простые URL с :param — для вложенных представлений используйте 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>

Параметры маршрута ngRoute

$routeParams открывает сегменты URL (:id) как объект со строковыми ключами — значения всегда строки, поэтому преобразуйте числа через parseInt. Обновляется после смены маршрута. Для динамических ссылок используйте ng-href. Префикс hashbang по умолчанию #! (с 1.6); настройте через $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" -->

События жизненного цикла ngRoute

ngRoute рассылает $routeChangeStart (отменяется через event.preventDefault), $routeChangeSuccess и $routeChangeError. Аргументы 'next'/'current' несут конфигурацию маршрута (с результатами resolve). Используйте их для auth-гвардов, индикаторов загрузки и заголовков хлебных крошек. Отклонённый resolve вызывает $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);
  });
}]);

Состояния ui-router

ui-router организует приложение в именованные состояния (state), а не URL-пути. ui-sref строит ссылки по имени состояния и параметрам, ui-view — outlet. Состояния могут вкладываться и иметь собственные URL. Это отделяет навигацию от URL и поддерживает несколько/именованных представлений — намного мощнее ngRoute для реальных приложений.

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 и вложенные состояния ui-router

resolve сопоставляет ключи с промисами; контроллер не создаётся, пока всё не разрешится. Если resolve отклонён, срабатывает $stateChangeError и состояние не активируется. Значения resolve внедряются в контроллер по ключам. Дочерние состояния наследуют и видят resolve родителей — удобно для предзагрузки данных.

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

Множественные именованные представления ui-router

ui-router может рендерить несколько именованных ui-view в одном состоянии. Ключи в views соответствуют именам ui-view в шаблоне; пустая строка нацеливается на безымянный outlet. Это позволяет одному состоянию собирать несколько областей (шапка, сайдбар, основная) — невозможно с единственным ng-view в 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

Формы и валидация

Форма с ng-model

Дайте форме атрибут name, чтобы её состояние валидации стало доступно в scope. novalidate отключает встроенные подсказки браузера — валидацией управляет Angular. Каждый именованный input публикует своё состояние (myForm.email.$valid, $dirty, $error). Для отслеживания поля валидацией требуется ng-model.

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

Состояния валидации

Каждый input открывает $pristine/$dirty (менялось ли), $touched/$untouched (получало ли фокус), $valid/$invalid и $error (карту сработавших валидаторов). Форма агрегирует эти состояния: myForm.$invalid истинно, если хоть один input невалиден. Показывайте сообщения только после $touched или $dirty, чтобы не ругать пользователя до ввода.

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

Встроенные валидаторы

Встроенные валидаторы: required, type=email/url/number, min/max, ng-minlength/ng-maxlength, ng-pattern. Каждый сработавший валидатор кладёт ключ в $error (например, $error.required, $error.minlength, $error.pattern). Экранируйте обратные слэши в regex для ng-pattern внутри 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}$/">

Пользовательский валидатор (директива)

Добавляйте валидаторы директивой, требующей ngModel и регистрирующей функцию в ctrl.$validators. Верните true для валидного значения, false — для невалидного; отказ появится в $error под вашим ключом (здесь 'even'). Для асинхронной валидации используйте ctrl.$asyncValidators, возвращающий промис.

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 показывает первую подходящую ошибку (или все с ng-messages-multiple). Намного чище, чем нагромождение ng-if на каждый валидатор. Общие сообщения вынесите в партиал и подключите через ng-messages-include='messages.html'. Работает и со встроенными, и с пользовательскими ключами валидаторов.

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

Отправка формы

ng-submit срабатывает при отправке формы (Enter или кнопка type='submit') и только если валидации ng-model прошли, если не переопределить. Передавайте myForm.$valid обработчику как дополнительную проверку. novalidate гарантирует, что валидацией управляет Angular, а не браузер. Блокируйте кнопку через ng-disabled от повторной отправки.

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

События (ng-click, ng-change, ...)

ng-click

ng-click вычисляет выражение при клике на элемент. $event — нативное DOM-событие, поэтому можно вызвать stopPropagation/preventDefault — хотя для форм лучше ng-submit и встроенные директивы, где возможно. ng-click работает на любом элементе, не только на кнопках.

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 срабатывает после того, как ng-model обновил модель — значит, $scope.country уже содержит новое значение. Требует ng-model на том же элементе. Используйте для реакции на изменение input/select/checkbox (каскадные выпадающие списки, живая фильтрация) без собственной подписки на 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 и семейство ng-focus/blur

ng-submit обрабатывает отправку формы. Angular также предоставляет директивы событий для многих событий DOM: ng-focus, ng-blur, ng-change, ng-copy, ng-cut, ng-paste, ng-keydown/up/press, ng-mousedown/up/enter/over/leave/move и ng-dblclick. Каждая вычисляет выражение, при этом доступна $event.

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

События клавиатуры и мыши

Angular даёт ng-keydown/ng-keypress/ng-keyup, ng-mousedown/up/enter/leave/over/move и ng-dblclick. Каждая передаёт $event, поэтому можно проверить $event.keyCode или $event.shiftKey. Для сочетаний клавиш на уровне приложения привязывайтесь к $document или $window внутри сервиса, а не рассыпайте обработчики по шаблонам.

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>

Объект $event

$event — нативное DOM-событие, переданное вашему обработчику. Можно читать target, координаты, клавиши-модификаторы и вызывать preventDefault/stopPropagation. Не размещайте тяжёлую логику в обработчиках клика — вызывайте метод контроллера/сервиса. $event доступна в каждой директиве событий.

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

Модификаторы событий (вручную)

В отличие от Vue/Angular 2+, у AngularJS нет модификаторов .stop/.prevent/.once — методы события вызываются вручную внутри обработчика. Это многословнее, но явно. Для частого поведения (автоматический preventDefault при отправке) ng-submit уже делает это для форм.

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 регистрирует слушателя, выполняющегося при каждом изменении отслеживаемого значения во время digest. Первый аргумент — строковое выражение или функция; колбэк получает (newVal, oldVal). $watch возвращает функцию отписки — вызовите её, чтобы прекратить наблюдение и избежать утечек, особенно в директивах.

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 отслеживает один уровень массива или объекта: срабатывает при добавлении/удалении/замене элементов, но НЕ сравнивает свойства элементов глубоко. Это намного дешевле глубокого $watch (третий аргумент true). Используйте для массивов примитивов или когда важно лишь членство в списке, а не глубокое содержимое.

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 (третий аргумент)

Третий аргумент true включает глубокое сравнение значений в $watch — срабатывает при изменении любого вложенного свойства. Это дорого (обход всего объекта на каждом digest). Предпочитайте отслеживание конкретного пути или $watchCollection. Глубокий вотчинг — для небольших объектов, где он действительно нужен.

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

Код вне мира Angular (сырой setTimeout, XHR без $http, события jQuery, колбэки Promise) меняет модель, но Angular об этом не знает — вызовите $apply(), чтобы запустить $digest. Функциональная форма оборачивает изменения с обработкой ошибок и выполняет один digest. Внутри Angular-сервисов ($http, $timeout) $apply уже выполнен — не применяйте дважды.

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 и $timeout (безопасный apply)

Предпочитайте $evalAsync или $timeout(fn, 0) ручному $apply, когда не уверены, не идёт ли уже digest, — они избегают ошибки «digest already in progress». $evalAsync встраивается в текущий digest; $timeout откладывает на следующий тик. Используйте $timeout, когда также нужно, чтобы DOM уже отрендерился.

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

Цикл $digest изнутри

$digest — цикл, распространяющий изменения модели в представление: он пересчитывает всех вотчеров, пока значения не перестанут меняться (dirty-checking), с потолком в 10 итераций. Поскольку каждый вотчер выполняется на каждом digest, производительность масштабируется с их числом. Сокращайте вотчеры однократной привязкой (::), track by и вычислениями в контроллере.

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

Компоненты (.component())

Основы .component()

.component() — синтаксический сахар над директивой, оптимизированный для шаблонных компонентов. По умолчанию restrict 'E', изолированный scope и controllerAs '$ctrl' — используйте this (под псевдонимом $ctrl) вместо $scope. bindings заменяет scope:{...}; '<' (однонаправленный вход) предпочтительнее '=' для входов с 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>

Компонент с контроллером и привязками

Контроллер компонента использует this (в шаблоне под псевдонимом $ctrl). bindings объявляет входы ('<', '=') и выходы ('&'). Для входов предпочтителен однонаправленный '<'. Выходы используют '&' — вызывайте с объектом аргументов, который станет локальными переменными выражения родителя: 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 }); };
  }
});

Хуки жизненного цикла компонента

Хуки компонентов AngularJS 1.5+ повторяют жизненный цикл Angular 2+: $onInit (инициализация), $onChanges (изменение привязок, с isFirstChange), $doCheck (каждый digest), $postLink (после связывания дочернего DOM), $onDestroy (завершение). Используйте их вместо навешивания логики в конструктор — поведение компонента становится явным и тестируемым.

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

Подробности $onChanges

$onChanges срабатывает при каждом изменении ссылки однонаправленной привязки ('<') и получает объект changes: каждый ключ содержит currentValue, previousValue и isFirstChange(). Он НЕ срабатывает при мутации того же объекта (ссылка не изменилась) — для этого есть $doCheck. Он всегда срабатывает один раз при инициализации с isFirstChange() истинным.

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

Трансклюзия в компонентах

Задайте transclude: true и добавьте ng-transclude в шаблон, чтобы вызывающий мог вставлять контент. В компонентах поддерживается многослотовая трансклюзия через transclude: { slotName: 'elementName' }. Трансклюзия позволяет строить переиспользуемые обёртки (панели, модалки, карточки), тело которых предоставляет родитель.

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>

Компонент против директивы

Используйте компоненты для всего, что рендерит шаблон — они проще и приближают к модели Angular 2+ (изолированный scope, this/controllerAs, хуки жизненного цикла). Директивы оставьте для атрибутного поведения без шаблона (автофокус, триггер подсказки, маска ввода) и прямых манипуляций с DOM в 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

Промис-сервис $q

Основы $q.defer()

$q — реализация Promise в Angular (Promises/A+). Создайте через $q.defer(), затем resolve(value) или reject(reason). Промис учитывает digest: разрешение вызывает $digest, и представление обновляется. Предпочитайте $q нативному Promise, когда нужна авто-digest Angular; иначе подойдёт и нативный Promise.

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 оборачивает простое значение или нативный промис. $q.all ждёт массив или объект промисов и разрешается результатами той же формы. $q.reject(reason) — удобный способ вернуть отклонённый промис (например, для ранней валидации в цепочке). Всё учитывает 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'));

Цепочки промисов

Возврат значения из .then передаёт его следующему обработчику; возврат промиса заставляет цепочку ждать. Один .catch обрабатывает любое отклонение выше по цепочке. .finally выполняется и при успехе, и при провале — идеально для скрытия индикаторов загрузки. Каждый обработчик выполняется внутри digest Angular, поэтому обновления scope работают сами.

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 возвращает промисы

$http уже возвращает промис $q, поэтому добавляйте .then для преобразования ответа (обычно извлечения .data) и возврата более чистого значения. Оборачивание $http в сервис даёт вызывающим аккуратный API и централизует обработку URL/base-url/ошибок. Интерсепторы — другой способ применить сквозное поведение $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; });

Конструктор $q (стиль ES6)

С 1.6 $q поддерживает форму конструктора ES6: $q(function(resolve, reject){...}). Лаконичнее $q.defer() и совпадает с синтаксисом нативного Promise. Используйте при обёртке одного асинхронного API. Полученный промис по-прежнему учитывает digest, поэтому обновление представления при разрешении происходит автоматически.

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 против нативного Promise

Ключевая разница: $q вызывает $digest при разрешении, нативный Promise — нет. В современных AngularJS-приложениях на актуальных браузерах можно использовать нативный Promise, но обновления модели придётся оборачивать в $apply (или $evalAsync). Для единообразия и удобства внутри Angular-кода предпочитайте $q.

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

Анимации (ngAnimate)

Настройка ngAnimate

ngAnimate — отдельный модуль (свой JS-файл). После добавления в зависимости он автоматически расширяет встроенные директивы, добавляя CSS-классы при переходах enter/leave/move — вы просто пишете CSS. В обычном случае JS не нужен. Без ngAnimate эти директивы меняют DOM мгновенно.

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

CSS-классы переходов

ngAnimate добавляет по два класса на событие: стартовый (например, .ng-enter) и -active (.ng-enter-active) кадром позже. Определите CSS-переход на стартовом классе и конечное состояние на active-классе — Angular удаляет оба по окончании перехода. Это самый простой и производительный подход к анимации.

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>

CSS-анимации keyframes

Вместо переходов можно использовать CSS-анимации @keyframes — ngAnimate переключает те же классы .ng-enter/.ng-leave/.ng-move, и keyframe выполняется. С keyframes нужен только один стартовый класс (-active не требуется), потому что всю последовательность ведёт сама анимация. Подходит для эффектов 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>

enter / leave / move в ng-repeat

Элементы ng-repeat получают классы .ng-enter (новый), .ng-leave (удалённый) и .ng-move (переставленный). Используйте track by, чтобы Angular сопоставлял элементы между изменениями и корректно анимировал перестановки. Возможны каскадные анимации через .ng-enter-stagger / .ng-leave-stagger с задержкой каждого элемента — отличный эффект появления списка.

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>

Сервис $animate (JS-анимации)

app.animation(cssSelector, factory) регистрирует JS-анимацию для элементов, подходящих под селектор. Методы enter/leave/move/class получают элемент и колбэк done. Полезно, когда CSS недостаточно (например, jQuery.animate или физическая библиотека). Возвращайте функцию cancel для очистки. JS-анимации тяжелее CSS — предпочитайте CSS, где возможно.

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>

Отключение анимаций

Отключите анимации глобально или для поддерева через $animate.enabled или класс ng-animate-disabled. Полезно для производительности больших списков или в тестах. ng-animate-children позволяет родителю включить совместную анимацию детей (по умолчанию анимация родителя пропускает анимации детей).

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

Тестирование (Karma и Jasmine)

Набросок конфигурации Karma

Karma — стандартный тест-раннер AngularJS: он запускает реальные браузеры, загружает ваши скрипты плюс angular-mocks и собирает результаты Jasmine. angular-mocks даёт хелперы module() и inject() и мок-сервисы ($httpBackend). singleRun:true завершает процесс после одного прогона (CI); не задавайте для 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

Основы Jasmine

Jasmine предоставляет describe (набор), it (спека), beforeEach/afterEach (подготовка/завершение) и expect с матчерами (toBe, toEqual, toContain, toBeTruthy, toThrow и т. д.). xit/xdescribe пропускают спеки. По умолчанию тесты синхронные; для асинхронности используйте колбэк done или поддержку async/await в 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() {});
});

Тестирование контроллера

module('myApp') загружает Angular-модуль; inject() разрешает сервисы (часто с подчёркиваниями по краям имени). Создайте контроллер через $controller('Name', { $scope: scope }) с фейковыми зависимостями. Затем проверяйте assertions по scope. Паттерн работает и для controllerAs: передайте методы с this и проверьте возвращённый экземпляр.

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

Тестирование сервиса

Внедрите тестируемый сервис и $httpBackend из angular-mocks. expectGET(url).respond(data) задаёт фейковый ответ; flush() синхронно разрешает ожидающие запросы. verifyNoOutstandingExpectation() в afterEach ловит невыполненные ожидания. Это делает сервисы на $http полностью тестируемыми без реального сервера.

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

Тестирование директивы

Скомпилируйте фрагмент HTML через $compile(html)(scope), затем вызовите scope.$digest(), чтобы вычислить привязки и связать директивы. Проверяйте результат по jqLite-элементу (el.find, el.text, el.attr). Для templateUrl используйте $httpBackend.expectGET, чтобы отдать шаблон, и flush перед digest. Изолированный scope доступен через 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');
  });
});

Мокирование $httpBackend

expectGET (и expectPOST и т. д.) утверждает, что запрос сделан, и падает, если нет; whenGET молча возвращает данные при вызове и игнорирует, если запроса не было. Используйте expect для утверждений «это должно произойти», when — для подготовки. flush() разрешает ожидающие запросы по порядку. Всегда вызывайте verifyNoOutstanding* в afterEach, чтобы поймать расхождения.

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

Внедрение зависимостей

Основы DI

DI в Angular разрешает зависимости по именам параметров функции. Такой «неявный» стиль лаконичен, но ломается при минификации (имена параметров сокращаются). Подходит для прототипов и демо. В продакшене используйте один из стилей аннотаций — инлайн-массив или $inject — или автоматизируйте 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).

Инлайн-аннотация массивом

Самый распространённый стиль, безопасный при минификации: передайте массив, элементы которого — имена сервисов (строки), а конструктор — последний. Строки переживают минификацию, поэтому Angular разрешает зависимости правильно. Используйте для любого кода, который будет минифицироваться. Вручную поддерживать утомительно — ng-annotate или babel-плагины добавят автоматически.

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

Аннотация через $inject

Прикрепите к функции-конструктору массив $inject со строками-именами сервисов. Angular читает его для разрешения зависимостей, игнорируя имена параметров. Объявление функции остаётся читаемым, а конструктор — переиспользуемым. ng-annotate может генерировать $inject автоматически из имён параметров при сборке.

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.

Сервис $injector

$injector — DI-контейнер: .get(name) возвращает синглтон, .annotate(fn) возвращает список зависимостей, .instantiate/.invoke создают/вызывают функции с их зависимостями. В коде приложения требуется редко, но полезен в динамических сценариях (загрузка сервисов по имени) и внутри кастомных директив или resolve роутера.

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 (на этапе сборки)

ng-annotate — инструмент сборки, автоматически добавляющий инлайн-аннотации массивом: вы пишете чистый неявный DI и отгружаете код, безопасный при минификации. Используйте /* @ngInject */ для неоднозначных случаев. Интегрируется с gulp, grunt, webpack, babel. Преемник ng-annotate-patched поддерживает современные инструменты.

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

Режим strict-di

ng-strict-di заставляет неявное (без аннотаций) внедрение зависимостей падать в runtime, поэтому небезопасный при минификации код ловится в разработке, а не в продакшене. Держите включённым в dev и тестах. Немного влияет на производительность (доп. проверки), поэтому обычно удаляется из продакшен-сборок.

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

Практики и производительность

Используйте controllerAs

controllerAs делает явным, какой контроллер владеет каждым свойством, избегает затенения примитивов при наследовании scope и приближает к модели «компонента» Angular 2+. Привязывайтесь к this (под псевдонимом), а не к $scope. Для компонентов псевдоним по умолчанию — $ctrl; используйте его последовательно.

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

Однократная привязка (::)

Префикс :: делает выражение однократной привязкой: Angular вычисляет его один раз и, когда значение определено, удаляет вотчер. Для неизменяющихся данных (заголовки, метки времени, статичные списки) это заметно сокращает число вотчеров — самый большой выигрыш по производительности в 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 в ng-repeat

Без track by Angular использует внутренний $$hashKey для сопоставления элементов — при изменении массива он может перерендерить и пересоздать DOM для фактически неизменившихся элементов, теряя их состояние. track by u.id даёт стабильную идентичность, и Angular переиспользует узлы. Критично для производительности больших списков и исправляет ошибки «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>

Переносите логику в сервисы

Контроллеры трудно тестировать и они привязаны к $scope; сервисы — синглтоны, внедряемые и юнит-тестируемые. Уводите бизнес-логику, доступ к данным и общее состояние в сервисы, а контроллеры держите сфокусированными на соединении представления с этими сервисами. Такое разделение также позволяет нескольким контроллерам делить одну логику.

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 Once / меньше вотчеров

Каждые {{ }} и большинство привязок добавляют вотчер, выполняющийся на каждом digest. Избегайте вызовов функций внутри привязок (они пересчитываются каждый digest, даже если входы не изменились) — вычисляйте заранее и сохраняйте результат. Совмещайте однократную привязку (::), track by и вычисления в контроллере, чтобы держать число вотчеров низким на больших страницах.

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>

Организация модулей

Организуйте по фичам (не по типам файлов), чтобы каждая фича была самодостаточным модулем со своим контроллером, сервисом, шаблоном, маршрутами и тестами. Корневой модуль приложения лишь собирает модули фич. Это держит связанный код вместе, делает фичи переиспользуемыми между приложениями и масштабируется намного лучше одного гигантского модуля.

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?