배터리 상태 API

이 문서의 상태

이 섹션은 이 문서를 발행한 당시의 상태에 대해 기술합니다. 다른 문서가 이 문서를 대체할 수 있습니다. 현재 W3C 발행본 및 기술 보고서 최신 버전 목록은 W3C technical reports index at http://www.w3.org/TR/에서 확인할 수 있습니다.

No substantial changes have been made to the Battery Status API since the W3C Candidate Recommendation of December 2014 (diff) , however the document now has more detailed privacy considerations, including advice regarding the implications of high precision readouts, based on feedback from implementation experience. It also has updated references.

The implementation report of the API shows all features have been implemented by two independent deployed browsers, meeting the CR exit criteria. We had no CR features marked as 'at-risk'.

There is a known issue with some WebIDL implementations that are not specific to the Battery Status API; the interoperability effect of that issue is minimal, since it only affects error handling in case where the API is mis-used, which is in practice detected at development time rather than usage time.

This document was published by the Device APIs Working Group as a Proposed Recommendation. This document is intended to become a W3C Recommendation. The W3C Membership and other interested parties are invited to review the document and send comments to public-device-apis@w3.org (subscribe, archives) through 29 April 2016. Advisory Committee Representatives should consult their WBS questionnaires. Note that substantive technical comments were expected during the Last Call review period that ended 02 October 2014.

Please see the Working Group's implementation report.

Publication as a Proposed Recommendation does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 14 October 2005 W3C Process Document.

6. `BatteryManager` 인터페이스

BatteryManager 인터페이스는 호스팅 디바이스의 현재 배터리 상태 정보를 나타냅니다. charging 속성은 시스템 배터리의 충전 상태를 나타냅니다. chargingTime 속성은 시스템 배터리가 완전히 차기까지 남은 시간을 나타냅니다. dischargingTime 속성은 시스템 배터리가 완전히 충전 중이지 않은 시간과 시스템이 꺼지기까지의 시간을 나타내며, level 속성은 시스템 배터리 레벨을 나타냅니다.

interface BatteryManager : EventTarget {
    readonly        attribute boolean             charging;
    readonly        attribute unrestricted double chargingTime;
    readonly        attribute unrestricted double dischargingTime;
    readonly        attribute double              level;
                    attribute EventHandler        onchargingchange;
                    attribute EventHandler        onchargingtimechange;
                    attribute EventHandler        ondischargingtimechange;
                    attribute EventHandler        onlevelchange;
};

