Obter informações sobre a bateria

2025-06-10

Este tópico descreve como obter um relatório de bateria que inclua informações detalhadas da bateria (como a carga, a capacidade e o status de uma bateria ou conjunto de baterias) e gerenciar alterações de estado em quaisquer itens do relatório.

(Relatório de Bateria)

Os exemplos de código são do aplicativo de bateria básico listado no final deste tópico.

APIs importantes

Obter relatório de bateria agregada

Alguns dispositivos têm mais de uma bateria e nem sempre é óbvio como cada bateria contribui para a capacidade de energia geral do dispositivo. É aí que entra a classe AggregateBattery. A bateria agregada representa todos os controladores de bateria conectados ao dispositivo e pode fornecer um único objeto BatteryReport geral.

Observação Uma classe Bateria na verdade corresponde a um controlador de bateria. Dependendo do dispositivo, às vezes o controlador é anexado à bateria física e, às vezes, é anexado ao compartimento do dispositivo. Portanto, é possível criar um objeto de bateria mesmo quando nenhuma bateria está presente. Outras vezes, o objeto de bateria pode ser nulo .

Depois de ter um objeto de bateria agregado, chame GetReport para obter o correspondente BatteryReport .

private void RequestAggregateBatteryReport()
{
    // Create aggregate battery object
    var aggBattery = Battery.AggregateBattery;

    // Get report
    var report = aggBattery.GetReport();

    // Update UI
    AddReportUI(BatteryReportPanel, report, aggBattery.DeviceId);
}

Obter relatórios individuais de bateria

Você também pode criar um objeto BatteryReport para baterias individuais. Use GetDeviceSelector com o método FindAllAsync para obter uma coleção de objetos DeviceInformation que representam todos os controladores de bateria conectados ao dispositivo. Em seguida, usando a propriedade Id do objeto DeviceInformation desejado, crie o correspondente Battery com o método FromIdAsync. Por fim, chame GetReport para obter o relatório de bateria individual.

Este exemplo mostra como criar um relatório de bateria para todas as baterias conectadas ao dispositivo.

async private void RequestIndividualBatteryReports()
{
    // Find batteries 
    var deviceInfo = await DeviceInformation.FindAllAsync(Battery.GetDeviceSelector());
    foreach(DeviceInformation device in deviceInfo)
    {
        try
        {
        // Create battery object
        var battery = await Battery.FromIdAsync(device.Id);

        // Get report
        var report = battery.GetReport();

        // Update UI
        AddReportUI(BatteryReportPanel, report, battery.DeviceId);
        }
        catch { /* Add error handling, as applicable */ }
    }
}

Detalhes do relatório do Access

O objeto BatteryReport fornece muitas informações de bateria. Para obter mais informações, consulte a referência de API para suas propriedades: Status (uma enumeração StatusDaBateria), TaxaDeCargaEmMiliwatts, CapacidadeDeProjetoEmMiliwattHora, CapacidadeDeCargaCompletaEmMiliwattHorae CapacidadeRestanteEmMiliwattHora. Este exemplo mostra algumas das propriedades do relatório de bateria usadas pelo aplicativo de bateria básico, que são fornecidas posteriormente neste tópico.

...
TextBlock txt3 = new TextBlock { Text = "Charge rate (mW): " + report.ChargeRateInMilliwatts.ToString() };
TextBlock txt4 = new TextBlock { Text = "Design energy capacity (mWh): " + report.DesignCapacityInMilliwattHours.ToString() };
TextBlock txt5 = new TextBlock { Text = "Fully-charged energy capacity (mWh): " + report.FullChargeCapacityInMilliwattHours.ToString() };
TextBlock txt6 = new TextBlock { Text = "Remaining energy capacity (mWh): " + report.RemainingCapacityInMilliwattHours.ToString() };
...
...

Solicitar atualizações de relatório

O objeto Battery dispara o evento ReportUpdated quando a carga, a capacidade ou o status da bateria é alterado. Isso normalmente ocorre imediatamente para alterações de status e periodicamente para todas as outras alterações. Este exemplo mostra como se registrar para atualizações de relatório de bateria.

...
Battery.AggregateBattery.ReportUpdated += AggregateBattery_ReportUpdated;
...

Lidar com atualizações de relatório

