You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The **`ProgressEvent`** interface represents events measuring progress of an underlying process, like an HTTP request (for an `XMLHttpRequest`, or the loading of the underlying resource of an {{HTMLElement("img")}}, {{HTMLElement("audio")}}, {{HTMLElement("video")}}, {{HTMLElement("style")}} or {{HTMLElement("link")}}).
10
+
The **`ProgressEvent`** interface represents events that measure the progress of an underlying process, like an HTTP request (e.g., an `XMLHttpRequest`, or the loading of the underlying resource of an {{HTMLElement("img")}}, {{HTMLElement("audio")}}, {{HTMLElement("video")}}, {{HTMLElement("style")}} or {{HTMLElement("link")}}).
11
11
12
12
{{InheritanceDiagram}}
13
13
@@ -21,18 +21,28 @@ The **`ProgressEvent`** interface represents events measuring progress of an und
21
21
_Also inherits properties from its parent {{domxref("Event")}}_.
- : A boolean flag indicating if the ratio between the size of the data already transmitted or processed (`loaded`), and the total size of the data (`total`), is calculable. In other words, it tells if the progress is measurable or not.
24
+
- : A boolean flag indicating if the ratio between the size of the data already transmitted or processed (`loaded`), and the total size of the data (`total`), is calculable.
25
+
In other words, it tells if the progress is measurable or not.
- : A 64-bit unsigned integer indicating the size, in bytes, of the data already transmitted or processed. The ratio can be calculated by dividing `ProgressEvent.total` by the value of this property. When downloading a resource using HTTP, this only counts the body of the HTTP message, and doesn't include headers and other overhead. Note that for compressed requests of unknown total size, `loaded` might contain the size of the compressed, or decompressed, data, depending on the browser. As of 2024, it contains the size of the compressed data in Firefox, and the size of the uncompressed data in Chrome.
27
+
- : A number indicating the size of the data already transmitted or processed.
28
+
For a `ProgressEvent` dispatched by the browser in HTTP messages, the value refers to the size, in bytes, of the message body, excluding headers and other overhead.
29
+
In compressed messages of unknown total size, `loaded` might refer to the size of the compressed or uncompressed data, depending on the browser.
30
+
As of 2024, it contains the size of the compressed data in Firefox, and the uncompressed data in Chrome.
31
+
In a `ProgressEvent` you create yourself, you can assign any numeric value to `loaded` that represents the amount of work completed relative to the `total` value.
- : A 64-bit unsigned integer indicating the total size, in bytes, of the data being transmitted or processed. When downloading a resource using HTTP, this value is taken from the `Content-Length` response header. It only counts the body of the HTTP message, and doesn't include headers and other overhead.
33
+
- : A number indicating the total size of the data being transmitted or processed.
34
+
For `ProgressEvent`s dispatched by the browser in HTTP messages, the value refers to the size, in bytes, of a resource and is derived from the `Content-Length` header.
35
+
In a `ProgressEvent` you create yourself, you may wish to normalize `total` to a value such as `100` or `1` if revealing the precise amount of bytes of a resource is a concern.
36
+
If using `1` as a total, for example, then `loaded` would be a decimal value between `0` and `1`.
29
37
30
38
## Instance methods
31
39
32
40
_Inherits methods from its parent, {{domxref("Event")}}._
33
41
34
42
## Examples
35
43
44
+
### Showing the status of a request
45
+
36
46
The following example adds a `ProgressEvent` to a new {{domxref("XMLHttpRequest")}} and uses it to display the status of the request.
37
47
38
48
```js
@@ -51,6 +61,28 @@ client.onloadend = (pe) => {
51
61
client.send();
52
62
```
53
63
64
+
### Using fractions in a ProgressEvent
65
+
66
+
The total number of bytes of a resource may reveal too much information about a resource, so a number between 0 and 1 may be used in a {{domxref("ProgressEvent.ProgressEvent", "ProgressEvent()")}} instead:
The **`ProgressEvent.loaded`** read-only property is a 64-bit unsigned integer
12
-
indicating the size, in bytes, of the data already transmitted or processed. The ratio can be calculated by dividing the value of this property by `ProgressEvent.total`.
13
-
When downloading a resource using HTTP, this only counts the body of the HTTP message, and doesn't include headers and other overhead.
11
+
The **`ProgressEvent.loaded`** read-only property is a number indicating the size of the data already transmitted or processed.
12
+
The progress ratio can be calculated by dividing the value of this property by {{domxref("ProgressEvent.total")}}.
14
13
15
-
Note that for compressed requests of unknown total size, `loaded` might contain the size of the compressed, or decompressed, data, depending on the browser. As of 2024, it contains the size of the compressed data in Firefox, and the size of the uncompressed data in Chrome.
14
+
For `ProgressEvent`s dispatched by the browser in HTTP messages, the value refers to the amount of bytes of a resource that are completed, and is derived from the `Content-Length` header.
15
+
For compressed requests of unknown total size, `loaded` might contain the size of the compressed or decompressed data, depending on the browser.
16
+
As of 2024, it contains the size of the compressed data in Firefox, and the size of the uncompressed data in Chrome.
17
+
18
+
In a `ProgressEvent` you create yourself, you can assign any numeric value to `loaded` that represents the amount of work completed relative to the `total` value.
Copy file name to clipboardExpand all lines: files/en-us/web/api/progressevent/progressevent/index.md
+36-12Lines changed: 36 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -25,27 +25,29 @@ new ProgressEvent(type, options)
25
25
-`options` {{optional_inline}}
26
26
- : An object that, _in addition of the properties defined in {{domxref("Event/Event", "Event()")}}_, can have the following properties:
27
27
-`lengthComputable` {{optional_inline}}
28
-
- : A boolean value indicating if the total work to be done, and the
29
-
amount of work already done, by the underlying process is calculable. In other words,
30
-
it tells if the progress is measurable or not. It defaults to `false`.
28
+
- : A boolean value indicating if the total work to be done, and the amount of work already done, by the underlying process is calculable.
29
+
In other words, it tells if the progress is measurable or not.
30
+
It defaults to `false`.
31
31
-`loaded` {{optional_inline}}
32
-
- : A number representing the amount of work already
33
-
performed by the underlying process. The ratio of work done can be calculated with the
34
-
property and `ProgressEvent.total`. When downloading a resource using HTTP,
35
-
this only represent the part of the content itself, not headers and other overhead. It
36
-
defaults to `0`.
32
+
- : A number representing the amount of work already performed by the underlying process.
33
+
For a `ProgressEvent` dispatched by the browser in HTTP messages, the value refers to the size, in bytes, of the message body, excluding headers and other overhead.
34
+
In a `ProgressEvent` you create yourself, you can assign any numeric value to `loaded` that represents the amount of work completed relative to the `total` value.
35
+
It defaults to `0`.
37
36
-`total` {{optional_inline}}
38
-
- : A number representing the total amount of work that the
39
-
underlying process is in the progress of performing. When downloading a resource using
40
-
HTTP, this only represent the content itself, not headers and other overhead. It
41
-
defaults to `0`.
37
+
- : A number indicating the total size of the data being transmitted or processed.
38
+
For `ProgressEvent`s dispatched by the browser in HTTP messages, the value refers to the size, in bytes, of a resource and is derived from the `Content-Length` response header.
39
+
In a `ProgressEvent` you create yourself, you may wish to normalize `total` to a value such as `100` or `1` if revealing the precise amount of bytes of a resource is a concern.
40
+
If using `1` as a total, for example, then `loaded` should be a decimal value between `0` and `1`.
41
+
It defaults to `0`.
42
42
43
43
### Return value
44
44
45
45
A new {{domxref("ProgressEvent")}} object.
46
46
47
47
## Example
48
48
49
+
### File upload
50
+
49
51
The example demonstrates how a `ProgressEvent` is built using a constructor. This is particularly useful for tracking the progress of processes like file uploads, downloads, or any long-running tasks.
The **`ProgressEvent.total`** read-only property is a 64-bit unsigned integer
12
-
indicating the total size, in bytes, of the data being transmitted or processed.
11
+
The **`ProgressEvent.total`** read-only property is a number indicating the total size of the data being transmitted or processed.
13
12
14
-
When downloading a resource using HTTP, this value is taken from the `Content-Length` response header. It only counts the body of the HTTP message, and doesn't include headers and other overhead.
13
+
For `ProgressEvent`s dispatched by the browser, the value refers to the size, in bytes, of a resource and is derived from the `Content-Length` response header.
15
14
16
-
If the event's {{domxref("ProgressEvent.lengthComputable", "lengthComputable")}}
17
-
property is `false`, this value is meaningless and should be ignored.
15
+
In a `ProgressEvent` you create yourself, this may also be the total bytes of a resource, although this can be any number.
16
+
For example, you may wish to normalize `total` to a value such as `100` or `1` if revealing the precise amount of bytes of a resource is a concern.
17
+
If using `1` as a total, then {{domxref("ProgressEvent.loaded")}} would be a decimal value between `0` and `1`.
18
+
19
+
If the event's {{domxref("ProgressEvent.lengthComputable", "lengthComputable")}} property is `false`, this value is meaningless and should be ignored.
0 commit comments