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

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

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

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

Методы

• $new(isolate, parent);

  Создает новый дочерний контекст.

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

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

  Параметры

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

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

  Object

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

• $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, если обнаружено изменение.)

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

  Параметры

  Параметр	Тип	Подробности
  watchExpression	function()string	Выражение, которое вычисляется в каждом цикле $digest. Изменение возвращаемого значения вызывает вызов listener. string: Вычисляется как выражение function(scope): вызывается с текущим scope в качестве параметра.
  listener	function(newVal, oldVal, scope)	Обратный вызов, вызываемый всякий раз, когда значение watchExpression изменяется. newVal содержит текущее значение watchExpression oldVal содержит предыдущее значение watchExpression 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 изменяется.

  Параметры

  Параметр	Тип	Подробности
  watchExpressions	Array.<string|Function(scope)>	Массив выражений, которые будут индивидуально отслеживаться с помощью $watch()
  listener	function(newValues, oldValues, scope)	Обратный вызов, вызываемый всякий раз, когда возвращаемое значение любого выражения в watchExpressions меняется. Массив newValues содержит текущие значения watchExpressions, с индексами, соответствующими индексам watchExpression, и массив oldValues содержит предыдущие значения watchExpressions, с индексами, соответствующими индексам watchExpression. 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 ссылается на текущий контекст.

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

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

• $suspend();

  Приостанавливает наблюдатели этого поддерева области видимости, чтобы они не вызывались во время обработки digest.

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

  Предупреждение

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

  Некоторые моменты, которые следует учитывать:

  • Любое внешнее событие в директиве/компоненте не вызовет обработку digest, пока родительская область видимости приостановлена — даже если обработчик событий вызовет $apply() или $rootScope.$digest().
  • Транслируемый контент существует в области видимости, которая наследует от внешнего контекста, но существует как дочерний элемент области видимости директивы. Если родительская область видимости приостановлена, то транслируемая область видимости также будет приостановлена, даже если область видимости, от которой наследует транслируемая область видимости, не приостановлена.
  • Несколько директив, пытающихся управлять состоянием приостановки области видимости, могут привести к путанице:
    • Вызов $suspend() в уже приостановленной области видимости является пустой операцией.
    • Вызов $resume() в не приостановленной области видимости является пустой операцией.
    • Если две директивы приостанавливают область видимости, а затем одна из них возобновляет область видимости, область видимости больше не будет приостановлена. Это может привести к тому, что другая директива посчитает область видимости приостановленной, когда на самом деле она не приостановлена.
  • Если родительская область видимости приостановлена, то все её потомки также будут исключены из будущих обработок digest, независимо от того, были ли они сами приостановлены. Обратите внимание, что это также относится к дочерним областям видимости изоляции.
  • Вызов $digest() непосредственно на потомке приостановленной области видимости всё равно запустит наблюдатели этой области видимости и её потомков. При обработке digest мы проверяем только, приостановлена ли текущая область видимости локально, а не проверяем, есть ли у неё приостановленный предок.
  • Вызов $resume() в области видимости, у которой есть приостановленный предок, не включит область видимости в будущие обработки digest, пока не будут возобновлены все её предки.
  • Выполнение обещаний, например, от явных отложенных обещаний $q и вызовов $http , запускает $apply() относительно $rootScope и по-прежнему будут вызывать глобальную обработку digest, даже если обещание было инициировано компонентом, который существует в приостановленной области видимости.

• $isSuspended();

  Вызовите этот метод, чтобы определить, была ли эта область видимости явно приостановлена. Он не скажет вам, был ли приостановлен предок. Чтобы определить, будет ли эта область видимости исключена из обработки digest, инициированной в $rootScope, например, вы должны проверить всех её предков:

  function isExcludedFromDigest(scope) {
  while(scope) {
    if (scope.$isSuspended()) return true;
    scope = scope.$parent;
  }
  return false;
  

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

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

  true, если текущая область видимости приостановлена.

• $resume();

  Возобновляет наблюдатели этого поддерева области видимости в случае, если она была приостановлена.

  См. $rootScope.Scope для получения информации об опасностях использования этого подхода.

• $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 cycle после выполнения 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. Обработчики наблюдателей запускаются немедленно после выполнения выражения с помощью метода $digest().

  Параметры

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

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

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

• $applyAsync([exp]);

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

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

  Параметры

  Параметр	Тип	Подробности
  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 также есть событие jQuery $destroy , которое можно использовать для очистки связей DOM перед удалением элемента из DOM.

  Тип:

  broadcast

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

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

Свойства

• $id

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

• $parent

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

• $root

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