Xamarin.Essentials: OrientationSensorXamarin.Essentials: OrientationSensor

La clase OrientationSensor permite supervisar la orientación de un dispositivo en un espacio tridimensional.The OrientationSensor class lets you monitor the orientation of a device in three dimensional space.

Nota

Esta clase se usa para determinar la orientación de un dispositivo en un espacio tridimensional.This class is for determining the orientation of a device in 3D space. Si tiene que determinar si la visualización de vídeo del dispositivo está en modo vertical u horizontal, use la propiedad Orientation del objeto ScreenMetrics disponible en la clase DeviceDisplay.If you need to determine if the device's video display is in portrait or landscape mode, use the Orientation property of the ScreenMetrics object available from the DeviceDisplay class.

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.

Uso de OrientationSensorUsing OrientationSensor

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

using Xamarin.Essentials;

OrientationSensor se habilita mediante una llamada al método Start para supervisar los cambios en la orientación del dispositivo y se deshabilita al llamar al método Stop.The OrientationSensor is enabled by calling the Start method to monitor changes to the device's orientation, and disabled by calling the Stop method. Los cambios se enviarán a través del evento ReadingChanged.Any changes are sent back through the ReadingChanged event. Este es un uso de ejemplo:Here is a sample usage:


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

    public OrientationSensorTest()
    {
        // Register for reading changes, be sure to unsubscribe when finished
        OrientationSensor.ReadingChanged += OrientationSensor_ReadingChanged;
    }

    void OrientationSensor_ReadingChanged(object sender, OrientationSensorChangedEventArgs e)
    {
        var data = e.Reading;
        Console.WriteLine($"Reading: X: {data.Orientation.X}, Y: {data.Orientation.Y}, Z: {data.Orientation.Z}, W: {data.Orientation.W}");
        // Process Orientation quaternion (X, Y, Z, and W)
    }

    public void ToggleOrientationSensor()
    {
        try
        {
            if (OrientationSensor.IsMonitoring)
                OrientationSensor.Stop();
            else
                OrientationSensor.Start(speed);
        }
        catch (FeatureNotSupportedException fnsEx)
        {
            // Feature not supported on device
        }
        catch (Exception ex)
        {
            // Other error has occurred.
        }
    }
}

Las lecturas de OrientationSensor se informan como un Quaternion que describe la orientación del dispositivo en función de dos sistemas de coordenadas tridimensionales:OrientationSensor readings are reported back in the form of a Quaternion that describes the orientation of the device based on two 3D coordinate systems:

El dispositivo (generalmente un teléfono o tableta) tiene un sistema de coordenadas tridimensional con los siguientes ejes:The device (generally a phone or tablet) has a 3D coordinate system with the following axes:

  • El eje X positivo apunta a la derecha de la visualización en modo vertical.The positive X axis points to the right of the display in portrait mode.
  • El eje Y positivo apunta a la parte de arriba del dispositivo en modo horizontal.The positive Y axis points to the top of the device in portrait mode.
  • El eje Z positivo apunta fuera de la pantalla.The positive Z axis points out of the screen.

El sistema de coordenadas tridimensional de la Tierra tiene estos ejes:The 3D coordinate system of the Earth has the following axes:

  • El eje X positivo es tangente a la superficie de la Tierra y apunta al este.The positive X axis is tangent to the surface of the Earth and points east.
  • El eje Y positivo también es tangente a la superficie de la Tierra y apunta al norte.The positive Y axis is also tangent to the surface of the Earth and points north.
  • El eje Z positivo es perpendicular a la superficie de la Tierra y apunta hacia arriba.The positive Z axis is perpendicular to the surface of the Earth and points up.

Quaternion describe la rotación del sistema de coordenadas del dispositivo en relación con el sistema de coordenadas de la Tierra.The Quaternion describes the rotation of the device's coordinate system relative to the Earth's coordinate system.

