Obter informações de bateria

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 agregação de baterias) e lidar com alterações de estado em todos os itens do relatório.

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

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. É aqui 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.

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

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 um Battery correspondente 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.

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

            // Get report.
            BatteryReport 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 (um valor de enumeração BatteryStatus )
• ChargeRateInMilliwatts
• Capacidade de projeto em miliwatt-hora
• CapacidadeTotalDeCargaEmMiliwattHora
• RemainingCapacityInMilliwattHours.

Este exemplo mostra algumas das propriedades do relatório de bateria usadas pelo aplicativo de bateria básico fornecido 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 são alterados. 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;
...

Gerenciar atualizações do relatório

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

private async void AggregateBattery_ReportUpdated(Battery sender, object args)
{
    if (reportRequested)
    {
        DispatcherQueue?.TryEnqueue(DispatcherQueuePriority.Normal, async () =>
        {
            await GetBatteryReport();
        });
    }
}

Código de exemplo: aplicativo de bateria básico

Este exemplo demonstra como usar as APIs de bateria para exibir as informações da bateria na interface do usuário (interface do usuário) do aplicativo. Ele contém uma interface XAML mínima, enquanto a interface principal do relatório é criada em code-behind.

<Grid>
    <Grid.RowDefinitions>
        <RowDefinition Height="Auto"/>
        <RowDefinition Height="*"/>
    </Grid.RowDefinitions>
    <StackPanel x:Name="topPanel" Margin="24">
        <RadioButtons>
            <RadioButton x:Name="AggregateButton" Content="Aggregate results" IsChecked="True" />
            <RadioButton x:Name="IndividualButton" Content="Individual results"/>
        </RadioButtons>
        <Button Content="Get battery report" Click="GetReportButton_Click"  Margin="0,12,0,0"/>
    </StackPanel>

    <StackPanel x:Name="BatteryReportPanel" Grid.Row="1" Margin="24,0"/>
</Grid>

using Microsoft.UI.Dispatching;
using Microsoft.UI.Xaml;
using Microsoft.UI.Xaml.Controls;
using Microsoft.UI.Xaml.Media;
using Windows.Devices.Enumeration;
using Windows.Devices.Power;

namespace DevicesDemo.Pages
{
    public sealed partial class BatteryInfoPage : Page
    {
        bool reportRequested = false;

        public BatteryInfoPage()
        {
            InitializeComponent();

            Battery.AggregateBattery.ReportUpdated += AggregateBattery_ReportUpdated;
        }

        private async void AggregateBattery_ReportUpdated(Battery sender, object args)
        {
            if (reportRequested)
            {
                DispatcherQueue?.TryEnqueue(DispatcherQueuePriority.Normal, async () =>
                {
                    await GetBatteryReport();
                });
            }
        }

        private async void GetReportButton_Click(object sender, RoutedEventArgs e)
        {
            await GetBatteryReport();
        }

        private async Task GetBatteryReport()
        {
            // Clear UI.
            BatteryReportPanel.Children.Clear();

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

            // Note request.
            reportRequested = true;
        }

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

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

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

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

                    // Get report.
                    BatteryReport 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);
        }
    }
}