Xamarin.Essentials:バッテリXamarin.Essentials: Battery

Battery クラスでは、デバイスのバッテリ情報を確認し、変更を監視し、デバイスが省電力モードで実行されているかどうかを示す、デバイスの省電力状態に関する情報を提供できます。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. デバイスの省電力状態がオンになっている場合、アプリケーションはバックグラウンド処理を避ける必要があります。Applications should avoid background processing if the device's energy-saver status is on.

作業開始Get started

この API の使用を始めるには、Xamarin.Essentials の概要ガイドを読み、ライブラリが正しくインストールされてプロジェクトに設定されていることを確認してください。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.

Battery の機能にアクセスするには、次のプラットフォーム固有の設定が必要です。To access the Battery functionality the following platform specific setup is required.

Battery アクセス許可が必要です。Android プロジェクト内で構成する必要があります。The Battery permission is required and must be configured in the Android project. これは次の方法で追加できます。This can be added in the following ways:

[プロパティ] フォルダーにある AssemblyInfo.cs ファイルを開き、以下を追加します。Open the AssemblyInfo.cs file under the Properties folder and add:

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

または、Android マニフェストを追加します。OR Update Android Manifest:

[プロパティ] フォルダーにある AndroidManifest.xml ファイルを開き、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" />

または、Android プロジェクトを右クリックし、プロジェクトのプロパティを開きます。Or right click on the Android project and open the project's properties. [Android マニフェスト] の下で [必要なアクセス許可:] 領域を探し、Battery アクセス許可をオンにします。Under Android Manifest find the Required permissions: area and check the Battery permission. これにより、AndroidManifest.xml ファイルが自動的に更新されます。This will automatically update the AndroidManifest.xml file.

Battery の使用Using Battery

自分のクラスの Xamarin.Essentials に参照を追加します。Add a reference to Xamarin.Essentials in your class:

using Xamarin.Essentials;

現在のバッテリに関する情報を確認します。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;
}

バッテリのプロパティのいずれかが変化するたびに、イベントがトリガーされます。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}");
    }
}

バッテリで動作するデバイスは、低電力の省電力モードに切り替えることができます。Devices that run on batteries can be put into a low-power energy-saver mode. デバイスが自動的にこのモードに切り替わる場合があります。たとえば、バッテリ残量が 20% を下回ったときなどです。Sometimes devices are switched into this mode automatically, for example, when the battery drops below 20% capacity. オペレーティング システムは、バッテリを消耗させる傾向があるアクティビティを減らすことで、省電力モードに対応します。The operating system responds to energy-saver mode by reducing activities that tend to deplete the battery. アプリケーションでは、バックグラウンド処理やその他の電力消費の大きいアクティビティを回避することで、省電力モードがオンになった場合をサポートできます。Applications can help by avoiding background processing or other high-power activities when energy-saver mode is on.

静的プロパティ 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;

このプロパティは EnergySaverStatus 列挙型のメンバーを返します。それは OnOff、または Unknown です。This property returns a member of the EnergySaverStatus enumeration, which is either On, Off, or Unknown. プロパティが On を返す場合、アプリケーションでは、バックグラウンド処理やその他の電力消費の大きいアクティビティを回避する必要があります。If the property returns On, the application should avoid background processing or other activities that might consume a lot of power.

アプリケーションでは、イベント ハンドラーもインストールする必要があります。The application should also install an event handler. Battery クラスでは、省電力状態が変更されたときにトリガーされるイベントが公開されています。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;
    }
}

省電力の状態が On に変わった場合、アプリケーションはバックグラウンド処理の実行を停止させる必要があります。If the energy-saver status changes to On, the application should stop performing background processing. 状態が Unknown または Off に変わった場合、アプリケーションはバックグラウンド処理を再開することができます。If the status changes to Unknown or Off, the application can resume background processing.

プラットフォームによる違いPlatform Differences

プラットフォームによる違いはありません。No platform differences.

APIAPI

他の Xamarin ビデオは、Channel 9 および YouTube でご覧いただけます。Find more Xamarin videos on Channel 9 and YouTube.