Улучшить документацию Посмотреть исходный код $rootScope.Scope

Использование

$rootScope.Scope([providers], [instanceCache]);

Возвращаемое значение

Методы

• $new(isolate, parent);

  Создаёт новый дочерний scope.

  Родительский scope будет распространять событие $digest(). Scope можно удалить из иерархии scope с помощью $destroy().

  $destroy() необходимо вызвать для scope, когда требуется, чтобы scope и его дочерние scopes были окончательно отвязаны от родительского и, таким образом, перестали участвовать в обнаружении изменений модели и уведомлении слушателей, вызывая.

  Параметры

  Параметр	Тип	Описание
  isolate	boolean	Если true, то scope не наследует прототипы от родительского scope. Scope изолирован, так как он не может видеть свойства родительского scope. При создании виджетов полезно, чтобы виджет не случайно считывал состояние родителя.
  parent (необязательно)	Scope	Scope, который будет $parent нового созданного scope. По умолчанию this scope, если не указано. Это используется при создании transclude scope для правильного размещения его в иерархии scope, сохраняя при этом правильное прототипное наследование. (по умолчанию: this)

  Возвращаемое значение

  Object

  Новый созданный дочерний scope.

• $watch(watchExpression, listener, [objectEquality]);

  Регистрирует listener обратный вызов, который выполняется всякий раз, когда watchExpression изменяется.

  • watchExpression вызывается при каждом вызове $digest() и должен возвращать значение, которое будет наблюдаться. (watchExpression не должен изменять своё значение при выполнении несколько раз с одинаковым входом, потому что он может быть выполнен несколько раз $digest(). То есть, watchExpression должен быть идемпотентным.)
  • listener вызывается только тогда, когда значение от текущего watchExpression и предыдущего вызова watchExpression не равны (за исключением начального выполнения, см. ниже). Неравенство определяется по ссылке неравенства, строгому сравнению с помощью !== Javascript оператора, если objectEquality == true (см. следующий пункт)
  • При objectEquality == true, неравенство watchExpression определяется согласно angular.equals функции. Для сохранения значения объекта для последующего сравнения используется функция angular.copy. Это означает, что наблюдение за сложными объектами будет иметь неблагоприятные последствия для памяти и производительности.
  • Это не следует использовать для отслеживания изменений в объектах, которые являются или содержат File объекты из-за ограничений angular.copy.
  • Наблюдение listener может изменить модель, что может вызвать другие listener для запуска. Это достигается повторным выполнением наблюдателей до тех пор, пока не будут обнаружены изменения. Предел итераций повторного выполнения равен 10 для предотвращения тупика бесконечного цикла.

  Если вам нужно уведомление всякий раз, когда вызывается $digest, вы можете зарегистрировать watchExpression функцию без listener. (Будьте готовы к множественным вызовам вашей watchExpression, потому что она будет выполняться несколько раз в одном цикле $digest, если изменения будут обнаружены.)

  После регистрации наблюдателя в scope, listener fn вызывается асинхронно (через $evalAsync) для инициализации наблюдателя. В редких случаях это нежелательно, потому что слушатель вызывается, когда результат watchExpression не изменился. Для обнаружения этой ситуации в listener fn можно сравнить newVal и oldVal. Если эти два значения идентичны (===) , то слушатель был вызван из-за инициализации.

  Параметры

  Параметр	Тип	Описание
  watchExpression	function()string	Выражение, которое вычисляется в каждом цикле $digest. Изменение возвращаемого значения запускает вызов listener. string: Вычисляется как выражение function(scope): вызывается с текущим scope в качестве параметра.
  listener	function(newVal, oldVal, scope)	Обратный вызов, вызываемый всякий раз, когда значение watchExpression изменяется. newVal содержит текущее значение watchExpression oldVal содержит предыдущее значение watchExpression scope относится к текущему scope
  objectEquality (необязательно)	boolean	Сравнение на равенство объектов с использованием angular.equals вместо сравнения по ссылке. (по умолчанию: false)

  Возвращаемое значение

  function()

  Возвращает функцию отмены регистрации для этого слушателя.

  Пример

  // let's assume that scope was dependency injected as the $rootScope
  var scope = $rootScope;
  scope.name = 'misko';
  scope.counter = 0;
  
  expect(scope.counter).toEqual(0);
  scope.$watch('name', function(newValue, oldValue) {
    scope.counter = scope.counter + 1;
  });
  expect(scope.counter).toEqual(0);
  
  scope.$digest();
  // the listener is always called during the first $digest loop after it was registered
  expect(scope.counter).toEqual(1);
  
  scope.$digest();
  // but now it will not be called unless the value changes
  expect(scope.counter).toEqual(1);
  
  scope.name = 'adam';
  scope.$digest();
  expect(scope.counter).toEqual(2);
  
  
  
  // Using a function as a watchExpression
  var food;
  scope.foodCounter = 0;
  expect(scope.foodCounter).toEqual(0);
  scope.$watch(
    // This function returns the value being watched. It is called for each turn of the $digest loop
    function() { return food; },
    // This is the change listener, called when the value returned from the above function changes
    function(newValue, oldValue) {
      if ( newValue !== oldValue ) {
        // Only increment the counter if the value changed
        scope.foodCounter = scope.foodCounter + 1;
      }
    }
  );
  // No digest has been run so the counter will be zero
  expect(scope.foodCounter).toEqual(0);
  
  // Run the digest but since food has not changed count will still be zero
  scope.$digest();
  expect(scope.foodCounter).toEqual(0);
  
  // Update food and run digest.  Now the counter will increment
  food = 'cheeseburger';
  scope.$digest();
  expect(scope.foodCounter).toEqual(1);
  

