Skip to content

Commit 8ce190b

Browse files
arturovtAndrewKushnir
arturovt
authored and
AndrewKushnir
committed
docs(zone.js): update docs to enable beforeunload (angular#57881)
In this commit, we update the documentation to reflect the property that allows enabling the default browser `beforeunload` handling, which was added in a previous commit. Additionally, some cosmetic grammar changes have been made in this documentation, as the previous text had some issues. Closes angular#52256 PR Close angular#57881
1 parent 84b6896 commit 8ce190b

File tree

1 file changed

+120
-118
lines changed

1 file changed

+120
-118
lines changed

‎packages/zone.js/MODULE.md‎

Lines changed: 120 additions & 118 deletions
Original file line numberDiff line numberDiff line change
@@ -4,145 +4,147 @@ Starting from zone.js v0.8.9, you can choose which web API modules you want to p
44
the below samples show how to disable some modules. You just need to define a few global variables
55
before loading zone.js.
66

7-
```
8-
<script>
9-
__Zone_disable_Error = true; // Zone will not patch Error
10-
__Zone_disable_on_property = true; // Zone will not patch onProperty such as button.onclick
11-
__Zone_disable_geolocation = true; // Zone will not patch geolocation API
12-
__Zone_disable_toString = true; // Zone will not patch Function.prototype.toString
13-
__Zone_disable_blocking = true; // Zone will not patch alert/prompt/confirm
14-
__Zone_disable_PromiseRejectionEvent = true; // Zone will not patch PromiseRejectionEventHandler
15-
</script>
16-
<script src="../bundles/zone.umd.js"></script>
7+
```html
8+
<script>
9+
__Zone_disable_Error = true; // Zone will not patch Error
10+
__Zone_disable_on_property = true; // Zone will not patch `on` properties such as button.onclick
11+
__Zone_disable_geolocation = true; // Zone will not patch geolocation API
12+
__Zone_disable_toString = true; // Zone will not patch Function.prototype.toString
13+
__Zone_disable_blocking = true; // Zone will not patch alert/prompt/confirm
14+
__Zone_disable_PromiseRejectionEvent = true; // Zone will not patch PromiseRejectionEventHandler
15+
</script>
16+
<script src="../bundles/zone.umd.js"></script>
1717
```
1818

1919
Below is the full list of currently supported modules.
2020

21-
- Common
22-
23-
|Module Name|Behavior with zone.js patch|How to disable|
24-
|--|--|--|
25-
|Error|stack frames will have the Zone's name information, (By default, Error patch will not be loaded by zone.js)|__Zone_disable_Error = true|
26-
|toString|Function.toString will be patched to return native version of toString|__Zone_disable_toString = true|
27-
|ZoneAwarePromise|Promise.then will be patched as Zone aware MicroTask|__Zone_disable_ZoneAwarePromise = true|
28-
|bluebird|Bluebird will use Zone.scheduleMicroTask as async scheduler. (By default, bluebird patch will not be loaded by zone.js)|__Zone_disable_bluebird = true|
29-
30-
- Browser
31-
32-
|Module Name|Behavior with zone.js patch|How to disable|
33-
|--|--|--|
34-
|on_property|target.onProp will become zone aware target.addEventListener(prop)|__Zone_disable_on_property = true|
35-
|timers|setTimeout/setInterval/setImmediate will be patched as Zone MacroTask|__Zone_disable_timers = true|
36-
|requestAnimationFrame|requestAnimationFrame will be patched as Zone MacroTask|__Zone_disable_requestAnimationFrame = true|
37-
|blocking|alert/prompt/confirm will be patched as Zone.run|__Zone_disable_blocking = true|
38-
|EventTarget|target.addEventListener will be patched as Zone aware EventTask|__Zone_disable_EventTarget = true|
39-
|MutationObserver|MutationObserver will be patched as Zone aware operation|__Zone_disable_MutationObserver = true|
40-
|IntersectionObserver|Intersection will be patched as Zone aware operation|__Zone_disable_IntersectionObserver = true|
41-
|FileReader|FileReader will be patched as Zone aware operation|__Zone_disable_FileReader = true|
42-
|canvas|HTMLCanvasElement.toBlob will be patched as Zone aware operation|__Zone_disable_canvas = true|
43-
|IE BrowserTools check|in IE, browser tool will not use zone patched eventListener|__Zone_disable_IE_check = true|
44-
|CrossContext check|in webdriver, enable check event listener is cross context|__Zone_enable_cross_context_check = true|
45-
|XHR|XMLHttpRequest will be patched as Zone aware MacroTask|__Zone_disable_XHR = true|
46-
|geolocation|navigator.geolocation's prototype will be patched as Zone.run|__Zone_disable_geolocation = true|
47-
|PromiseRejectionEvent|PromiseRejectEvent will fire when ZoneAwarePromise has unhandled error|__Zone_disable_PromiseRejectionEvent = true|
48-
|mediaQuery|mediaQuery addListener API will be patched as Zone aware EventTask. (By default, mediaQuery patch will not be loaded by zone.js) |__Zone_disable_mediaQuery = true|
49-
|notification|notification onProperties API will be patched as Zone aware EventTask. (By default, notification patch will not be loaded by zone.js) |__Zone_disable_notification = true|
50-
|MessagePort|MessagePort onProperties APIs will be patched as Zone aware EventTask. (By default, MessagePort patch will not be loaded by zone.js) |__Zone_disable_MessagePort = true|
51-
52-
- NodeJS
53-
54-
|Module Name|Behavior with zone.js patch|How to disable|
55-
|--|--|--|
56-
|node_timers|NodeJS patch timer|__Zone_disable_node_timers = true|
57-
|fs|NodeJS patch fs function as macroTask|__Zone_disable_fs = true|
58-
|EventEmitter|NodeJS patch EventEmitter as Zone aware EventTask|__Zone_disable_EventEmitter = true|
59-
|nextTick|NodeJS patch process.nextTick as microTask|__Zone_disable_nextTick = true|
60-
|handleUnhandledPromiseRejection|NodeJS handle unhandledPromiseRejection from ZoneAwarePromise|__Zone_disable_handleUnhandledPromiseRejection = true|
61-
|crypto|NodeJS patch crypto function as macroTask|__Zone_disable_crypto = true|
62-
63-
- Test Framework
64-
65-
|Module Name|Behavior with zone.js patch|How to disable|
66-
|--|--|--|
67-
|Jasmine|Jasmine APIs patch|__Zone_disable_jasmine = true|
68-
|Mocha|Mocha APIs patch|__Zone_disable_mocha = true|
69-
70-
- on_property
71-
72-
You can also disable specific on_properties by setting `__Zone_ignore_on_properties` as follows: for example,
73-
if you want to disable `window.onmessage` and `HTMLElement.prototype.onclick` from zone.js patching,
74-
you can do like this.
75-
21+
### Common
22+
23+
| Module Name | Behavior with zone.js patch | How to disable |
24+
| ---------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
25+
| Error | stack frames will have the Zone's name information, (By default, Error patch will not be loaded by zone.js) | \_\_Zone_disable_Error = true |
26+
| toString | Function.toString will be patched to return native version of toString | \_\_Zone_disable_toString = true |
27+
| ZoneAwarePromise | Promise.then will be patched as Zone aware MicroTask | \_\_Zone_disable_ZoneAwarePromise = true |
28+
| bluebird | Bluebird will use Zone.scheduleMicroTask as async scheduler. (By default, bluebird patch will not be loaded by zone.js) | \_\_Zone_disable_bluebird = true |
29+
30+
### Browser
31+
32+
| Module Name | Behavior with zone.js patch | How to disable |
33+
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
34+
| on_property | target.onProp will become zone aware target.addEventListener(prop) | \_\_Zone_disable_on_property = true |
35+
| timers | setTimeout/setInterval/setImmediate will be patched as Zone MacroTask | \_\_Zone_disable_timers = true |
36+
| requestAnimationFrame | requestAnimationFrame will be patched as Zone MacroTask | \_\_Zone_disable_requestAnimationFrame = true |
37+
| blocking | alert/prompt/confirm will be patched as Zone.run | \_\_Zone_disable_blocking = true |
38+
| EventTarget | target.addEventListener will be patched as Zone aware EventTask | \_\_Zone_disable_EventTarget = true |
39+
| MutationObserver | MutationObserver will be patched as Zone aware operation | \_\_Zone_disable_MutationObserver = true |
40+
| IntersectionObserver | Intersection will be patched as Zone aware operation | \_\_Zone_disable_IntersectionObserver = true |
41+
| FileReader | FileReader will be patched as Zone aware operation | \_\_Zone_disable_FileReader = true |
42+
| canvas | HTMLCanvasElement.toBlob will be patched as Zone aware operation | \_\_Zone_disable_canvas = true |
43+
| IE BrowserTools check | in IE, browser tool will not use zone patched eventListener | \_\_Zone_disable_IE_check = true |
44+
| CrossContext check | in webdriver, enable check event listener is cross context | \_\_Zone_enable_cross_context_check = true |
45+
| `beforeunload` | enable the default `beforeunload` handling behavior, where event handlers return strings to prompt the user | **zone_symbol**enable_beforeunload = true |
46+
| XHR | XMLHttpRequest will be patched as Zone aware MacroTask | \_\_Zone_disable_XHR = true |
47+
| geolocation | navigator.geolocation's prototype will be patched as Zone.run | \_\_Zone_disable_geolocation = true |
48+
| PromiseRejectionEvent | PromiseRejectEvent will fire when ZoneAwarePromise has unhandled error | \_\_Zone_disable_PromiseRejectionEvent = true |
49+
| mediaQuery | mediaQuery addListener API will be patched as Zone aware EventTask. (By default, mediaQuery patch will not be loaded by zone.js) | \_\_Zone_disable_mediaQuery = true |
50+
| notification | notification onProperties API will be patched as Zone aware EventTask. (By default, notification patch will not be loaded by zone.js) | \_\_Zone_disable_notification = true |
51+
| MessagePort | MessagePort onProperties APIs will be patched as Zone aware EventTask. (By default, MessagePort patch will not be loaded by zone.js) | \_\_Zone_disable_MessagePort = true |
52+
53+
### Node.js
54+
55+
| Module Name | Behavior with zone.js patch | How to disable |
56+
| ------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------- |
57+
| node_timers | NodeJS patch timer | \_\_Zone_disable_node_timers = true |
58+
| fs | NodeJS patch fs function as macroTask | \_\_Zone_disable_fs = true |
59+
| EventEmitter | NodeJS patch EventEmitter as Zone aware EventTask | \_\_Zone_disable_EventEmitter = true |
60+
| nextTick | NodeJS patch process.nextTick as microTask | \_\_Zone_disable_nextTick = true |
61+
| handleUnhandledPromiseRejection | NodeJS handle unhandledPromiseRejection from ZoneAwarePromise | \_\_Zone_disable_handleUnhandledPromiseRejection = true |
62+
| crypto | NodeJS patch crypto function as macroTask | \_\_Zone_disable_crypto = true |
63+
64+
### Test Framework
65+
66+
| Module Name | Behavior with zone.js patch | How to disable |
67+
| ----------- | --------------------------- | ------------------------------- |
68+
| Jasmine | Jasmine APIs patch | \_\_Zone_disable_jasmine = true |
69+
| Mocha | Mocha APIs patch | \_\_Zone_disable_mocha = true |
70+
71+
### `on` properties
72+
73+
You can also disable specific `on` properties by setting `__Zone_ignore_on_properties` as follows. For example, if you want to disable `window.onmessage` and `HTMLElement.prototype.onclick` from zone.js patching, you can do so like this:
74+
75+
```html
76+
<script>
77+
__Zone_ignore_on_properties = [
78+
{
79+
target: window,
80+
ignoreProperties: ['message'],
81+
},
82+
{
83+
target: HTMLElement.prototype,
84+
ignoreProperties: ['click'],
85+
},
86+
];
87+
</script>
88+
<script src="../bundles/zone.umd.js"></script>
7689
```
77-
<script>
78-
__Zone_ignore_on_properties = [
79-
{
80-
target: window,
81-
ignoreProperties: ['message']
82-
}, {
83-
target: HTMLElement.prototype,
84-
ignoreProperties: ['click']
85-
}
86-
];
87-
</script>
88-
<script src="../bundles/zone.umd.js"></script>
90+
91+
Excluding `on` properties from being patched means that callbacks will always be invoked within the root context, regardless of where the `on` callback has been set. Even if `onclick` is set within a child zone, the callback will be called inside the root zone:
92+
93+
```ts
94+
Zone.current.fork({ name: 'child' }).run(() => {
95+
document.body.onclick = () => {
96+
console.log(Zone.current); // <root>
97+
};
98+
});
8999
```
90100

91-
- Error
101+
You can find more information on adding unpatched events via `addEventListener`, please refer to [UnpatchedEvents](./STANDARD-APIS.md#unpatchedevents).
102+
103+
### Error
92104

93-
By default, `zone.js/plugins/zone-error` will not be loaded for performance concern.
94-
This package will provide following functionality.
105+
By default, `zone.js/plugins/zone-error` will not be loaded for performance reasons.
106+
This package provides the following functionality:
95107

96-
1. Error inherit: handle `extend Error` issue.
97-
```
98-
class MyError extends Error {}
99-
const myError = new MyError();
100-
console.log('is MyError instanceof Error', (myError instanceof Error));
101-
```
108+
1. **Error Inheritance:** Handle the `extend Error` issue:
102109

103-
without `zone-error` patch, the example above will output `false`, with the patch, the result will be `true`.
110+
```ts
111+
class MyError extends Error {}
112+
const myError = new MyError();
113+
console.log('is MyError instanceof Error', (myError instanceof Error));
114+
```
104115

105-
2. ZoneJsInternalStackFrames: remove zone.js stack from `stackTrace`, and add `zone` information. Without this patch, a lot of `zone.js` invocation stack will be shown
106-
in stack frames.
116+
Without the `zone-error` patch, the example above will output `false`. With the patch, the result will be `true`.
107117

108-
```
109-
at zone.run (polyfill.bundle.js: 3424)
110-
at zoneDelegate.invokeTask (polyfill.bundle.js: 3424)
111-
at zoneDelegate.runTask (polyfill.bundle.js: 3424)
112-
at zone.drainMicroTaskQueue (polyfill.bundle.js: 3424)
113-
at a.b.c (vendor.bundle.js: 12345 <angular>)
114-
at d.e.f (main.bundle.js: 23456)
115-
```
118+
2. **ZoneJsInternalStackFrames:** Remove the zone.js stack from `stackTrace` and add `zone` information. Without this patch, many `zone.js` invocation stacks will be displayed in the stack frames.
116119

117-
with this patch, those zone frames will be removed,
118-
and the zone information `<angular>/<root>` will be added
120+
```
121+
at zone.run (polyfill.bundle.js: 3424)
122+
at zoneDelegate.invokeTask (polyfill.bundle.js: 3424)
123+
at zoneDelegate.runTask (polyfill.bundle.js: 3424)
124+
at zone.drainMicroTaskQueue (polyfill.bundle.js: 3424)
125+
at a.b.c (vendor.bundle.js: 12345 <angular>)
126+
at d.e.f (main.bundle.js: 23456)
127+
```
119128

120-
```
121-
at a.b.c (vendor.bundle.js: 12345 <angular>)
122-
at d.e.f (main.bundle.js: 23456 <root>)
123-
```
129+
With this patch, those zone frames will be removed, and the zone information `<angular>/<root>` will be added.
124130

125-
The second feature will slow down the `Error` performance, so `zone.js` provide a flag to let you be able to control the behavior.
126-
The flag is `__Zone_Error_ZoneJsInternalStackFrames_policy`. And the available options is:
131+
```
132+
at a.b.c (vendor.bundle.js: 12345 <angular>)
133+
at d.e.f (main.bundle.js: 23456 <root>)
134+
```
127135

128-
1. default: this is the default one, if you load `zone.js/plugins/zone-error` without
129-
setting the flag, `default` will be used, and `ZoneJsInternalStackFrames` will be available
130-
when `new Error()`, you can get a `error.stack` which is `zone stack free`. But this
131-
will slow down `new Error()` a little bit.
136+
The second feature may slow down `Error` performance, so `zone.js` provides a flag that allows you to control this behavior.
137+
The flag is `__Zone_Error_ZoneJsInternalStackFrames_policy`. The available options are:
132138

133-
2. disable: this will disable `ZoneJsInternalStackFrames` feature, and if you load
134-
`zone.js/plugins/zone-error`, you will only get a `wrapped Error` which can handle
135-
`Error inherit` issue.
139+
1. **default:** This is the default setting. If you load `zone.js/plugins/zone-error` without setting the flag, `default` will be used. In this case, `ZoneJsInternalStackFrames` will be available when using `new Error()`, allowing you to obtain an `error.stack` that is zone-stack-free. However, this may slightly slow down the performance of new `Error()`.
136140

137-
3. lazy: this is a feature to let you be able to get `ZoneJsInternalStackFrames` feature,
138-
but not impact performance. But as a trade off, you can't get the `zone free stack
139-
frames` by access `error.stack`. You can only get it by access `error.zoneAwareStack`.
141+
2. **disable:** This option will disable the `ZoneJsInternalStackFrames` feature. If you load `zone.js/plugins/zone-error`, you will only receive a wrapped `Error`, which can handle the `Error` inheritance issue.
140142

143+
3. **lazy:** This feature allows you to access `ZoneJsInternalStackFrames` without impacting performance. However, as a trade-off, you won't be able to obtain the zone-free stack frames via `error.stack`. You can only access them through `error.zoneAwareStack`.
141144

142-
- Angular(2+)
145+
### Angular
143146

144-
Angular uses zone.js to manage async operations and decide when to perform change detection. Thus, in Angular,
145-
the following APIs should be patched, otherwise Angular may not work as expected.
147+
Angular uses zone.js to manage asynchronous operations and determine when to perform change detection. Therefore, in Angular, the following APIs should be patched; otherwise, Angular may not work as expected:
146148

147149
1. ZoneAwarePromise
148150
2. timer

0 commit comments

Comments
 (0)