共用方式為

電池

  • 發行項

Browse sample. 流覽範例

本文說明如何使用 .NET 多平臺應用程式 UI （.NET MAUI） IBattery 介面來檢查裝置的電池資訊，並監視是否有變更。 此介面也會提供裝置節能狀態的相關信息，指出裝置是否以低功率模式執行。

介面的預設實作 IBattery 可透過 Battery.Default 屬性取得。 IBattery介面和Battery類別都包含在 命名空間中Microsoft.Maui.Devices。

開始使用

若要存取 電池 功能，需要下列平臺特定設定。

需要 BatteryStats 權限，而且必須在 Android 專案中設定。 您可以透過下列方式設定權限：

  • 新增元件型權限：

    開啟 Platform/Android/MainApplication.cs 檔案，並在 指示詞之後using新增下列元件屬性：

    [assembly: UsesPermission(Android.Manifest.Permission.BatteryStats)]

    - 或 -

  • 更新 Android 指令清單：

    開啟 [平臺/Android/AndroidManifest.xml] 檔案，manifest然後在 節點中新增下列這一行：

    <uses-permission android:name="android.permission.BATTERY_STATS" />

    - 或 -

  • 更新指令清單編輯器中的 Android 指令清單：

    在 Visual Studio 中按兩下 [平臺/Android/AndroidManifest.xml ] 檔案，以開啟 Android 指令清單編輯器。 然後，在 [必要許可權] 底下，檢查BATTERY_STATS許可權。 這將會自動更新 AndroidManifest.xml 檔案。

檢查電池狀態

您可以藉由存取 屬性來 Battery.Default 檢查電池狀態，這是介面的預設實作 IBattery 。 此介面會定義各種屬性，以提供電池狀態的相關信息，例如 ChargeLevel 讀取剩餘多少電池。 屬性ChargeLevel會分別傳回介於 0.0 和 1.0 之間的值，指出電池的電量從空白到完整。

您也可以 BatteryInfoChanged 使用 事件，並在電池的狀態變更時引發。 下列範例示範如何使用監視器事件， BatteryInfoChanged 並將電池狀態報告給 Label 控件：

private void BatterySwitch_Toggled(object sender, ToggledEventArgs e) =>
    WatchBattery();

private bool _isBatteryWatched;

private void WatchBattery()
{
    
    if (!_isBatteryWatched)
    {
        Battery.Default.BatteryInfoChanged += Battery_BatteryInfoChanged;
    }
    else
    {
        Battery.Default.BatteryInfoChanged -= Battery_BatteryInfoChanged;
    }

    _isBatteryWatched = !_isBatteryWatched;
}

private void Battery_BatteryInfoChanged(object sender, BatteryInfoChangedEventArgs e)
{
    BatteryStateLabel.Text = e.State switch
    {
        BatteryState.Charging => "Battery is currently charging",
        BatteryState.Discharging => "Charger is not connected and the battery is discharging",
        BatteryState.Full => "Battery is full",
        BatteryState.NotCharging => "The battery isn't charging.",
        BatteryState.NotPresent => "Battery is not available.",
        BatteryState.Unknown => "Battery is unknown",
        _ => "Battery is unknown"
    };
    
    BatteryLevelLabel.Text = $"Battery is {e.ChargeLevel * 100}% charged.";
}

低功率節能模式

以電池電力運作的裝置可能會進入低電源省電狀態。 有時候，裝置會自動切換到此模式，例如當電池低於 20% 容量時。 針對省電模式，作業系統會減少可能會耗電的活動。 當進入省電模式時，應用程式也可以透過避免進行背景處理或執行其他耗電量大的活動，以降低耗電量。

重要

若裝置已開啟低電源狀態，應用程式應該避免背景處理。

裝置的節能狀態可藉由存取 EnergySaverStatus 屬性來讀取，其為 On、 Off或 Unknown。 如果狀態為 On，應用程式應該避免背景處理或其他可能耗用大量電源的活動。

當電池進入或離開節能模式時，電池會引發 EnergySaverStatusChanged 事件。 您也可以使用 EnergySaverStatus 屬性取得裝置目前的節能狀態：

下列程式代碼範例會監視節能狀態，並據此設定 屬性。

private bool _isBatteryLow = false;

private void BatterySaverSwitch_Toggled(object sender, ToggledEventArgs e)
{
    // Capture the initial state of the battery
    _isBatteryLow = Battery.Default.EnergySaverStatus == EnergySaverStatus.On;
    BatterySaverLabel.Text = _isBatteryLow.ToString();

    // Watch for any changes to the battery saver mode
    Battery.Default.EnergySaverStatusChanged += Battery_EnergySaverStatusChanged;
}

private void Battery_EnergySaverStatusChanged(object sender, EnergySaverStatusChangedEventArgs e)
{
    // Update the variable based on the state
    _isBatteryLow = Battery.Default.EnergySaverStatus == EnergySaverStatus.On;
    BatterySaverLabel.Text = _isBatteryLow.ToString();
}

電源來源

屬性 PowerSource 會 BatteryPowerSource 傳回列舉，指出裝置的收費方式，如果有的話。 如果未收費，則狀態為 BatteryPowerSource.Battery。 BatteryPowerSource.AC、 BatteryPowerSource.Usb和 BatteryPowerSource.Wireless 值表示電池正在充電。

下列程式代碼範例會根據電源設定控制件的 Label 文字。

private void SetChargeModeLabel()
{
    BatteryPowerSourceLabel.Text = Battery.Default.PowerSource switch
    {
        BatteryPowerSource.Wireless => "Wireless charging",
        BatteryPowerSource.Usb => "USB cable charging",
        BatteryPowerSource.AC => "Device is plugged in to a power source",
        BatteryPowerSource.Battery => "Device isn't charging",
        _ => "Unknown"
    };
}

平台差異

本節說明電池的平臺特定差異。

無平台差異。