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.
`EventEmitter`, `addEventListener`, `prependEventListener`, and `on` will be patched once as EventTasks, while `removeEventListener` and `removeAllListeners` will remove those EventTasks.
Zone.js does not patch the Electron API. However, in Electron, both browser APIs and Node APIs are patched. Therefore, if you want to include Zone.js in an Electron application, please use `dist/zone-mix.js`.
`ZoneAwareError` replaces the global `Error` and adds zone information to the stack trace. It also addresses the 'this' issue. This problem can occur when creating an error without `new`: `this` will be `undefined` in strict mode and `global` in non-strict mode, potentially leading to difficult-to-detect issues.
Sometimes we don't want certain `events` to be patched by `zone.js`. We can instruct `zone.js` to leave these `events`.
This can be done through `__Zone_ignore_on_properties` and `__zone_symbol__UNPATCHED_EVENTS`, which should be available on the `window` object. It is usually recommended to declare these lists in the `<head>` element before your code is loaded. Once the zone.js code is executed and all the patches are initialized, the `__Zone_ignore_on_properties` and `__zone_symbol__UNPATCHED_EVENTS` lists will no longer be read:
```html
<head>
<script>
// Disable patching `on` properties for the following targets:
When we declare events in `__zone_symbol__UNPATCHED_EVENTS`, their callbacks will not be intercepted by zone.js, since zone.js calls the native `addEventListener` of the `EventTarget` (not the patched function):
```js
__zone_symbol__UNPATCHED_EVENTS = ['scroll'];
Zone.current.fork({name: 'child'}).run(() => {
window.addEventListener('scroll', () => {
console.log(Zone.current); // <root>
});
});
```
Note that for `__Zone_ignore_on_properties`, we need to specify object prototypes (like `Document.prototype`), with `window` being the exception. This is because `on` properties are part of the prototypes.
When the `target` is `Document.prototype` and `ignoreProperties` is a list containing `['scroll']`, then `document.onscroll` will not be patched.
Note that `__Zone_ignore_on_properties` allows for individually unpatching events, but this only applies to `on` properties. In contrast, `__zone_symbol__UNPATCHED_EVENTS` affects all events with the specified name. For example, if you're dealing with a library that uses `FileReader` and sets the `load` event using `reader.onload = () => { ... }`, you can simply use `__Zone_ignore_on_properties = [{ target: FileReader.prototype, ignoreProperties: ['load'] }]`. However, if the library adds a `load` event listener using `addEventListener`, you would need to use `__zone_symbol__UNPATCHED_EVENTS = ['load']`, which would affect other targets as well. For instance, the `load` event of `XMLHttpRequest` would also be unpatched.
