diff --git a/files/en-us/web/api/progressevent/index.md b/files/en-us/web/api/progressevent/index.md index 29bf7e6dfc10f69..5ac43749221bd6b 100644 --- a/files/en-us/web/api/progressevent/index.md +++ b/files/en-us/web/api/progressevent/index.md @@ -7,7 +7,7 @@ browser-compat: api.ProgressEvent {{APIRef("XMLHttpRequest API")}}{{AvailableInWorkers}} -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")}}). +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")}}). {{InheritanceDiagram}} @@ -21,11 +21,19 @@ The **`ProgressEvent`** interface represents events measuring progress of an und _Also inherits properties from its parent {{domxref("Event")}}_. - {{domxref("ProgressEvent.lengthComputable")}} {{ReadOnlyInline}} - - : 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. + - : 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. - {{domxref("ProgressEvent.loaded")}} {{ReadOnlyInline}} - - : 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. + - : A number indicating the size of the data already transmitted or processed. + 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. + In compressed messages of unknown total size, `loaded` might refer to the size of the compressed or uncompressed data, depending on the browser. + As of 2024, it contains the size of the compressed data in Firefox, and the uncompressed data in Chrome. + 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. - {{domxref("ProgressEvent.total")}} {{ReadOnlyInline}} - - : 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. + - : A number indicating the total size of the data being transmitted or processed. + 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. + 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. + If using `1` as a total, for example, then `loaded` would be a decimal value between `0` and `1`. ## Instance methods @@ -33,6 +41,8 @@ _Inherits methods from its parent, {{domxref("Event")}}._ ## Examples +### Showing the status of a request + The following example adds a `ProgressEvent` to a new {{domxref("XMLHttpRequest")}} and uses it to display the status of the request. ```js @@ -51,6 +61,28 @@ client.onloadend = (pe) => { client.send(); ``` +### Using fractions in a ProgressEvent + +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: + +```js +function updateProgress(loaded, total) { + const progressEvent = new ProgressEvent("progress", { + lengthComputable: true, + loaded, + total, + }); + + document.dispatchEvent(progressEvent); +} + +document.addEventListener("progress", (event) => { + console.log(`Progress: ${event.loaded}/${event.total}`); +}); + +updateProgress(0.123456, 1); +``` + ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/progressevent/loaded/index.md b/files/en-us/web/api/progressevent/loaded/index.md index 14b3cb763466a6c..960aa6dbdece527 100644 --- a/files/en-us/web/api/progressevent/loaded/index.md +++ b/files/en-us/web/api/progressevent/loaded/index.md @@ -8,11 +8,14 @@ browser-compat: api.ProgressEvent.loaded {{APIRef("XMLHttpRequest API")}}{{AvailableInWorkers}} -The **`ProgressEvent.loaded`** read-only property is a 64-bit unsigned integer -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`. -When downloading a resource using HTTP, this only counts the body of the HTTP message, and doesn't include headers and other overhead. +The **`ProgressEvent.loaded`** read-only property is a number indicating the size of the data already transmitted or processed. +The progress ratio can be calculated by dividing the value of this property by {{domxref("ProgressEvent.total")}}. -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. +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. +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. + +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. ## Value diff --git a/files/en-us/web/api/progressevent/progressevent/index.md b/files/en-us/web/api/progressevent/progressevent/index.md index 12e05335198a061..5dac6f085614f02 100644 --- a/files/en-us/web/api/progressevent/progressevent/index.md +++ b/files/en-us/web/api/progressevent/progressevent/index.md @@ -25,20 +25,20 @@ new ProgressEvent(type, options) - `options` {{optional_inline}} - : An object that, _in addition of the properties defined in {{domxref("Event/Event", "Event()")}}_, can have the following properties: - `lengthComputable` {{optional_inline}} - - : A boolean value indicating if the total work to be done, and the - amount of work already done, by the underlying process is calculable. In other words, - it tells if the progress is measurable or not. It defaults to `false`. + - : A boolean value indicating if the total work to be done, and the amount of work already done, by the underlying process is calculable. + In other words, it tells if the progress is measurable or not. + It defaults to `false`. - `loaded` {{optional_inline}} - - : A number representing the amount of work already - performed by the underlying process. The ratio of work done can be calculated with the - property and `ProgressEvent.total`. When downloading a resource using HTTP, - this only represent the part of the content itself, not headers and other overhead. It - defaults to `0`. + - : A number representing the amount of work already performed by the underlying process. + 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. + 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. + It defaults to `0`. - `total` {{optional_inline}} - - : A number representing the total amount of work that the - underlying process is in the progress of performing. When downloading a resource using - HTTP, this only represent the content itself, not headers and other overhead. It - defaults to `0`. + - : A number indicating the total size of the data being transmitted or processed. + 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. + 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. + If using `1` as a total, for example, then `loaded` should be a decimal value between `0` and `1`. + It defaults to `0`. ### Return value @@ -46,6 +46,8 @@ A new {{domxref("ProgressEvent")}} object. ## Example +### File upload + 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. ```js @@ -66,6 +68,28 @@ document.addEventListener("progress", (event) => { updateProgress(50, 100); ``` +### Using fractions in a ProgressEvent + +The total number of bytes of a resource may reveal too much information about a download, so a number between 0 and 1 may be used instead: + +```js +function updateProgress(loaded, total) { + const progressEvent = new ProgressEvent("progress", { + lengthComputable: true, + loaded, + total, + }); + + document.dispatchEvent(progressEvent); +} + +document.addEventListener("progress", (event) => { + console.log(`Progress: ${event.loaded}/${event.total}`); +}); + +updateProgress(0.123456, 1); +``` + ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/progressevent/total/index.md b/files/en-us/web/api/progressevent/total/index.md index f0673f9afbf850f..ea612b075de9a43 100644 --- a/files/en-us/web/api/progressevent/total/index.md +++ b/files/en-us/web/api/progressevent/total/index.md @@ -8,17 +8,19 @@ browser-compat: api.ProgressEvent.total {{APIRef("XMLHttpRequest API")}}{{AvailableInWorkers}} -The **`ProgressEvent.total`** read-only property is a 64-bit unsigned integer -indicating the total size, in bytes, of the data being transmitted or processed. +The **`ProgressEvent.total`** read-only property is a number indicating the total size 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. +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. -If the event's {{domxref("ProgressEvent.lengthComputable", "lengthComputable")}} -property is `false`, this value is meaningless and should be ignored. +In a `ProgressEvent` you create yourself, this may also be the total bytes of a resource, although this can be any number. +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. +If using `1` as a total, then {{domxref("ProgressEvent.loaded")}} would be a decimal value between `0` and `1`. + +If the event's {{domxref("ProgressEvent.lengthComputable", "lengthComputable")}} property is `false`, this value is meaningless and should be ignored. ## Value -An integer. +A number. ## Specifications