Xamarin.Essentials: BatterieXamarin.Essentials: Battery

La classe Battery vous permet de vérifier les informations de batterie de l’appareil et de superviser les changements. Elle fournit aussi des informations sur l’état d’économie d’énergie de l’appareil, qui indique si l’appareil s’exécute dans un mode de basse consommation.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. Les applications doivent de préférence éviter le traitement en arrière-plan lorsque l’économie d’énergie de l’appareil est activée.Applications should avoid background processing if the device's energy-saver status is on.

Prise en mainGet started

Pour commencer à utiliser cette API, lisez le Guide de prise en main de Xamarin.Essentials pour vérifier que la bibliothèque est correctement installée et configurée dans vos projets.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.

Pour accéder à la fonctionnalité de batterie, la configuration suivante spécifique à la plateforme est obligatoire.To access the Battery functionality the following platform specific setup is required.

L'autorisation Battery est obligatoire et doit être configurée dans le projet Android.The Battery permission is required and must be configured in the Android project. Elle peut être ajoutée comme suit :This can be added in the following ways:

Ouvrez le fichier AssemblyInfo.cs dans le dossier Properties et ajoutez :Open the AssemblyInfo.cs file under the Properties folder and add:

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

Ou mettez à jour le manifeste Android :OR Update Android Manifest:

Ouvrez le fichier AndroidManifest.xml dans le dossier Properties et ajoutez le code suivant dans le nœud 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" />

Vous pouvez également cliquer avec le bouton droit sur le projet Android, et ouvrir les propriétés du projet.Or right click on the Android project and open the project's properties. Sous Manifeste Android, repérez la zone "Autorisations requises : " et cochez l'autorisation Batterie.Under Android Manifest find the Required permissions: area and check the Battery permission. Cela met automatiquement à jour le fichier AndroidManifest.xml.This will automatically update the AndroidManifest.xml file.

Utilisation de BatteryUsing Battery

Ajoutez une référence à Xamarin.Essentials dans votre classe :Add a reference to Xamarin.Essentials in your class:

using Xamarin.Essentials;

Vérifiez les informations actuelles de la batterie :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;
}

Chaque fois que l’une des propriétés de la batterie change, un événement est déclenché :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}");
    }
}

Les appareils qui fonctionnent sur batterie peuvent être mis en mode faible consommation d’énergie.Devices that run on batteries can be put into a low-power energy-saver mode. Parfois, ce basculement se fait automatiquement, par exemple, lorsque la batterie est à moins de 20 % de sa capacité.Sometimes devices are switched into this mode automatically, for example, when the battery drops below 20% capacity. En mode économie d’énergie, le système d’exploitation réduit les activités qui ont tendance à épuiser la batterie.The operating system responds to energy-saver mode by reducing activities that tend to deplete the battery. Les applications peuvent aller dans ce sens en évitant le traitement en arrière-plan ou autres activités énergivores lorsque le mode économie d’énergie est activé.Applications can help by avoiding background processing or other high-power activities when energy-saver mode is on.

Vous pouvez aussi obtenir l’état d’économie d’énergie actuel de l’appareil à l’aide de la propriété statique 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;

Cette propriété retourne un membre de l’énumération EnergySaverStatus : On, Off ou Unknown.This property returns a member of the EnergySaverStatus enumeration, which is either On, Off, or Unknown. Si elle retourne On, l’application doit de préférence éviter le traitement en arrière-plan ou autres activités susceptibles de consommer beaucoup d’énergie.If the property returns On, the application should avoid background processing or other activities that might consume a lot of power.

L’application doit également installer un gestionnaire d’événements.The application should also install an event handler. La classe Battery expose un événement qui est déclenché quand l’état d’économie d’énergie change :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 l’état d’économie d’énergie devient On, l’application doit arrêter le traitement en arrière-plan.If the energy-saver status changes to On, the application should stop performing background processing. S’il passe à Unknown ou Off, elle peut reprendre le traitement en arrière-plan.If the status changes to Unknown or Off, the application can resume background processing.

Différences entre les plateformesPlatform Differences

Aucune spécificité pour cette plateforme.No platform differences.

APIAPI

Retrouvez d’autres vidéos Xamarin sur Channel 9 et YouTube.Find more Xamarin videos on Channel 9 and YouTube.