유저 에이전트는 새로운 BatteryManager 객체를 생성할 때, 반드시 새 BatteryManager 객체를 사용하여야 하고 [MUST], 그 속성값을 배터리 상태 정보 리포트를 사용하지 못하는 경우를 제외하고, 현재 배터리 상태 정보로 해야하며, 배터리 상태 정보 리포트를 사용하지 못하는 경우, 반드시 기본 값을 아래 순서대로 해야합니다 [MUST]. charging은 반드시 true로 [MUST], chargingTime은 반드시 0으로 [MUST], dischargingTime은 반드시 양수 무한대로 [MUST], level은 반드시 1.0으로 설정합니다 [MUST.

예를 들어 유저나 시스템 선호, 세팅, 제한으로 인해 만약 속성의 어떤 값도 리포트하지 못하는 경우 유저 에이전트는 배터리 상태 정보 리포트를 사용하지 못하는 경우를 말해야합니다.

노트

구현체가 배터리 상태 정보 리포트를 사용하지 못하는 경우 예를 들어, 만약 배터리 상태 정보를 사용하지 못하는 경우, 퍼포먼스 저하로부터 막거나, 완전히 충전되거나, 배터리 접속 핑거프린팅 가능성을 줄일 수 있습니다.

charging 속성은 반드시, 충전중이지 않을 때는 false로, 충전 중인 경우, 구현체가 상태 보고를 사용하지 못할 경우, 시스템의 배터리가 첨부되지 않은 경우, 그 외의 경우에는 true로 세트해야합니다 [MUST]. 배터리 충전 상태가 업데이트 될 때, 유저 에이전트는 반드시 charging 속성의 값을 태스크 큐로 설정하고, BatteryManager 객체의 chargingchange 이벤트를 발생시켜야 합니다 [MUST].

chargingTime 속성은 반드시 시스템의 배터리가 첨부되지 않았거나 배터리 상태가 풀인 경우 0으로 세팅해야 하며, 배터리가 충전중이지 않은 경우나 구현체가 충전 시간 리포트를 사용하지 못하는 경우, 그 외의 경우에는 양수 무한대로 값을 정합니다 [MUST]. 배터리 충전 시간이 업데이트 될 때, 유저 에이전트는 반드시 chargingtime 속성의 값을 태스크 큐로 설정하고, BatteryManager 객체의 chargingtimechange 이벤트를 발생시켜야 합니다 [MUST].

dischargingTime 속성은 반드시 배터리가 충전중이거나, 구현체가 충전을 안한 시간 나머지의 보고를 사용하지 못하거나, 시스템에 배터리가 첨부되지 않았거나, 그 외의 경우에 값을 양수 무한대로 지정해야 합니다. 배터리 비충전 시간이 업데이트 될 때, 유저 에이전트는 반드시 dischargingTime 속성의 값을 태스크 큐로 설정하고, BatteryManager 객체의 dischargingtimechange 이벤트를 발생시켜야 합니다.

level 속성은 반드시 시스템의 배터리가 고갈되거나, 시스템이 꺼진 경우 0으로 지정하고, 배터리가 가득 차있거나, 구현체가 배터리의 레벨 리포트를 사용하지 못하는 경우, 시스템에 배터리가 첨부되지 않은 경우에는 1.0으로 지정합니다. 배터리 레벨이 업데이트 될 때, 유저 에이전트는 반드시 level 속성의 값을 태스크 큐로 설정하고, BatteryManager 객체의 levelchange 이벤트를 발생시켜야 합니다.

노트

얼마나 자주 chargingtimechange, dischargingtimechange, levelchange 이벤트가 발생할 지에 대한 정의는 구현체에 따릅니다.

6.1 다중 배터리

호스팅 디바이스가 하나 이상의 배터리를 사용하는 경우 BatteryManager는 배터리들을 통합하여 관측해야합니다. [SHOULD]

charging 속성은 최소한 하나의 배터리의 charging 상태가 위에서 소개한 대로 true라면 true로 세팅해야만 합니다 [MUST]. 그 외의 경우에는 반드시 false입니다 [MUST].

chargingTime 속성은 만약 병렬 충전이라면 개별 배터리의 최대 충전 시간으로 설정하며, 직렬 충전이라면 각 배터리별 충전 시간의 합계로 설정합니다.

dischargingTime 속성은 만약 병렬 비충전이라면 개별 배터리의 최대 충전 시간으로 설정하며, 직렬 비충전이라면 각 배터리별 비충전 시간의 합계로 설정합니다.

level 속성은 같은 정도라면 배터리의 레벨의 평균, 다른 정도라면 배터리 레벨의 가중 평균으로 설정합니다.

6.2 이벤트 핸들러

아래 목록은 BatteryManager 객체에서 속성으로 지원해야만 하는 (그리고 그 이벤트 핸들러 이벤트 타입에 해당하는) 이벤트 핸들러입니다.

이벤트 핸들러	이벤트 핸들러 이벤트 타입
`onchargingchange`	`chargingchange`
`onchargingtimechange`	`chargingtimechange`
`ondischargingtimechange`	`dischargingtimechange`
`onlevelchange`	`levelchange`

7. 예제

이 섹션은 표준에 준하지 않습니다.

아래 사소한 에제에서 배터리 레벨이 바뀔 때마다 콘솔에 배터리 레벨을 찍어주고 있습니다:

Example 1

// We get the initial value when the promise resolves ...
navigator.getBattery().then(function(battery) {
  console.log(battery.level);
  // ... and any subsequent updates.
  battery.onlevelchange = function() {
    console.log(this.level);
  };
});

대신하여, 같은 동작으로 addEventListener() 메서드를 사용했습니다.

Example 2

navigator.getBattery().then(function(battery) {
  console.log(battery.level);
  battery.addEventListener('levelchange', function() {
    console.log(this.level);
  });
});

아래 예제는 인디케이터를 업데이트하여 충전 상태, 레벨과 일분에 남아있는 시간을 보여줍니다.

Example 3

<!DOCTYPE html>
<html>
<head>
  <title>Battery Status API Example</title>
  <script>
    window.onload = function () {
      function updateBatteryStatus(battery) {
        document.querySelector('#charging').textContent = battery.charging ? 'charging' : 'not charging';
        document.querySelector('#level').textContent = battery.level;
        document.querySelector('#dischargingTime').textContent = battery.dischargingTime / 60;
      }

      navigator.getBattery().then(function(battery) {
        // Update the battery status initially when the promise resolves ...
        updateBatteryStatus(battery);

        // .. and for any subsequent updates.
        battery.onchargingchange = function () {
          updateBatteryStatus(battery);
        };

        battery.onlevelchange = function () {
          updateBatteryStatus(battery);
        };

        battery.ondischargingtimechange = function () {
          updateBatteryStatus(battery);
        };
      });
    };
  </script>
</head>
<body>
  <div id="charging">(charging state unknown)</div>
  <div id="level">(battery level unknown)</div>
  <div id="dischargingTime">(discharging time unknown)</div>
</body>
</html>

배터리 상태 API

2016년 3월 29일 W3C 후보 권고안

Abstract

이 문서의 상태

1. 소개

2. 적합 요구사항

3. 용어

4. 보안 및 프라이버시 고려사항

5. `Navigator` 인터페이스

6. `BatteryManager` 인터페이스

6.1 다중 배터리

6.2 이벤트 핸들러

7. 예제

A. 감사의 말

B. References

B.1 Normative references

Abstract

이 문서의 상태

1. 소개

2. 적합 요구사항

3. 용어

4. 보안 및 프라이버시 고려사항

5. Navigator 인터페이스

6. BatteryManager 인터페이스

6.1 다중 배터리

6.2 이벤트 핸들러

7. 예제

A. 감사의 말

B. References

B.1 Normative references

5. `Navigator` 인터페이스

6. `BatteryManager` 인터페이스