From 3c30474417d2c511b162c4568267a42c16ea2ba2 Mon Sep 17 00:00:00 2001
From: JiaLiPassion <JiaLi.Passion@gmail.com>
Date: Mon, 23 Dec 2019 08:07:54 +0900
Subject: [PATCH] docs: update zone-bluebird patch document for angular
 (#34536)

PR Close #34536
---
 packages/zone.js/NON-STANDARD-APIS.md | 67 ++++++++++++++++++---------
 1 file changed, 44 insertions(+), 23 deletions(-)

diff --git a/packages/zone.js/NON-STANDARD-APIS.md b/packages/zone.js/NON-STANDARD-APIS.md
index 8cca25bdd3..36dbd1fc0d 100644
--- a/packages/zone.js/NON-STANDARD-APIS.md
+++ b/packages/zone.js/NON-STANDARD-APIS.md
@@ -1,14 +1,13 @@
 # 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.
-  
-But there are still a lot of non standard APIs that are not patched by default, such as MediaQuery, Notification, 
- WebAudio and so on. We are adding support to those APIs, and our progress is updated here.
- 
-## Currently supported non standard Web APIs 
+
+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.
+
+## Currently supported non-standard Web APIs
 
 * MediaQuery
-* Notification 
+* Notification
 
 ## Currently supported polyfills
 
@@ -26,9 +25,9 @@ Usage:
 
 ## Currently supported non standard common APIs
 
-* bluebird promise
+* [Bluebird](http://bluebirdjs.com/docs/getting-started.html] Promise
 
-Browser Usage: 
+Browser Usage:
 
 ```
   <script src="zone.js"></script>
@@ -39,7 +38,29 @@ Browser Usage:
   </script>
 ```
 
-After those steps, window.Promise will become a ZoneAware Bluebird Promise.
+After those steps, window.Promise becomes Bluebird Promise and will also be zone awareness.
+
+Angular Usage:
+
+in polyfills.ts, import the `zone-bluebird` package.
+
+```
+import 'zone.js/dist/zone'; // Included with Angular CLI.
+import 'zone.js/dist/zone-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));
+```
+
+After this step, the `window.Promise` will be the Bluebird `Promise`, and the callback of `Bluebird.then` will be executed in the Angular zone.
 
 Node Sample Usage:
 
@@ -75,11 +96,11 @@ remove the comment of the following line
 
 ## Others
 
-* Cordova 
+* Cordova
 
 patch `cordova.exec` API
 
-`cordova.exec(success, error, service, action, args);` 
+`cordova.exec(success, error, service, action, args);`
 
 `success` and `error` will be patched with `Zone.wrap`.
 
@@ -96,12 +117,12 @@ to load the patch, you should load in the following order.
 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.
 
-For example, if you want to add MediaQuery patch, you should do like this: 
+For example, if you want to add MediaQuery patch, you should do like this:
 
 ```
-  <script src="path/zone.js"></script> 
-  <script src="path/webapis-media-query.js"></script> 
-```  
+  <script src="path/zone.js"></script>
+  <script src="path/webapis-media-query.js"></script>
+```
 
 * rxjs
 
@@ -127,17 +148,17 @@ constructorZone.run(() => {
 
 subscriptionZone.run(() => {
   observable.subscribe(() => {
-    console.log('current zone when subscription next', Zone.current.name); // will output subscription. 
+    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 error', Zone.current.name); // will output subscription.
   }, () => {
-    console.log('current zone when subscription complete', Zone.current.name); // will output subscription. 
+    console.log('current zone when subscription complete', Zone.current.name); // will output subscription.
   });
 });
 
 operatorZone.run(() => {
   observable.map(() => {
-    console.log('current zone when map operator', Zone.current.name); // will output operator. 
+    console.log('current zone when map operator', Zone.current.name); // will output operator.
   });
 });
 ```
@@ -147,8 +168,8 @@ Currently basically everything the `rxjs` API includes
 - Observable
 - Subscription
 - Subscriber
-- Operators 
-- Scheduler 
+- Operators
+- Scheduler
 
 is patched, so each asynchronous call will run in the correct zone.
 
@@ -194,7 +215,7 @@ user need to patch `io` themselves just like following code.
     </script>
 ```
 
-please reference the sample repo [zone-socketio](https://github.com/JiaLiPassion/zone-socketio) about 
+please reference the sample repo [zone-socketio](https://github.com/JiaLiPassion/zone-socketio) about
 detail usage.
 
 * jsonp
@@ -212,7 +233,7 @@ import 'zone.js/dist/zone-patch-jsonp';
 Zone['__zone_symbol__jsonp']({
   jsonp: getJSONP,
   sendFuncName: 'send',
-  successFuncName: 'jsonpSuccessCallback', 
+  successFuncName: 'jsonpSuccessCallback',
   failedFuncName: 'jsonpFailedCallback'
 });
 ```