Получение сведений об аккумуляторе

В этом разделе описывается, как получить отчет о батарее, содержащий подробные сведения о батарее (например, заряд, емкость и состояние батареи или агрегат батареи), а также обрабатывать изменения состояния любых элементов в отчете.

Примеры кода относятся к базовому приложению батареи, указанному в конце этого раздела.

Important API:BatteryReport, Windows. Devices.Power, DeviceInformation.FindAllAsync

Получение сводного отчета о батарее

Некоторые устройства имеют более одной батареи, и это не всегда очевидно, как каждая батарея способствует общей емкости энергии устройства. Здесь-то и появляется класс AggregateBattery. Совокупная батарея объединяет все контроллеры батарей, подключённые к устройству, и может предоставлять единый объект BatteryReport.

Note

Класс Battery фактически соответствует контроллеру батареи. В зависимости от устройства, иногда контроллер подключен к физической батарее и иногда он подключен к корпусу устройства. Таким образом, можно создать объект батареи даже при отсутствии батареи. В других случаях объект батареи может быть null.

Получив объект агрегированной батареи, вызовите GetReport, чтобы получить соответствующий объект 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);
}

Получение отдельных отчетов о батарее

Можно также создать объект BatteryReport для отдельных батарей. Используйте GetDeviceSelector с методом FindAllAsync, чтобы получить коллекцию объектов DeviceInformation, представляющих все контроллеры батареи, подключенные к устройству. Затем с помощью свойства Id объекта DeviceInformation создайте соответствующий метод Battery с помощью метода FromIdAsync. Наконец, вызовите GetReport , чтобы получить отдельный отчет о батарее.

В этом примере показано, как создать отчет о батарее для всех батарей, подключенных к устройству.

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. */ }
    }
}

Доступ к сведениям о отчете

Объект BatteryReport предоставляет много сведений о батарее. Дополнительные сведения см. в справочнике по API по его свойствам:

Состояние (значение из перечисления BatteryStatus)
Скорость зарядки в милливаттах
DesignCapacityInMilliwattHours
Полная емкость заряда в милливатт-часах
Оставшаяся ёмкость в милливатт-часах.

В этом примере показаны некоторые свойства отчета о батарее, используемые базовым приложением батареи, которое представлено далее в этом разделе.

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() };

Запрос обновлений отчета

Объект Battery активирует событие ReportUpdated при изменении заряда, емкости или состояния батареи. Обычно это происходит немедленно для изменений состояния и периодически для всех других изменений. В этом примере показано, как зарегистрировать обновления отчета о батарее.

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

Обработка обновлений отчетов

При обновлении батареи событие ReportUpdated передает соответствующий объект Battery в метод обработчика событий. Однако этот обработчик событий не вызывается из потока пользовательского интерфейса. Для вызова изменений пользовательского интерфейса необходимо использовать объект DispatcherQueue , как показано в этом примере.

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

Пример кода: базовое приложение для батареи

В этом примере показано, как использовать API батареи для отображения сведений о батарее в пользовательском интерфейсе приложения. Он содержит минимальный пользовательский интерфейс XAML, а основной пользовательский интерфейс отчета создается в коде программной части.

<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);
        }
    }
}

Tip

Чтобы получить числовые значения из объекта BatteryReport, отладите приложение на локальном компьютере или внешнем устройстве. При отладке в эмуляторе устройства объект BatteryReport возвращает значение NULL к свойствам емкости и скорости.

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-06-01