diff --git a/packages/zone.js/NON-STANDARD-APIS.md b/packages/zone.js/NON-STANDARD-APIS.md index ec9ae95b467..dde0a478fe2 100644 --- a/packages/zone.js/NON-STANDARD-APIS.md +++ b/packages/zone.js/NON-STANDARD-APIS.md @@ -1,101 +1,113 @@ # Zone.js's support for non standard apis -Zone.js patched most standard APIs such as DOM event listeners, XMLHttpRequest in Browser, EventEmitter and fs API in Node.js so they can be in zone. +Zone.js patches most standard APIs, such as DOM event listeners and `XMLHttpRequest` in the browser, as well as `EventEmitter` and the `fs` API in Node.js, so they can operate within a zone. -But there are still a lot of non-standard APIs that are not patched by default, such as MediaQuery, Notification, WebAudio and so on. This page provides updates on the current state of zone support for Angular APIs. +But there are still many non-standard APIs that are not patched by default, such as MediaQuery, Notification, and WebAudio. This page provides updates on the current state of zone support for Angular APIs. -## Currently supported non-standard Web APIs +## Currently Supported Non-Standard Web APIs -* MediaQuery -* Notification +- MediaQuery +- Notification -## Currently supported polyfills +## Currently Supported Polyfills -* webcomponents +- WebComponents Usage: -``` + +```html ``` -## Currently supported non standard node APIs +## Currently Supported Non-Standard Node.js APIs -## Currently supported non standard common APIs +- (empty) -* [Bluebird](http://bluebirdjs.com/docs/getting-started.html) Promise +## Currently Supported Non-Standard Common APIs + +- [Bluebird](http://bluebirdjs.com/docs/getting-started.html) Promise Browser Usage: -``` - - - - + + + + ``` -After those steps, window.Promise becomes Bluebird Promise and will also be zone awareness. +After completing those steps, `window.Promise` will be replaced by Bluebird `Promise` and will also be zone-aware. Angular Usage: -in polyfills.ts, import the `zone-bluebird` package. +In `polyfills.ts`, import the `zone-bluebird` package: -``` +```ts import 'zone.js'; // Included with Angular CLI. import 'zone.js/plugins/zone-bluebird'; ``` -in main.ts, patch bluebird. +In `main.ts`, patch `bluebird`: -``` -platformBrowserDynamic() - .bootstrapModule(AppModule) - .then(_ => { -import('bluebird').then(Bluebird => {const Zone = (window as any)['Zone']; Zone[Zone['__symbol__']('bluebird')](Bluebird.default);}); - }) - .catch(err => console.error(err)); +```ts +/// + +bootstrapApplication(AppComponent, appConfig) + .then(() => { + import('bluebird').then((Bluebird) => { + const bluebirdSymbol = Zone.__symbol__('bluebird'); + const patchBluebirdFn = (Zone as any)[bluebirdSymbol]; + patchBluebirdFn(Bluebird.default); + }); + }) + .catch((err) => console.error(err)); ``` -After this step, the `window.Promise` will be the Bluebird `Promise`, and the callback of `Bluebird.then` will be executed in the Angular zone. +After this step, `window.Promise` will be replaced by Bluebird's `Promise`, and the callback for `Bluebird.then` will be executed within the Angular zone. Node Sample Usage: -``` +```ts require('zone.js'); const Bluebird = require('bluebird'); require('zone.js/plugins/zone-bluebird'); -Zone[Zone['__symbol__']('bluebird')](Bluebird); -Zone.current.fork({ - name: 'bluebird' -}).run(() => { - Bluebird.resolve(1).then(r => { - console.log('result ', r, 'Zone', Zone.current.name); + +const bluebirdSymbol = Zone.__symbol__('bluebird'); +const patchBluebirdFn = (Zone as any)[bluebirdSymbol]; +patchBluebirdFn(Bluebird); + +Zone.current + .fork({ + name: 'bluebird', + }) + .run(() => { + Bluebird.resolve(1).then((result) => { + console.log('result ', result, 'Zone', Zone.current.name); + }); }); -}); ``` -In NodeJS environment, you can choose to use Bluebird Promise as global.Promise -or use ZoneAwarePromise as global.Promise. +In a Node.js environment, you can choose to use Bluebird `Promise` as `global.Promise` or `ZoneAwarePromise` as `global.Promise`. -To run the jasmine test cases of bluebird +To run the jasmine test cases of bluebird: -``` - npm install bluebird +```shell +npm install bluebird ``` -then modify test/node_tests.ts -remove the comment of the following line +Then modify `test/node_tests.ts` and remove the comment of the following line: -``` +```ts //import './extra/bluebird.spec'; ``` ## Others -* Cordova +- Cordova patch `cordova.exec` API @@ -105,7 +117,7 @@ patch `cordova.exec` API to load the patch, you should load in the following order. -``` +```html @@ -113,45 +125,48 @@ to load the patch, you should load in the following order. ## Usage -By default, those APIs' support will not be loaded in zone.js or zone-node.js, -so if you want to load those API's support, you should load those files by yourself. +By default, support for those APIs is not included in zone.js or `zone-node.js`. If you want to enable support for these APIs, you will need to load the files yourself. -For example, if you want to add MediaQuery patch, you should do like this: +For example, if you want to add a MediaQuery patch, you should do it like this: -``` - - +```html + + ``` -* rxjs +- RxJS -`zone.js` also provide a `rxjs` patch to make sure rxjs Observable/Subscription/Operator run in correct zone. -For details please refer to [pull request 843](https://github.com/angular/zone.js/pull/843). The following sample code describes the idea. +zone.js also provides an `rxjs` patch to ensure that RxJS Observables, Subscriptions, and Operators run in the correct zone. For details, please refer to [pull request 843](https://github.com/angular/zone.js/pull/843). The following sample code illustrates this concept: -``` +```ts const constructorZone = Zone.current.fork({name: 'constructor'}); const subscriptionZone = Zone.current.fork({name: 'subscription'}); const operatorZone = Zone.current.fork({name: 'operator'}); let observable; let subscriber; + constructorZone.run(() => { observable = new Observable((_subscriber) => { subscriber = _subscriber; console.log('current zone when construct observable:', Zone.current.name); // will output constructor. return () => { console.log('current zone when unsubscribe observable:', Zone.current.name); // will output constructor. - } + }; }); }); subscriptionZone.run(() => { - observable.subscribe(() => { - console.log('current zone when subscription next', Zone.current.name); // will output subscription. - }, () => { - console.log('current zone when subscription error', Zone.current.name); // will output subscription. - }, () => { - console.log('current zone when subscription complete', Zone.current.name); // will output subscription. + observable.subscribe({ + next: () => { + console.log('current zone when subscription next', Zone.current.name); // will output subscription. + }, + error: () => { + console.log('current zone when subscription error', Zone.current.name); // will output subscription. + }, + complete: () => { + console.log('current zone when subscription complete', Zone.current.name); // will output subscription. + }, }); }); @@ -176,11 +191,11 @@ is patched, so each asynchronous call will run in the correct zone. For example, in an Angular application, you can load this patch in your `app.module.ts`. -``` +```ts import 'zone.js/plugins/zone-patch-rxjs'; ``` -* electron +- electron In electron, we patched the following APIs with `zone.js` @@ -192,7 +207,7 @@ In electron, we patched the following APIs with `zone.js` add following line into `polyfill.ts` after loading zone-mix. -``` +```ts //import 'zone.js'; // originally added by angular-cli, comment it out import 'zone.js/mix'; // add zone-mix to patch both Browser and Nodejs import 'zone.js/plugins/zone-patch-electron'; // add zone-patch-electron to patch Electron native API @@ -200,35 +215,34 @@ import 'zone.js/plugins/zone-patch-electron'; // add zone-patch-electron to patc there is a sample repo [zone-electron](https://github.com/JiaLiPassion/zone-electron). -* socket.io-client +- socket.io-client user need to patch `io` themselves just like following code. -```javascript - - - - +```html + + + + ``` -please reference the sample repo [zone-socketio](https://github.com/JiaLiPassion/zone-socketio) about -detail usage. +Please refer to the sample repository [zone-socketio](https://github.com/JiaLiPassion/zone-socketio) for detailed usage. -* jsonp +- jsonp ## Usage. -provide a helper method to patch jsonp. Because jsonp has a lot of implementation, so -user need to provide the information to let json `send` and `callback` in zone. +A helper method is provided to patch JSONP. Since JSONP has many implementations, the user needs to supply the information necessary for JSON to `send` and `callback` in the zone. -there is a sample repo [zone-jsonp](https://github.com/JiaLiPassion/test-zone-js-with-jsonp) here, -sample usage is: +There is a sample repository, [zone-jsonp](https://github.com/JiaLiPassion/test-zone-js-with-jsonp), available here. The sample usage is as follows: ```javascript import 'zone.js/plugins/zone-patch-jsonp'; + Zone['__zone_symbol__jsonp']({ jsonp: getJSONP, sendFuncName: 'send', @@ -236,14 +250,14 @@ Zone['__zone_symbol__jsonp']({ failedFuncName: 'jsonpFailedCallback' }); ``` -* ResizeObserver -Currently only `Chrome 64` native support this feature. -you can add the following line into `polyfill.ts` after loading `zone.js`. +- ResizeObserver -``` +Currently, only Chrome 64 natively supports this feature. You can add the following line to `polyfill.ts` after loading zone.js: + +```ts import 'zone.js'; import 'zone.js/plugins/zone-patch-resize-observer'; ``` -there is a sample repo [zone-resize-observer](https://github.com/JiaLiPassion/zone-resize-observer) here +There is a sample repository, [zone-resize-observer](https://github.com/JiaLiPassion/zone-resize-observer), available here.