Un valor Quaternion está estrechamente relacionado con la rotación alrededor de un eje.A Quaternion value is very closely related to rotation around an axis. Si un eje de rotación es el vector normalizado (ax, ay, az) y el ángulo de rotación es Θ, los componentes (X, Y, Z, W) del cuaternión son:If an axis of rotation is the normalized vector (ax, ay, az), and the rotation angle is Θ, then the (X, Y, Z, W) components of the quaternion are:

(ax·sin(Θ/2), ay·sin(Θ/2), az·sin(Θ/2), cos(Θ/2))(ax·sin(Θ/2), ay·sin(Θ/2), az·sin(Θ/2), cos(Θ/2))

Estos son los sistemas de coordenadas de la derecha por lo que, con el pulgar de la mano derecha apuntando en la dirección positiva del eje de rotación, la curva de los dedos indica la dirección de la rotación de los ángulos positivos.These are right-hand coordinate systems, so with the thumb of the right hand pointed in the positive direction of the rotation axis, the curve of the fingers indicate the direction of rotation for positive angles.

Ejemplos:Examples:

  • Cuando el dispositivo está pantalla arriba sobre una mesa, con la parte superior del mismo (en el modo vertical) apuntando al norte, los dos sistemas de coordenadas están alineados.When the device lies flat on a table with its screen facing up, with the top of the device (in portrait mode) pointing north, the two coordinate systems are aligned. El valor Quaternion representa el cuaternión de identidad (0, 0, 0, 1).The Quaternion value represents the identity quaternion (0, 0, 0, 1). Todas las rotaciones se pueden analizar en relación con esta posición.All rotations can be analyzed relative to this position.

  • Cuando el dispositivo está pantalla arriba sobre una mesa y la parte superior del mismo (en el modo vertical) apunta al oeste, el valor de Quaternion es (0, 0, 0.707, 0.707).When the device lies flat on a table with its screen facing up, and the top of the device (in portrait mode) pointing west, the Quaternion value is (0, 0, 0.707, 0.707). El dispositivo se giró 90 grados alrededor del eje Z de la Tierra.The device has been rotated 90 degrees around the Z axis of the Earth.

  • Cuando el dispositivo se sostiene de manera vertical, con la parte superior (en el modo vertical) apuntando al cielo y la parte posterior orientada al norte, es porque el dispositivo se giró 90 grados alrededor del eje X.When the device is held upright so that the top (in portrait mode) points towards the sky, and the back of the device faces north, the device has been rotated 90 degrees around the X axis. El valor de Quaternion es (0.707, 0, 0, 0.707).The Quaternion value is (0.707, 0, 0, 0.707).

  • Si el dispositivo se coloca de manera tal que el borde izquierdo esté sobre una mesa y la parte superior apunte al norte, es porque el dispositivo se giró –90 grados alrededor del eje Y (o 90 grados alrededor del eje Y negativo).If the device is positioned so its left edge is on a table, and the top points north, the device has been rotated –90 degrees around the Y axis (or 90 degrees around the negative Y axis). El valor de Quaternion es (0, -0.707, 0, 0.707).The Quaternion value is (0, -0.707, 0, 0.707).

Velocidad de sensorSensor Speed

  • Más rápido: obtener los datos del sensor tan rápido como sea posible (no se garantiza la devolución en el subproceso de interfaz de usuario).Fastest – Get the sensor data as fast as possible (not guaranteed to return on UI thread).
  • Juego: velocidad adecuada para juegos (no se garantiza la devolución en el subproceso de interfaz de usuario).Game – Rate suitable for games (not guaranteed to return on UI thread).
  • Normal: velocidad predeterminada adecuada para los cambios de orientación de pantalla.Normal – Default rate suitable for screen orientation changes.
  • Interfaz de usuario: velocidad adecuada para la interfaz de usuario general.UI – Rate suitable for general user interface.

Si no se garantiza la ejecución del controlador de eventos en el subproceso de interfaz de usuario y si el controlador de eventos necesita tener acceso a elementos de la interfaz de usuario, use el método MainThread.BeginInvokeOnMainThread para ejecutar ese código en el subproceso de interfaz de usuario.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.

APIAPI