Xamarin.Essentials: BateríaXamarin.Essentials: Battery

La clase Battery le permite comprobar la información sobre la batería del dispositivo y supervisar los cambios. Además, ofrece información sobre el estado de ahorro de energía del dispositivo, que indica si este se está ejecutando en el modo de bajo consumo.The Battery class lets you check the device's battery information and monitor for changes and provides information about the device's energy-saver status, which indicates if the device is running in a low-power mode. Las aplicaciones deben evitar el procesamiento en segundo plano si el estado de ahorro de energía del dispositivo está activado.Applications should avoid background processing if the device's energy-saver status is on.

Primeros pasosGet started

Para empezar a usar esta API, lea la guía de introducción para Xamarin.Essentials con el fin de asegurarse de que la biblioteca está correctamente instalada y configurada en los proyectos.To start using this API, read the getting started guide for Xamarin.Essentials to ensure the library is properly installed and set up in your projects.

Para acceder a la funcionalidad de Battery, se requiere la siguiente configuración específica para la plataforma.To access the Battery functionality the following platform specific setup is required.

El permiso Battery es necesario y se debe configurar en el proyecto Android.The Battery permission is required and must be configured in the Android project. Se puede agregar de las siguientes maneras:This can be added in the following ways:

Abra el archivo AssemblyInfo.cs de la carpeta Propiedades y agregue lo siguiente:Open the AssemblyInfo.cs file under the Properties folder and add:

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

O BIEN, actualice el manifiesto de Android:OR Update Android Manifest:

Abra el archivo AndroidManifest.xml de la carpeta Propiedades y agregue lo siguiente dentro del nodo manifest.Open the AndroidManifest.xml file under the Properties folder and add the following inside of the manifest node.

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

O haga clic con el botón derecho en el proyecto de Android y abra las propiedades del proyecto.Or right click on the Android project and open the project's properties. En Manifiesto de Android, busque el área Permisos requeridos: y active el permiso Battery (Batería).Under Android Manifest find the Required permissions: area and check the Battery permission. Esto actualizará automáticamente el archivo AndroidManifest.xml.This will automatically update the AndroidManifest.xml file.

Uso de BatteryUsing Battery

Agregue una referencia a Xamarin.Essentials en su clase:Add a reference to Xamarin.Essentials in your class:

using Xamarin.Essentials;

Compruebe la información actual de la batería:Check current battery information:

var level = Battery.ChargeLevel; // returns 0.0 to 1.0 or 1.0 when on AC or no battery.

var state = Battery.State;

switch (state)
{
    case BatteryState.Charging:
        // Currently charging
        break;
    case BatteryState.Full:
        // Battery is full
        break;
    case BatteryState.Discharging:
    case BatteryState.NotCharging:
        // Currently discharging battery or not being charged
        break;
    case BatteryState.NotPresent:
        // Battery doesn't exist in device (desktop computer)
    case BatteryState.Unknown:
        // Unable to detect battery state
        break;
}

var source = Battery.PowerSource;

switch (source)
{
    case BatteryPowerSource.Battery:
        // Being powered by the battery
        break;
    case BatteryPowerSource.AC:
        // Being powered by A/C unit
        break;
    case BatteryPowerSource.Usb:
        // Being powered by USB cable
        break;
    case BatteryPowerSource.Wireless:
        // Powered via wireless charging
        break;
    case BatteryPowerSource.Unknown:
        // Unable to detect power source
        break;
}

Cada vez que se cambia cualquiera de las propiedades de la batería, se desencadena un evento:Whenever any of the battery's properties change an event is triggered:

public class BatteryTest
{
    public BatteryTest()
    {
        // Register for battery changes, be sure to unsubscribe when needed
        Battery.BatteryInfoChanged += Battery_BatteryInfoChanged;
    }

    void Battery_BatteryInfoChanged(object sender, BatteryInfoChangedEventArgs   e)
    {
        var level = e.ChargeLevel;
        var state = e.State;
        var source = e.PowerSource;
        Console.WriteLine($"Reading: Level: {level}, State: {state}, Source: {source}");
    }
}

Es posible poner los dispositivos que usan baterías en el modo de ahorro en caso de baja energía.Devices that run on batteries can be put into a low-power energy-saver mode. A veces, los dispositivos cambian automáticamente a este modo, por ejemplo, cuando la batería cae por debajo del 20 % de su capacidad.Sometimes devices are switched into this mode automatically, for example, when the battery drops below 20% capacity. El sistema operativo responde al modo de ahorro de energía reduciendo las actividades que tienden a agotar la batería.The operating system responds to energy-saver mode by reducing activities that tend to deplete the battery. Para ayudar, las aplicaciones pueden evitar el procesamiento en segundo plano u otras actividades de alta potencia cuando el modo de ahorro de energía está activado.Applications can help by avoiding background processing or other high-power activities when energy-saver mode is on.

También puede conocer el estado de ahorro de energía actual del dispositivo con la propiedad estática Battery.EnergySaverStatus:You can also obtain the current energy-saver status of the device using the static Battery.EnergySaverStatus property:

// Get energy saver status
var status = Battery.EnergySaverStatus;

Esta propiedad devuelve un miembro de la enumeración EnergySaverStatus, que es On, Off o Unknown.This property returns a member of the EnergySaverStatus enumeration, which is either On, Off, or Unknown. Si la propiedad devuelve On, la aplicación debe evitar el procesamiento en segundo plano o cualquier otra actividad que pueda tener un consumo energético grande.If the property returns On, the application should avoid background processing or other activities that might consume a lot of power.

La aplicación también debe instalar un controlador de eventos.The application should also install an event handler. La clase Battery expone un evento que se desencadena cuando cambia el estado de ahorro de energía:The Battery class exposes an event that is triggered when the energy-saver status changes:

public class EnergySaverTest
{
    public EnergySaverTest()
    {
        // Subscribe to changes of energy-saver status
        Battery.EnergySaverStatusChanged += OnEnergySaverStatusChanged;
    }

    private void OnEnergySaverStatusChanged(EnergySaverStatusChangedEventArgs e)
    {
        // Process change
        var status = e.EnergySaverStatus;
    }
}

Si el estado de ahorro de energía cambia a On, la aplicación debe detener el procesamiento en segundo plano.If the energy-saver status changes to On, the application should stop performing background processing. Si el estado cambia a Unknown o Off, la aplicación puede reanudar el procesamiento en segundo plano.If the status changes to Unknown or Off, the application can resume background processing.

Diferencias entre plataformasPlatform Differences

No hay diferencias entre las plataformas.No platform differences.

APIAPI

Obtenga más información sobre The Xamarin Show en Channel 9 y YouTube.Find more of The Xamarin Show on Channel 9 and YouTube.