This is the archived documentation for Angular v6. Please visit angular.io to see documentation for the current version of Angular.

NgZone

An injectable service for executing work inside or outside of the Angular zone.

See more...

      
      class NgZone {
  static isInAngularZone(): boolean
  static assertInAngularZone(): void
  static assertNotInAngularZone(): void
  constructor(__0)
  hasPendingMicrotasks: boolean
  hasPendingMacrotasks: boolean
  isStable: boolean
  onUnstable: EventEmitter<any>
  onMicrotaskEmpty: EventEmitter<any>
  onStable: EventEmitter<any>
  onError: EventEmitter<any>
  run<T>(fn: (...args: any[]) => T, applyThis?: any, applyArgs?: any[]): T
  runTask<T>(fn: (...args: any[]) => T, applyThis?: any, applyArgs?: any[], name?: string): T
  runGuarded<T>(fn: (...args: any[]) => T, applyThis?: any, applyArgs?: any[]): T
  runOutsideAngular<T>(fn: (...args: any[]) => T): T
}
    

Description

The most common use of this service is to optimize performance when starting a work consisting of one or more asynchronous tasks that don't require UI updates or error handling to be handled by Angular. Such tasks can be kicked off via runOutsideAngular and if needed, these tasks can reenter the Angular zone via run.

Static methods

static isInAngularZone(): boolean
      
      static isInAngularZone(): boolean
    

Parameters

There are no parameters.

Returns

boolean

static assertInAngularZone(): void
      
      static assertInAngularZone(): void
    

Parameters

There are no parameters.

Returns

void

static assertNotInAngularZone(): void
      
      static assertNotInAngularZone(): void
    

Parameters

There are no parameters.

Returns

void

Constructor

constructor(__0)
      
      constructor(__0)
    

Parameters

__0

Properties

Property Description
hasPendingMicrotasks: boolean Read-only.
hasPendingMacrotasks: boolean Read-only.
isStable: boolean Read-only.

Whether there are no outstanding microtasks or macrotasks.

onUnstable: EventEmitter<any> Read-only.

Notifies when code enters Angular Zone. This gets fired first on VM Turn.

onMicrotaskEmpty: EventEmitter<any> Read-only.

Notifies when there is no more microtasks enqueued in the current VM Turn. This is a hint for Angular to do change detection, which may enqueue more microtasks. For this reason this event can fire multiple times per VM Turn.

onStable: EventEmitter<any> Read-only.

Notifies when the last onMicrotaskEmpty has run and there are no more microtasks, which implies we are about to relinquish VM turn. This event gets called just once.

onError: EventEmitter<any> Read-only.

Notifies that an error has been delivered.

Methods

Executes the fn function synchronously within the Angular zone and returns value returned by the function.

run<T>(fn: (...args: any[]) => T, applyThis?: any, applyArgs?: any[]): T
      
      run<T>(fn: (...args: any[]) => T, applyThis?: any, applyArgs?: any[]): T
    

Parameters

fn

Type: (...args: any[]) => T.

applyThis

Type: any.

Optional. Default is undefined.

applyArgs

Type: any[].

Optional. Default is undefined.

Returns

T

Running functions via run allows you to reenter Angular zone from a task that was executed outside of the Angular zone (typically started via runOutsideAngular).

Any future tasks or microtasks scheduled from within this function will continue executing from within the Angular zone.

If a synchronous error happens it will be rethrown and not reported via onError.

Executes the fn function synchronously within the Angular zone as a task and returns value returned by the function.

runTask<T>(fn: (...args: any[]) => T, applyThis?: any, applyArgs?: any[], name?: string): T
      
      runTask<T>(fn: (...args: any[]) => T, applyThis?: any, applyArgs?: any[], name?: string): T
    

Parameters

fn

Type: (...args: any[]) => T.

applyThis

Type: any.

Optional. Default is undefined.

applyArgs

Type: any[].

Optional. Default is undefined.

name

Type: string.

Optional. Default is undefined.

Returns

T

Running functions via run allows you to reenter Angular zone from a task that was executed outside of the Angular zone (typically started via runOutsideAngular).

Any future tasks or microtasks scheduled from within this function will continue executing from within the Angular zone.

If a synchronous error happens it will be rethrown and not reported via onError.

Same as run, except that synchronous errors are caught and forwarded via onError and not rethrown.

