From cf05364b23bc44af37a350319a1dd47485746a9c Mon Sep 17 00:00:00 2001 From: skyclouds2001 <95597335+skyclouds2001@users.noreply.github.com> Date: Fri, 1 Dec 2023 22:40:27 +0800 Subject: [PATCH] some update to Battery Status API (#30601) * add the Extensions to other interfaces section * style update * style pretty * add secure context info * fix text * small fix * fix * add the link to DOMException * update text * small fix --- .../en-us/web/api/battery_status_api/index.md | 12 +++++++--- .../web/api/batterymanager/charging/index.md | 6 ++--- .../chargingchange_event/index.md | 6 ++--- .../api/batterymanager/chargingtime/index.md | 10 ++++----- .../chargingtimechange_event/index.md | 6 ++--- .../batterymanager/dischargingtime/index.md | 8 +++---- .../dischargingtimechange_event/index.md | 6 ++--- files/en-us/web/api/batterymanager/index.md | 22 +++++++++++-------- .../web/api/batterymanager/level/index.md | 6 ++--- .../batterymanager/levelchange_event/index.md | 6 ++--- .../web/api/navigator/getbattery/index.md | 18 ++++++++------- 11 files changed, 59 insertions(+), 47 deletions(-) diff --git a/files/en-us/web/api/battery_status_api/index.md b/files/en-us/web/api/battery_status_api/index.md index 731a88ae042b616..b7f015c11243db6 100644 --- a/files/en-us/web/api/battery_status_api/index.md +++ b/files/en-us/web/api/battery_status_api/index.md @@ -2,10 +2,13 @@ title: Battery Status API slug: Web/API/Battery_Status_API page-type: web-api-overview -browser-compat: api.BatteryManager +browser-compat: + - api.BatteryManager + - api.Navigator.getBattery +spec-urls: https://w3c.github.io/battery/ --- -{{DefaultAPISidebar("Battery API")}} +{{DefaultAPISidebar("Battery API")}}{{securecontext_header}} The **Battery Status API**, more often referred to as the **Battery API**, provides information about the system's battery charge level and lets you be notified by events that are sent when the battery level or charging status change. This can be used to adjust your app's resource usage to reduce battery drain when the battery is low, or to save changes before the battery runs out in order to prevent data loss. @@ -15,7 +18,10 @@ The **Battery Status API**, more often referred to as the **Battery API**, provi - {{domxref("BatteryManager")}} - : Provides information about the system's battery charge level. -- {{domxref("navigator.getBattery()")}} {{ReadOnlyInline}} + +### Extensions to other interfaces + +- {{domxref("Navigator.getBattery()")}} - : Returns a {{JSxRef("Promise")}} that resolves with a {{DOMxRef("BatteryManager")}} object. ## Example diff --git a/files/en-us/web/api/batterymanager/charging/index.md b/files/en-us/web/api/batterymanager/charging/index.md index 5eab574483e31b6..4caa527889272ae 100644 --- a/files/en-us/web/api/batterymanager/charging/index.md +++ b/files/en-us/web/api/batterymanager/charging/index.md @@ -6,9 +6,9 @@ page-type: web-api-instance-property browser-compat: api.BatteryManager.charging --- -{{APIRef("Battery API")}} +{{ApiRef("Battery API")}}{{securecontext_header}} -The **`BatteryManager.charging`** property is a Boolean value indicating whether or not the device's battery is currently being charged. When its value changes, the [`chargingchange`](/en-US/docs/Web/API/BatteryManager/chargingchange_event) event is fired. +The **`BatteryManager.charging`** property is a Boolean value indicating whether or not the device's battery is currently being charged. When its value changes, the {{domxref("BatteryManager/chargingchange_event", "chargingchange")}} event is fired. If the battery is charging or the user agent is unable to report the battery status information, this value is `true`. Otherwise, it is `false`. @@ -47,4 +47,4 @@ navigator.getBattery().then((battery) => { ## See also - {{domxref("BatteryManager")}} -- {{domxref("Navigator.getBattery")}} +- {{domxref("Navigator.getBattery()")}} diff --git a/files/en-us/web/api/batterymanager/chargingchange_event/index.md b/files/en-us/web/api/batterymanager/chargingchange_event/index.md index e6d3e1e72dbb137..b35052988ffea59 100644 --- a/files/en-us/web/api/batterymanager/chargingchange_event/index.md +++ b/files/en-us/web/api/batterymanager/chargingchange_event/index.md @@ -6,9 +6,9 @@ page-type: web-api-event browser-compat: api.BatteryManager.chargingchange_event --- -{{APIRef("Battery API")}} +{{ApiRef("Battery API")}}{{securecontext_header}} -The **`chargingchange`** event of the [Battery Status API](/en-US/docs/Web/API/Battery_Status_API) is fired when the battery {{domxref("BatteryManager.charging","charging")}} property is updated. +The **`chargingchange`** event of the {{domxref("Battery Status API", "", "", "nocode")}} is fired when the battery {{domxref("BatteryManager.charging", "charging")}} property is updated. ## Syntax @@ -57,4 +57,4 @@ navigator.getBattery().then((battery) => { ## See also - {{domxref("BatteryManager")}} -- {{domxref("Navigator.getBattery")}} +- {{domxref("Navigator.getBattery()")}} diff --git a/files/en-us/web/api/batterymanager/chargingtime/index.md b/files/en-us/web/api/batterymanager/chargingtime/index.md index 4e913bef4d8b3f0..a6cd3274515fcbb 100644 --- a/files/en-us/web/api/batterymanager/chargingtime/index.md +++ b/files/en-us/web/api/batterymanager/chargingtime/index.md @@ -6,11 +6,11 @@ page-type: web-api-instance-property browser-compat: api.BatteryManager.chargingTime --- -{{APIRef("Battery API")}} +{{ApiRef("Battery API")}}{{securecontext_header}} -The **`BatteryManager.chargingTime`** property indicates the amount of time, in seconds, that remain until the battery is fully charged or `0` if the battery is already fully charged or the user agent is unable to report the battery status information. -If the battery is currently discharging, its value is [`Infinity`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Infinity). -When its value changes, the [`chargingtimechange`](/en-US/docs/Web/API/BatteryManager/chargingtimechange_event) event is fired. +The **`BatteryManager.chargingTime`** property indicates the amount of time, in seconds, that remain until the battery is fully charged, or `0` if the battery is already fully charged or the user agent is unable to report the battery status information. +If the battery is currently discharging, its value is {{jsxref("Infinity")}}. +When its value changes, the {{domxref("BatteryManager/chargingtimechange_event", "chargingtimechange")}} event is fired. > **Note:** Even if the time returned is precise to the second, > browsers round them to a higher interval @@ -52,4 +52,4 @@ navigator.getBattery().then((battery) => { ## See also - {{domxref("BatteryManager")}} -- {{domxref("Navigator.getBattery")}} +- {{domxref("Navigator.getBattery()")}} diff --git a/files/en-us/web/api/batterymanager/chargingtimechange_event/index.md b/files/en-us/web/api/batterymanager/chargingtimechange_event/index.md index 0cc247b4aeb5068..a7797815d8c1af1 100644 --- a/files/en-us/web/api/batterymanager/chargingtimechange_event/index.md +++ b/files/en-us/web/api/batterymanager/chargingtimechange_event/index.md @@ -6,9 +6,9 @@ page-type: web-api-event browser-compat: api.BatteryManager.chargingtimechange_event --- -{{APIRef("Battery API")}} +{{ApiRef("Battery API")}}{{securecontext_header}} -The **`chargingtimechange`** event of the [Battery Status API](/en-US/docs/Web/API/Battery_Status_API) is fired when the battery {{domxref("BatteryManager.chargingTime","chargingTime")}} is updated. +The **`chargingtimechange`** event of the {{domxref("Battery Status API", "", "", "nocode")}} is fired when the battery {{domxref("BatteryManager.chargingTime", "chargingTime")}} property is updated. ## Syntax @@ -57,4 +57,4 @@ navigator.getBattery().then((battery) => { ## See also - {{domxref("BatteryManager")}} -- {{domxref("Navigator.getBattery")}} +- {{domxref("Navigator.getBattery()")}} diff --git a/files/en-us/web/api/batterymanager/dischargingtime/index.md b/files/en-us/web/api/batterymanager/dischargingtime/index.md index dc089410bbf11b9..8c94e254cbdb2bd 100644 --- a/files/en-us/web/api/batterymanager/dischargingtime/index.md +++ b/files/en-us/web/api/batterymanager/dischargingtime/index.md @@ -6,11 +6,11 @@ page-type: web-api-instance-property browser-compat: api.BatteryManager.dischargingTime --- -{{APIRef("Battery API")}} +{{ApiRef("Battery API")}}{{securecontext_header}} The **`BatteryManager.dischargingTime`** property indicates the amount of time, in seconds, that remains until the battery is fully discharged, -or [`Infinity`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Infinity) if the battery is currently charging rather than discharging or the user agent is unable to report the battery status information. -When its value changes, the [`dischargingtimechange`](/en-US/docs/Web/API/BatteryManager/dischargingtimechange_event) event is fired. +or {{jsxref("Infinity")}} if the battery is currently charging rather than discharging or the user agent is unable to report the battery status information. +When its value changes, the {{domxref("BatteryManager/dischargingtimechange_event", "dischargingtimechange")}} event is fired. > **Note:** Even if the time returned is precise to the second, browsers round them to a higher > interval (typically to the closest 15 minutes) for privacy reasons. @@ -51,4 +51,4 @@ navigator.getBattery().then((battery) => { ## See also - {{domxref("BatteryManager")}} -- {{domxref("Navigator.getBattery")}} +- {{domxref("Navigator.getBattery()")}} diff --git a/files/en-us/web/api/batterymanager/dischargingtimechange_event/index.md b/files/en-us/web/api/batterymanager/dischargingtimechange_event/index.md index 11da78a31e1e32f..40299e9ce193eae 100644 --- a/files/en-us/web/api/batterymanager/dischargingtimechange_event/index.md +++ b/files/en-us/web/api/batterymanager/dischargingtimechange_event/index.md @@ -6,9 +6,9 @@ page-type: web-api-event browser-compat: api.BatteryManager.dischargingtimechange_event --- -{{APIRef("Battery API")}} +{{ApiRef("Battery API")}}{{securecontext_header}} -The **`dischargingtimechange`** event of the [Battery Status API](/en-US/docs/Web/API/Battery_Status_API) is fired when the battery {{domxref("BatteryManager.dischargingTime","dischargingTime")}} is updated. +The **`dischargingtimechange`** event of the {{domxref("Battery Status API", "", "", "nocode")}} is fired when the battery {{domxref("BatteryManager.dischargingTime", "dischargingTime")}} property is updated. ## Syntax @@ -57,4 +57,4 @@ navigator.getBattery().then((battery) => { ## See also - {{domxref("BatteryManager")}} -- {{domxref("Navigator.getBattery")}} +- {{domxref("Navigator.getBattery()")}} diff --git a/files/en-us/web/api/batterymanager/index.md b/files/en-us/web/api/batterymanager/index.md index 609647ac0a2a295..57cc9c732d65fa7 100644 --- a/files/en-us/web/api/batterymanager/index.md +++ b/files/en-us/web/api/batterymanager/index.md @@ -5,14 +5,18 @@ page-type: web-api-interface browser-compat: api.BatteryManager --- -{{APIRef}} +{{ApiRef("Battery API")}}{{securecontext_header}} -The `BatteryManager` interface of the [Battery Status API](/en-US/docs/Web/API/Battery_Status_API) provides information about the system's battery charge level. The {{domxref("navigator.getBattery()")}} method returns a promise that resolves with a `BatteryManager` interface. +The `BatteryManager` interface of the {{domxref("Battery Status API", "", "", "nocode")}} provides information about the system's battery charge level. The {{domxref("navigator.getBattery()")}} method returns a promise that resolves with a `BatteryManager` interface. + +Since Chrome 103, the `BatteryManager` interface of {{domxref("Battery Status API", "", "", "nocode")}} only expose to secure context. {{InheritanceDiagram}} ## Instance properties +_Also inherits properties from its parent interface, {{domxref("EventTarget")}}._ + - {{domxref("BatteryManager.charging")}} {{ReadOnlyInline}} - : A Boolean value indicating whether the battery is currently being charged. - {{domxref("BatteryManager.chargingTime")}} {{ReadOnlyInline}} @@ -24,17 +28,17 @@ The `BatteryManager` interface of the [Battery Status API](/en-US/docs/Web/API/B ## Instance methods -_Inherits methods from its parent interface:_ {{domxref("EventTarget")}}. +_Also inherits methods from its parent interface, {{domxref("EventTarget")}}._ ## Events -- {{domxref("BatteryManager.chargingchange_event", "chargingchange")}} +- {{domxref("BatteryManager/chargingchange_event", "chargingchange")}} - : Fired when the battery charging state (the {{domxref("BatteryManager.charging", "charging")}} property) is updated. -- {{domxref("BatteryManager.chargingtimechange_event", "chargingtimechange")}} +- {{domxref("BatteryManager/chargingtimechange_event", "chargingtimechange")}} - : Fired when the battery charging time (the {{domxref("BatteryManager.chargingTime", "chargingTime")}} property) is updated. -- {{domxref("BatteryManager.dischargingtimechange_event", "dischargingtimechange")}} +- {{domxref("BatteryManager/dischargingtimechange_event", "dischargingtimechange")}} - : Fired when the battery discharging time (the {{domxref("BatteryManager.dischargingTime", "dischargingTime")}} property) is updated. -- {{domxref("BatteryManager.levelchange_event", "levelchange")}} +- {{domxref("BatteryManager/levelchange_event", "levelchange")}} - : Fired when the battery level (the {{domxref("BatteryManager.level", "level")}} property) is updated. ## Specifications @@ -47,5 +51,5 @@ _Inherits methods from its parent interface:_ {{domxref("EventTarget")}}. ## See also -- The [Battery Status API](/en-US/docs/Web/API/Battery_Status_API) -- {{domxref("navigator.getBattery")}} +- The {{domxref("Battery Status API", "", "", "nocode")}} +- {{domxref("Navigator.getBattery()")}} diff --git a/files/en-us/web/api/batterymanager/level/index.md b/files/en-us/web/api/batterymanager/level/index.md index efaef07ffe8bd1a..596cd5720ff33c8 100644 --- a/files/en-us/web/api/batterymanager/level/index.md +++ b/files/en-us/web/api/batterymanager/level/index.md @@ -6,12 +6,12 @@ page-type: web-api-instance-property browser-compat: api.BatteryManager.level --- -{{APIRef("Battery API")}} +{{ApiRef("Battery API")}}{{securecontext_header}} The **`BatteryManager.level`** property indicates the current battery charge level as a value between `0.0` and `1.0`. A value of `0.0` means the battery is empty and the system is about to be suspended. A value of `1.0` means the battery is full or the user agent is unable to report the battery status information. -When its value changes, the [`levelchange`](/en-US/docs/Web/API/BatteryManager/levelchange_event) event is fired. +When its value changes, the {{domxref("BatteryManager/levelchange_event", "levelchange")}} event is fired. ## Value @@ -60,4 +60,4 @@ getLevel.addEventListener("click", async () => { ## See also - {{domxref("BatteryManager")}} -- {{domxref("Navigator.getBattery")}} +- {{domxref("Navigator.getBattery()")}} diff --git a/files/en-us/web/api/batterymanager/levelchange_event/index.md b/files/en-us/web/api/batterymanager/levelchange_event/index.md index 1ae9271c7302bd7..55f88f448095eb3 100644 --- a/files/en-us/web/api/batterymanager/levelchange_event/index.md +++ b/files/en-us/web/api/batterymanager/levelchange_event/index.md @@ -6,9 +6,9 @@ page-type: web-api-event browser-compat: api.BatteryManager.levelchange_event --- -{{APIRef("Battery API")}} +{{ApiRef("Battery API")}}{{securecontext_header}} -The **`levelchange`** event of the [Battery Status API](/en-US/docs/Web/API/Battery_Status_API) is fired when the battery {{domxref("BatteryManager.level","level")}} property is updated. +The **`levelchange`** event of the {{domxref("Battery Status API", "", "", "nocode")}} is fired when the battery {{domxref("BatteryManager.level", "level")}} property is updated. ## Syntax @@ -65,4 +65,4 @@ navigator.getBattery().then((battery) => { ## See also - {{domxref("BatteryManager")}} -- {{domxref("Navigator.getBattery")}} +- {{domxref("Navigator.getBattery()")}} diff --git a/files/en-us/web/api/navigator/getbattery/index.md b/files/en-us/web/api/navigator/getbattery/index.md index dcd7ebb0e4ff50e..245642a7242ef0a 100644 --- a/files/en-us/web/api/navigator/getbattery/index.md +++ b/files/en-us/web/api/navigator/getbattery/index.md @@ -6,13 +6,15 @@ page-type: web-api-instance-method browser-compat: api.Navigator.getBattery --- -{{ ApiRef("Battery API") }} +{{ApiRef("Battery API")}}{{securecontext_header}} The **`getBattery()`** method provides information about the system's battery. -It returns a battery promise, which is resolved in a {{domxref("BatteryManager")}} object providing also some new events you can handle to monitor the battery status. -This implements the [Battery Status API](/en-US/docs/Web/API/Battery_Status_API); see that documentation for additional details, a guide to using the API, and sample code. +It returns a battery promise, which resolves with a {{domxref("BatteryManager")}} object providing some properties to get the battery status also some events you can handle to monitor the battery status. +This implements the {{domxref("Battery Status API", "", "", "nocode")}}; see that documentation for additional details, a guide to using the API, and sample code. -> **Note:** Access to this feature may be controlled by the {{HTTPHeader("Permissions-Policy")}} directive {{HTTPHeader("Permissions-Policy/battery","battery")}}. +Since Chrome 103, the `Navigator.getBattery()` method of {{domxref("Battery Status API", "", "", "nocode")}} only expose to secure context. + +> **Note:** Access to this feature may be controlled by the {{HTTPHeader("Permissions-Policy")}} directive {{HTTPHeader("Permissions-Policy/battery", "battery")}}. ## Syntax @@ -34,7 +36,7 @@ A {{JSxRef("Promise")}} that fulfills with a {{DOMxRef("BatteryManager")}} objec - : Use of this feature was blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy). -- `SecurityError` +- `SecurityError` {{domxref("DOMException")}} - : The User Agent does not expose battery information to insecure contexts and this method was called from an insecure context. ## Examples @@ -53,7 +55,7 @@ navigator.getBattery().then((battery) => { }); ``` -For more examples and details, see [Battery Status API](/en-US/docs/Web/API/Battery_Status_API). +For more examples and details, see {{domxref("Battery Status API", "", "", "nocode")}}. ## Specifications @@ -65,5 +67,5 @@ For more examples and details, see [Battery Status API](/en-US/docs/Web/API/Batt ## See also -- [Battery Status API](/en-US/docs/Web/API/Battery_Status_API) -- `Permissions-Policy` {{HTTPHeader("Permissions-Policy/battery", "battery")}} feature +- {{domxref("Battery Status API", "", "", "nocode")}} +- {{HTTPHeader("Permissions-Policy")}} {{HTTPHeader("Permissions-Policy/battery", "battery")}} directive