• $watchGroup(watchExpressions, listener);

  Вариант $watch(), где он наблюдает за массивом watchExpressions. Если любое выражение в коллекции изменяется, выполняется listener.

  • Элементы в массиве watchExpressions наблюдаются с помощью стандартной $watch операции. Их возвращаемые значения проверяются на изменения при каждом вызове $digest.
  • listener вызывается всякий раз, когда любое выражение в массиве watchExpressions изменяется.

  $watchGroup более эффективен, чем наблюдение за каждым выражением по отдельности, и должен использоваться, когда слушателю не нужно знать, какое выражение изменилось. Если слушателю нужно знать, какое выражение изменилось, следует использовать $watch() или $watchCollection().

  Параметры

  Параметр	Тип	Описание
  watchExpressions	Array.<string|Function(scope)>	Массив выражений, которые будут наблюдаться по отдельности с помощью $watch()
  listener	function(newValues, oldValues, scope)	Обратный вызов, вызываемый всякий раз, когда возвращаемое значение любого выражения в watchExpressions изменяется Массив newValues содержит текущие значения watchExpressions, индексы соответствуют индексам watchExpression, а массив oldValues содержит предыдущие значения watchExpressions, индексы соответствуют индексам watchExpression. Обратите внимание, что newValues и oldValues отражают отличия в каждом отдельном выражении, а не разницу значений между каждым вызовом слушателя. Это означает, что разность между newValues и oldValues нельзя использовать для определения того, какое выражение изменилось/осталось неизменным: $scope.$watchGroup(['v1', 'v2'], function(newValues, oldValues) { console.log(newValues, oldValues); }); // newValues, oldValues initially // [undefined, undefined], [undefined, undefined] $scope.v1 = 'a'; $scope.v2 = 'a'; // ['a', 'a'], [undefined, undefined] $scope.v2 = 'b' // v1 hasn't changed since it became `'a'`, therefore its oldValue is still `undefined` // ['a', 'b'], [undefined, 'a'] scope относится к текущему scope.

  Возвращаемое значение

  function()

  Возвращает функцию отмены регистрации для всех слушателей.

• $watchCollection(obj, listener);

  Поверхностно наблюдает за свойствами объекта и вызывает обратный вызов всякий раз, когда любое из свойств изменяется (для массивов это подразумевает наблюдение за элементами массива; для карт объектов это подразумевает наблюдение за свойствами). Если изменение обнаружено, вызывается обратный вызов listener.

  • Коллекция obj наблюдается через стандартную операцию $watch и проверяется при каждом вызове $digest() на предмет добавления, удаления или перемещения элементов.
  • listener вызывается всякий раз, когда что-либо в obj изменилось. Примеры включают добавление, удаление и перемещение элементов, принадлежащих объекту или массиву.

  Параметры

  Параметр	Тип	Описание
  obj	stringfunction(scope)	Вычисляется как выражение. Значение выражения должно вычисляться до объекта или массива, который наблюдается в каждом цикле $digest. Любое поверхностное изменение в коллекции вызовет обратный вызов listener.
  listener	function(newCollection, oldCollection, scope)	Функция обратного вызова, вызываемая при обнаружении изменения. Объект newCollection — это новые изменённые данные, полученные из выражения obj Объект oldCollection — копия предыдущих данных коллекции. Из соображений производительности значение oldCollection вычисляется только в том случае, если функция listener объявляет два или более аргументов. Аргумент scope относится к текущему scope.

  Возвращаемое значение

  function()

  Возвращает функцию отмены регистрации для этого слушателя. При выполнении функции отмены регистрации внутренняя операция наблюдения прекращается.

  Пример

  $scope.names = ['igor', 'matias', 'misko', 'james'];
  $scope.dataCount = 4;
  
  $scope.$watchCollection('names', function(newNames, oldNames) {
    $scope.dataCount = newNames.length;
  });
  
  expect($scope.dataCount).toEqual(4);
  $scope.$digest();
  
  //still at 4 ... no changes
  expect($scope.dataCount).toEqual(4);
  
  $scope.names.pop();
  $scope.$digest();
  
  //now there's been a change
  expect($scope.dataCount).toEqual(3);
  

