NgZone

export class NgZone

exported from angular2/core defined in angular2/src/core/zone/ng_zone.ts (line 26)

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

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.

Example (live demo)

import {Component, View, NgZone} from 'angular2/core'; import {NgIf} from 'angular2/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> `, directives: [NgIf] }) 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(); } } }

Constructor

constructor({enableLongStackTrace}: any)

Not Yet Documented

Members

overrideOnTurnStart(onTurnStartHook: ZeroArgFunction) : void

Sets the zone hook that is called just before a browser task that is handled by Angular executes.

The hook is called once per browser task that is handled by Angular.

Setting the hook overrides any previously set hook.

onTurnStart : /* Subject */ any

Notifies subscribers just before Angular event turn starts.

Emits an event once per browser task that is handled by Angular.

overrideOnTurnDone(onTurnDoneHook: ZeroArgFunction) : void

Sets the zone hook that is called immediately after Angular zone is done processing the current task and any microtasks scheduled from that task.

This is where we typically do change-detection.

The hook is called once per browser task that is handled by Angular.

Setting the hook overrides any previously set hook.

onTurnDone

Notifies subscribers immediately after Angular zone is done processing the current turn and any microtasks scheduled from that turn.

Used by Angular as a signal to kick off change-detection.

overrideOnEventDone(onEventDoneFn: ZeroArgFunction, opt_waitForAsync?: boolean) : void

Sets the zone hook that is called immediately after the onTurnDone callback is called and any microstasks scheduled from within that callback are drained.

onEventDoneFn is executed outside Angular zone, which means that we will no longer attempt to sync the UI with any model changes that occur within this callback.

This hook is useful for validating application state (e.g. in a test).

Setting the hook overrides any previously set hook.

onEventDone

Notifies subscribers immediately after the final onTurnDone callback before ending VM event.

This event is useful for validating application state (e.g. in a test).

hasPendingMicrotasks : boolean

Whether there are any outstanding microtasks.

hasPendingTimers : boolean

Whether there are any outstanding timers.

hasPendingAsyncTasks : boolean

Whether there are any outstanding asynchronous tasks of any kind that are scheduled to run within Angular zone.

Useful as a signal of UI stability. For example, when a test reaches a point when [hasPendingAsyncTasks] is false it might be a good time to run test expectations.

overrideOnErrorHandler(errorHandler: ErrorHandlingFn)

Sets the zone hook that is called when an error is thrown in the Angular zone.

Setting the hook overrides any previously set hook.

onError

Not Yet Documented

run(fn: () => any) : any

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

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.

runOutsideAngular(fn: () => any) : any

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

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.