Elgato_dark/angular
1
0
Fork 0
mirror of https://github.com/angular/angular synced 2026-05-24 09:28:37 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs(zone.js): update NON-STANDARD-APIS.md (#58098)

Browse source 
This commit makes some grammatical changes to the existing documentation.

PR Close #58098
This commit is contained in:
arturovt 2024-10-06 14:21:05 +03:00 committed by Miles Malerba
parent 19b6564cb2
commit 48d899f423
1 changed files with 102 additions and 88 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

190
packages/zone.js/NON-STANDARD-APIS.md
View file

@ -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
<script src="webcomponents-lite.js"></script>
<script src="node_modules/zone.js/bundles/zone.umd.js"></script>
<script src="node_modules/zone.js/bundles/webapis-shadydom.umd.js"></script>
```
## 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:
```
<script src="zone.js"></script>
<script src="bluebird.js"></script>
<script src="zone-bluebird.js"></script>
<script>
```html
<script src="zone.js"></script>
<script src="bluebird.js"></script>
<script src="zone-bluebird.js"></script>
<script>
Zone[Zone['__symbol__']('bluebird')](Promise);
</script>
</script>
```
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
/// <reference types="zone.js" />
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
<script src="zone.js"></script>
<script src="cordova.js"></script>
<script src="zone-patch-cordova.js"></script>
@ -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:
```
<script src="path/zone.js"></script>
<script src="path/webapis-media-query.js"></script>
```html
<script src="path/zone.js"></script>
<script src="path/webapis-media-query.js"></script>
```
* 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
<script src="socket.io-client/dist/socket.io.js"></script>
<script src="zone.js/bundles/zone.umd.js"></script>
<script src="zone.js/bundles/zone-patch-socket-io.js"></script>
<script>
// patch io here
Zone[Zone.__symbol__('socketio')](io);
</script>
```html
<script src="socket.io-client/dist/socket.io.js"></script>
<script src="zone.js/bundles/zone.umd.js"></script>
<script src="zone.js/bundles/zone-patch-socket-io.js"></script>
<script>
// patch io here
const patchSocketIOFn = Zone[Zone.__symbol__('socketio')];
patchSocketIOFn(io);
</script>
```
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.