Quando ocorre uma atualização da bateria, o evento ReportUpdated passa o objeto correspondente de Bateria para o método do manipulador de eventos. No entanto, esse manipulador de eventos não é chamado da linha de execução da IU. Você precisará usar o objeto Dispatcher para invocar as alterações de interface do usuário, conforme mostrado neste exemplo.

async private void AggregateBattery_ReportUpdated(Battery sender, object args)
{
    if (reportRequested)
    {

        await Dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>
        {
            // Clear UI
            BatteryReportPanel.Children.Clear();


            if (AggregateButton.IsChecked == true)
            {
                // Request aggregate battery report
                RequestAggregateBatteryReport();
            }
            else
            {
                // Request individual battery report
                RequestIndividualBatteryReports();
            }
        });
    }
}

Exemplo: aplicativo de bateria básico

Teste essas APIs criando o aplicativo de bateria básico a seguir no Microsoft Visual Studio. Na página inicial do Visual Studio, clique em Novo Projetoe, em seguida, nos modelos Visual C# > Windows > Universal, crie um novo aplicativo usando o modelo Aplicativo em Branco.

Em seguida, abra o arquivo MainPage.xaml e copie o XML a seguir para este arquivo (substituindo seu conteúdo original).

Observação

Se o aplicativo não tiver o nome App1, você precisará substituir a primeira parte do nome da classe no snippet a seguir pelo namespace do aplicativo. Por exemplo, se você criou um projeto chamado BasicBatteryApp, substitua x:Class="App1.MainPage" por x:Class="BasicBatteryApp.MainPage" e xmlns:local="using:App1" por xmlns:local="using:BasicBatteryApp".

<Page
    x:Class="App1.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:App1"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d">

    <StackPanel Background="{ThemeResource ApplicationPageBackgroundThemeBrush}" >
        <StackPanel VerticalAlignment="Center" Margin="15,30,0,0" >
            <RadioButton x:Name="AggregateButton" Content="Aggregate results" GroupName="Type" IsChecked="True" />
            <RadioButton x:Name="IndividualButton" Content="Individual results" GroupName="Type" IsChecked="False" />
        </StackPanel>
        <StackPanel Orientation="Horizontal">
        <Button x:Name="GetBatteryReportButton" 
                Content="Get battery report" 
                Margin="15,15,0,0" 
                Click="GetBatteryReport"/>
        </StackPanel>
        <StackPanel x:Name="BatteryReportPanel" Margin="15,15,0,0"/>
    </StackPanel>
</Page>

Em seguida, abra o arquivo MainPage.xaml.cs do projeto e substitua o código existente pelo seguinte.

Observação

Se o aplicativo não for denominado App1, você precisará renomear o namespace no exemplo a seguir com o nome que você deu ao seu projeto. Por exemplo, se você criou um projeto chamado BasicBatteryApp, substituirá o namespace App1 pelo namespace BasicBatteryApp.

using System;
using Windows.UI.Xaml;
using Windows.UI.Xaml.Controls;
using Windows.UI.Xaml.Media;
using Windows.Devices.Enumeration;
using Windows.Devices.Power;
using Windows.UI.Core;

namespace App1
{
    public sealed partial class MainPage : Page
    {
        bool reportRequested = false;
        public MainPage()
        {
            this.InitializeComponent();
            Battery.AggregateBattery.ReportUpdated += AggregateBattery_ReportUpdated;
        }


        private void GetBatteryReport(object sender, RoutedEventArgs e)
        {
            // Clear UI
            BatteryReportPanel.Children.Clear();


            if (AggregateButton.IsChecked == true)
            {
                // Request aggregate battery report
                RequestAggregateBatteryReport();
            }
            else
            {
                // Request individual battery report
                RequestIndividualBatteryReports();
            }

            // Note request
            reportRequested = true;
        }

        private void RequestAggregateBatteryReport()
        {
            // Create aggregate battery object
            var aggBattery = Battery.AggregateBattery;

            // Get report
            var report = aggBattery.GetReport();

            // Update UI
            AddReportUI(BatteryReportPanel, report, aggBattery.DeviceId);
        }