runGuarded<T>(fn: (...args: any[]) => T, applyThis?: any, applyArgs?: any[]): T
      
      runGuarded<T>(fn: (...args: any[]) => T, applyThis?: any, applyArgs?: any[]): T
    

Parameters

fn

Type: (...args: any[]) => T.

applyThis

Type: any.

Optional. Default is undefined.

applyArgs

Type: any[].

Optional. Default is undefined.

Returns

T

Executes the fn function synchronously in Angular's parent zone and returns value returned by the function.

runOutsideAngular<T>(fn: (...args: any[]) => T): T
      
      runOutsideAngular<T>(fn: (...args: any[]) => T): T
    

Parameters

fn

Type: (...args: any[]) => T.

Returns

T

Running functions via runOutsideAngular allows you to escape Angular's zone and do work that doesn't trigger Angular change-detection or is subject to Angular's error handling.

Any future tasks or microtasks scheduled from within this function will continue executing from outside of the Angular zone.

Use run to reenter the Angular zone and do work that updates the application model.

Usage notes

Example

import {Component, NgZone} from '@angular/core'; import {NgIf} from '@angular/common'; @Component({ selector: 'ng-zone-demo', template: ` <h2>Demo: NgZone</h2> <p>Progress: {{progress}}%</p> <p *ngIf="progress >= 100">Done processing {{label}} of Angular zone!</p> <button (click)="processWithinAngularZone()">Process within Angular zone</button> <button (click)="processOutsideOfAngularZone()">Process outside of Angular zone</button> `, }) export class NgZoneDemo { progress: number = 0; label: string; constructor(private _ngZone: NgZone) {} // Loop inside the Angular zone // so the UI DOES refresh after each setTimeout cycle processWithinAngularZone() { this.label = 'inside'; this.progress = 0; this._increaseProgress(() => console.log('Inside Done!')); } // Loop outside of the Angular zone // so the UI DOES NOT refresh after each setTimeout cycle processOutsideOfAngularZone() { this.label = 'outside'; this.progress = 0; this._ngZone.runOutsideAngular(() => { this._increaseProgress(() => { // reenter the Angular zone and display done this._ngZone.run(() => { console.log('Outside Done!'); }); }); }); } _increaseProgress(doneCallback: () => void) { this.progress += 1; console.log(`Current progress: ${this.progress}%`); if (this.progress < 100) { window.setTimeout(() => this._increaseProgress(doneCallback), 10); } else { doneCallback(); } } }
      
      
  1. import {Component, NgZone} from '@angular/core';
  2. import {NgIf} from '@angular/common';
  3.  
  4. @Component({
  5. selector: 'ng-zone-demo',
  6. template: `
  7. <h2>Demo: NgZone</h2>
  8.  
  9. <p>Progress: {{progress}}%</p>
  10. <p *ngIf="progress >= 100">Done processing {{label}} of Angular zone!</p>
  11.  
  12. <button (click)="processWithinAngularZone()">Process within Angular zone</button>
  13. <button (click)="processOutsideOfAngularZone()">Process outside of Angular zone</button>
  14. `,
  15. })
  16. export class NgZoneDemo {
  17. progress: number = 0;
  18. label: string;
  19.  
  20. constructor(private _ngZone: NgZone) {}
  21.  
  22. // Loop inside the Angular zone
  23. // so the UI DOES refresh after each setTimeout cycle
  24. processWithinAngularZone() {
  25. this.label = 'inside';
  26. this.progress = 0;
  27. this._increaseProgress(() => console.log('Inside Done!'));
  28. }
  29.  
  30. // Loop outside of the Angular zone
  31. // so the UI DOES NOT refresh after each setTimeout cycle
  32. processOutsideOfAngularZone() {
  33. this.label = 'outside';
  34. this.progress = 0;
  35. this._ngZone.runOutsideAngular(() => {
  36. this._increaseProgress(() => {
  37. // reenter the Angular zone and display done
  38. this._ngZone.run(() => { console.log('Outside Done!'); });
  39. });
  40. });
  41. }
  42.  
  43. _increaseProgress(doneCallback: () => void) {
  44. this.progress += 1;
  45. console.log(`Current progress: ${this.progress}%`);
  46.  
  47. if (this.progress < 100) {
  48. window.setTimeout(() => this._increaseProgress(doneCallback), 10);
  49. } else {
  50. doneCallback();
  51. }
  52. }
  53. }