Obter informações sobre a bateria

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

Exemplos de código são da aplicação básica de bateria que está listada no final deste tópico.

Obtenha o relatório agregado de baterias

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

Quando tiver um objeto de bateria agregada, 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);
}

Obtenha relatórios individuais de baterias

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 representem quaisquer controladores de bateria ligados ao dispositivo. Depois, usando a propriedade Id do objeto desejado DeviceInformation, crie um Battery correspondente com o método FromIdAsync. Por fim, ligue para o GetReport para obter o relatório individual da bateria.

Este exemplo mostra como criar um relatório de bateria para todas as baterias ligadas 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 de acesso

O objeto BatteryReport fornece muita informação sobre a bateria. Para mais informações, consulte a referência da API para as suas propriedades:

• Status (um valor de enumeração BatteryStatus )
• TaxaDeCarregamentoEmMiliwatts
• Capacidade de DesignEmMiliwattHoras
• Capacidade de Carga Completa EmMiliwattHora
• Capacidade RestanteEmMiliwattHora.

Este exemplo mostra algumas das propriedades do relatório de bateria usadas pela aplicação básica de baterias que são apresentadas mais adiante 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 do relatório

O objeto Battery ativa o evento ReportUpdated quando a carga, capacidade ou estado da bateria muda. Isto acontece normalmente imediatamente para alterações de estado e periodicamente para todas as outras alterações. Este exemplo mostra como se registar para atualizações de relatórios de bateria.

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

Gerir atualizações de relatórios

Quando ocorre uma atualização da bateria, o evento ReportUpdated passa o objeto correspondente Battery para o método do gestor de eventos. No entanto, este gestor de eventos não é chamado a partir do thread da interface. Terá de usar o objeto DispatcherQueue para invocar quaisquer alterações na interface, como 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: app básica de bateria

Este exemplo demonstra como usar as APIs de bateria para mostrar a informação da bateria na interface de utilizador (UI) da aplicação. 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);
        }
    }
}