Xamarin.Essentials : boussoleXamarin.Essentials: Compass

La classe Compass vous permet de superviser le cap du nord magnétique de l’appareil.The Compass class lets you monitor the device's magnetic north heading.

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.

Utilisation de la boussoleUsing Compass

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

using Xamarin.Essentials;

La fonctionnalité de boussole appelle les méthodes Start et Stop pour écouter les changements relatifs à la boussole.The Compass functionality works by calling the Start and Stop methods to listen for changes to the compass. Toutes les variations peuvent être écoutées via l’événement ReadingChanged.Any changes are sent back through the ReadingChanged event. Voici un exemple :Here is an example:

public class CompassTest
{
    // Set speed delay for monitoring changes.
    SensorSpeed speed = SensorSpeed.UI;

    public CompassTest()
    {
        // Register for reading changes, be sure to unsubscribe when finished
        Compass.ReadingChanged += Compass_ReadingChanged;
    }

    void Compass_ReadingChanged(object sender, CompassChangedEventArgs e)
    {
        var data = e.Reading;
        Console.WriteLine($"Reading: {data.HeadingMagneticNorth} degrees");
        // Process Heading Magnetic North
    }

    public void ToggleCompass()
    {
        try
        {
            if (Compass.IsMonitoring)
              Compass.Stop();
            else
              Compass.Start(speed);
        }
        catch (FeatureNotSupportedException fnsEx)
        {
            // Feature not supported on device
        }
        catch (Exception ex)
        {
            // Some other exception has occurred
        }
    }
}

Vitesse de capteurSensor Speed

  • Le plus rapide : obtenir les données de capteur aussi rapidement que possible (aucune garantie de retour sur le thread d’interface utilisateur).Fastest – Get the sensor data as fast as possible (not guaranteed to return on UI thread).
  • Jeu : débit adapté aux jeux (aucune garantie de retour sur le thread d’interface utilisateur).Game – Rate suitable for games (not guaranteed to return on UI thread).
  • Normal : débit par défaut adapté aux changements d’orientation de l’écran.Normal – Default rate suitable for screen orientation changes.
  • UI : débit adapté à une interface utilisateur général.UI – Rate suitable for general user interface.

Si votre gestionnaire d’événements ne garantit pas l’exécution sur le thread d’interface utilisateur et si le gestionnaire d’événements doit accéder aux éléments de l’interface utilisateur, utilisez la méthode MainThread.BeginInvokeOnMainThread pour exécuter ce code sur le thread d’interface utilisateur.If your event handler is not guaranteed to run on the UI thread, and if the event handler needs to access user-interface elements, use the MainThread.BeginInvokeOnMainThread method to run that code on the UI thread.

Caractéristiques de mise en œuvre de la plateformePlatform Implementation Specifics

Android ne fournit pas d’API pour récupérer le cap de la boussole.Android does not provide a API for retrieving the compass heading. Nous utilisons l’accéléromètre et le magnétomètre pour calculer le cap du nord magnétique, ce qui est recommandé par Google.We utilize the accelerometer and magnetometer to calculate the magnetic north heading, which is recommended by Google.

Dans de rares cas, vous constaterez peut-être des résultats incohérents, car les capteurs doivent être étalonnés, ce qui implique de bouger votre appareil en formant un 8.In rare instances, you maybe see inconsistent results because the sensors need to be calibrated, which involves moving your device in a figure-8 motion. Pour ce faire, ouvrez Google Maps, appuyez sur le point correspondant à votre position, puis sélectionnez Calibrate compass (Étalonner la boussole).The best way of doing this is to open Google Maps, tap on the dot for your location, and select Calibrate compass.

Sachez que l’exécution simultanée de plusieurs capteurs à partir de votre application peut modifier la vitesse du capteur.Be aware that running multiple sensors from your app at the same time may adjust the sensor speed.

Filtre passe-basLow Pass Filter

En raison du mode de mise à jour et de calcul des valeurs de la boussole Android, il peut s’avérer nécessaire d’affiner ces valeurs.Due to how the Android compass values are updated and calculated there may be a need to smooth out the values. Vous pouvez appliquer un filtre passe-bas qui fait la moyenne des valeurs de sinus et de cosinus des angles, en utilisant la surcharge de méthode Start qui accepte le paramètre bool applyLowPassFilter :A Low Pass Filter can be applied that averages the sine and cosine values of the angles and can be turned on by using the Start method overload which accepts the bool applyLowPassFilter parameter:

Compass.Start(SensorSpeed.UI, applyLowPassFilter: true);

Il est appliqué uniquement sur la plateforme Android et le paramètre est ignoré sur iOS et UWP.This is only applied on the Android platform, and the parameter is ignored on iOS and UWP. Vous trouverez plus d’informations ici.More information can be read here.

APIAPI