• $digest();

  Обрабатывает все наблюдатели текущего области видимости и её дочерних областей видимости. Поскольку обработчик наблюдателя может изменить модель, $digest() продолжает вызывать наблюдатели, пока больше не будут вызваны обработчики. Это может привести к бесконечной петле. Эта функция выбросит 'Maximum iteration limit exceeded.' если количество итераций превысит 10.

  Обычно вы не вызываете $digest() напрямую в контроллерах или директивах. Вместо этого вы должны вызвать $apply() (обычно из директивы), чтобы принудительно выполнить $digest().

  Если вы хотите быть уведомлены всякий раз, когда $digest() вызывается, вы можете зарегистрировать watchExpression функцию с помощью $watch() без listener.

  В тестах на единицу вы можете вызвать $digest() для имитации жизненного цикла области видимости.

  Пример

  var scope = ...;
  scope.name = 'misko';
  scope.counter = 0;
  
  expect(scope.counter).toEqual(0);
  scope.$watch('name', function(newValue, oldValue) {
    scope.counter = scope.counter + 1;
  });
  expect(scope.counter).toEqual(0);
  
  scope.$digest();
  // the listener is always called during the first $digest loop after it was registered
  expect(scope.counter).toEqual(1);
  
  scope.$digest();
  // but now it will not be called unless the value changes
  expect(scope.counter).toEqual(1);
  
  scope.name = 'adam';
  scope.$digest();
  expect(scope.counter).toEqual(2);
  

• $destroy();

  Удаляет текущую область видимости (и все её дочерние области видимости) из родительской области видимости. Удаление подразумевает, что вызовы $digest() больше не будут распространяться на текущую область видимости и её дочерние области видимости. Удаление также означает, что текущая область видимости может быть удалена сборщиком мусора.

  $destroy() обычно используется директивами, такими как ngRepeat для управления разматыванием цикла.

  Непосредственно перед уничтожением области видимости, событие $destroy транслируется в этой области видимости. Код приложения может зарегистрировать обработчик событий $destroy, который даст ему возможность выполнить необходимую очистку.

  Обратите внимание, что в AngularJS также есть событие $destroy jQuery, которое может быть использовано для очистки привязок к DOM перед удалением элемента из DOM.

• $eval([expression], [locals]);

  Выполняет expression в текущей области видимости и возвращает результат. Любые исключения в выражении передаются (не перехватываются). Это полезно при оценке выражений AngularJS.

  Параметры

  Параметр	Тип	Подробности
  expression (необязательно)	stringfunction()	Выражение AngularJS для выполнения. string: выполнить согласно правилам, определенным в выражении. function(scope): выполнить функцию с текущим scope параметром.
  locals (необязательно)	object	Объект локальных переменных, полезный для переопределения значений в области видимости.

  Возвращаемое значение

  *	Результат выполнения выражения.

  Пример

  var scope = ng.$rootScope.Scope();
  scope.a = 1;
  scope.b = 2;
  
  expect(scope.$eval('a+b')).toEqual(3);
  expect(scope.$eval(function(scope){ return scope.a + scope.b; })).toEqual(3);
  

• $evalAsync([expression], [locals]);

  Выполняет выражение в текущей области видимости в более позднее время.

  $evalAsync не гарантирует, когда expression будет выполнено, только то, что:

  • он будет выполнен после функции, которая запланировала оценку (предпочтительно до отрисовки DOM).
  • будет выполнено по крайней мере одно $цикл digest после выполнения expression.

  Любые исключения от выполнения выражения передаются сервису $exceptionHandler.

  Примечание: если эта функция вызывается вне цикла $digest, будет запланирован новый цикл $digest. Однако рекомендуется всегда вызывать код, изменяющий модель, в рамках вызова $apply. Это включает код, оцениваемый с помощью $evalAsync.

  Параметры

  Параметр	Тип	Подробности
  expression (необязательно)	stringfunction()	Выражение AngularJS для выполнения. string: выполнить согласно правилам, определенным в выражении. function(scope): выполнить функцию с текущим scope параметром.
  locals (необязательно)	object	Объект локальных переменных, полезный для переопределения значений в области видимости.