        async private void RequestIndividualBatteryReports()
        {
            // Find batteries 
            var deviceInfo = await DeviceInformation.FindAllAsync(Battery.GetDeviceSelector());
            foreach(DeviceInformation device in deviceInfo)
            {
                try
                {
                // Create battery object
                var battery = await Battery.FromIdAsync(device.Id);

                // Get report
                var report = battery.GetReport();

                // Update UI
                AddReportUI(BatteryReportPanel, report, battery.DeviceId);
                }
                catch { /* Add error handling, as applicable */ }
            }
        }


        private void AddReportUI(StackPanel sp, BatteryReport report, string DeviceID)
        {
            // Create battery report UI
            TextBlock txt1 = new TextBlock { Text = "Device ID: " + DeviceID };
            txt1.FontSize = 15;
            txt1.Margin = new Thickness(0, 15, 0, 0);
            txt1.TextWrapping = TextWrapping.WrapWholeWords;

            TextBlock txt2 = new TextBlock { Text = "Battery status: " + report.Status.ToString() };
            txt2.FontStyle = Windows.UI.Text.FontStyle.Italic;
            txt2.Margin = new Thickness(0, 0, 0, 15);

            TextBlock txt3 = new TextBlock { Text = "Charge rate (mW): " + report.ChargeRateInMilliwatts.ToString() };
            TextBlock txt4 = new TextBlock { Text = "Design energy capacity (mWh): " + report.DesignCapacityInMilliwattHours.ToString() };
            TextBlock txt5 = new TextBlock { Text = "Fully-charged energy capacity (mWh): " + report.FullChargeCapacityInMilliwattHours.ToString() };
            TextBlock txt6 = new TextBlock { Text = "Remaining energy capacity (mWh): " + report.RemainingCapacityInMilliwattHours.ToString() };

            // Create energy capacity progress bar & labels
            TextBlock pbLabel = new TextBlock { Text = "Percent remaining energy capacity" };
            pbLabel.Margin = new Thickness(0,10, 0, 5);
            pbLabel.FontFamily = new FontFamily("Segoe UI");
            pbLabel.FontSize = 11;

            ProgressBar pb = new ProgressBar();
            pb.Margin = new Thickness(0, 5, 0, 0);
            pb.Width = 200;
            pb.Height = 10;
            pb.IsIndeterminate = false;
            pb.HorizontalAlignment = HorizontalAlignment.Left;

            TextBlock pbPercent = new TextBlock();
            pbPercent.Margin = new Thickness(0, 5, 0, 10);
            pbPercent.FontFamily = new FontFamily("Segoe UI");
            pbLabel.FontSize = 11;

            // Disable progress bar if values are null
            if ((report.FullChargeCapacityInMilliwattHours == null)||
                (report.RemainingCapacityInMilliwattHours == null))
            {
                pb.IsEnabled = false;
                pbPercent.Text = "N/A";
            }
            else
            {
                pb.IsEnabled = true;
                pb.Maximum = Convert.ToDouble(report.FullChargeCapacityInMilliwattHours);
                pb.Value = Convert.ToDouble(report.RemainingCapacityInMilliwattHours);
                pbPercent.Text = ((pb.Value / pb.Maximum) * 100).ToString("F2") + "%";
            }

            // Add controls to stackpanel
            sp.Children.Add(txt1);
            sp.Children.Add(txt2);
            sp.Children.Add(txt3);
            sp.Children.Add(txt4);
            sp.Children.Add(txt5);
            sp.Children.Add(txt6);
            sp.Children.Add(pbLabel);
            sp.Children.Add(pb);
            sp.Children.Add(pbPercent);
        }

        async private void AggregateBattery_ReportUpdated(Battery sender, object args)
        {
            if (reportRequested)
            {

                await Dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>
                {
                    // Clear UI
                    BatteryReportPanel.Children.Clear();


                    if (AggregateButton.IsChecked == true)
                    {
                        // Request aggregate battery report
                        RequestAggregateBatteryReport();
                    }
                    else
                    {
                        // Request individual battery report
                        RequestIndividualBatteryReports();
                    }
                });
            }
        }
    }
}

Dica

Para receber valores numéricos do objeto BatteryReport, depure seu aplicativo na Máquina Local ou em um Dispositivo Externo. Ao depurar em um emulador de dispositivo, o objeto BatteryReport retorna nulo para as propriedades de capacidade e taxa.