• $apply([exp]);

  $apply() используется для выполнения выражения AngularJS извне фреймворка AngularJS. (Например, из событий DOM браузера, setTimeout, XHR или сторонних библиотек). Поскольку мы вызываем фреймворк AngularJS, нам нужно выполнить правильный жизненный цикл области видимости обработки исключений, выполнения наблюдений.

  Жизненный цикл: Псевдокод $apply()

  function $apply(expr) {
    try {
      return $eval(expr);
    } catch (e) {
      $exceptionHandler(e);
    } finally {
      $root.$digest();
    }
  }
  

  Метод $apply() области видимости проходит через следующие стадии:

  1. Выражение выражение выполняется с помощью метода $eval().
  2. Любые исключения от выполнения выражения передаются сервису $exceptionHandler.
  3. Обработчики наблюдения watch запускаются сразу после выполнения выражения с помощью метода $digest().

  Параметры

  Параметр	Тип	Подробности
  exp (необязательно)	stringfunction()	Выражение AngularJS для выполнения. string: выполнить согласно правилам, определенным в выражении. function(scope): выполнить функцию с текущим scope параметром.

  Возвращаемое значение

  *	Результат выполнения выражения.

• $applyAsync([exp]);

  Запланировать вызов $apply в более позднее время. Фактическое время разницы варьируется в разных браузерах, но обычно составляет около ~10 миллисекунд.

  Это можно использовать для очереди нескольких выражений, которые должны быть оценены в одном digest.

  Параметры

  Параметр	Тип	Подробности
  exp (необязательно)	stringfunction()	Выражение AngularJS для выполнения. string: выполнить согласно правилам, определенным в выражении. function(scope): выполнить функцию с текущим scope параметром.

• $on(name, listener);

  Прослушивает события заданного типа. Смотрите $emit для обсуждения жизненного цикла события.

  Формат функции обработчика событий: function(event, args...). Объект event, переданный в обработчик, имеет следующие атрибуты:

  • targetScope - {Scope}: область видимости, на которой событие было $emit-то или $broadcast-то.
  • currentScope - {Scope}: область видимости, которая в настоящее время обрабатывает событие. После того, как событие распространилось по иерархии области видимости, это свойство устанавливается в null.
  • name - {string}: имя события.
  • stopPropagation - {function=}: вызов stopPropagation функции отменяет дальнейшее распространение события (доступно только для событий, которые были $emit-то).
  • preventDefault - {function}: вызов preventDefault устанавливает флаг defaultPrevented в true.
  • defaultPrevented - {boolean}: true, если preventDefault был вызван.

  Параметры

  Параметр	Тип	Подробности
  name	string	Имя события для прослушивания.
  listener	function(event, ...args)	Функция для вызова при возникновении события.

  Возвращаемое значение

  function()

  Возвращает функцию отмены регистрации этого обработчика.

• $emit(name, args);

  Отправляет событие name вверх по иерархии области видимости, уведомляя зарегистрированных $rootScope.Scope обработчиков событий.

  Жизненный цикл события начинается в области видимости, в которой был вызван $emit. Все обработчики, подписывающиеся на событие name в этой области видимости, получают уведомление. После этого событие проходит вверх до корневой области видимости и вызывает все зарегистрированные обработчики по пути. Событие прекратит распространение, если один из обработчиков отменит его.

  Любое исключение, сгенерированное обработчиками, будет передано сервису $exceptionHandler.

  Параметры

  Параметр	Тип	Подробности
  name	string	Имя события для отправки.
  args	*	Необязательные один или несколько аргументов, которые будут переданы обработчикам событий.

  Возвращаемое значение

  Object

  Объект события (см. $rootScope.Scope).

• $broadcast(name, args);

  Отправляет событие name вниз ко всем дочерним областям (и их дочерним) уведомляя зарегистрированных $rootScope.Scope слушателей.

  Жизненный цикл события начинается в области, на которой был вызван $broadcast. Все слушатели, слушающие событие name в этой области, уведомляются. После этого событие распространяется на все прямые и косвенные области текущей области и вызывает всех зарегистрированных слушателей по пути. Событие не может быть отменено.

  Любое исключение, испущенное слушателями, будет передано в службу $exceptionHandler.

  Параметры

  Параметр	Тип	Подробности
  name	string	Имя события для трансляции.
  args	*	Необязательные один или несколько аргументов, которые будут переданы слушателям события.

  Возвращаемое значение

  Object

  Объект события, см. $rootScope.Scope

События

• $destroy

  Транслируется, когда область и ее дочерние элементы уничтожаются.

  Обратите внимание, что в AngularJS также существует событие $destroy jQuery, которое можно использовать для очистки привязок DOM перед удалением элемента из DOM.

  Тип:

  broadcast

  Целевая область:

  уничтожаемая область

Свойства

• $id

  Уникальный идентификатор области (монотонно возрастающий), полезный для отладки.

• $parent

  Ссылка на родительскую область.

• $root

  Ссылка на корневую область.