Xamarin.Essentials: OrientationSensorXamarin.Essentials: OrientationSensor

Класс OrientationSensor позволяет наблюдать за ориентацией устройства в трехмерном пространстве.The OrientationSensor class lets you monitor the orientation of a device in three dimensional space.

Примечание

Этот класс предназначен для определения расположения устройства в трехмерном пространстве.This class is for determining the orientation of a device in 3D space. Если вам нужно определить, в какой ориентации отображается видео на устройстве (книжной или альбомной), используйте свойство Orientation объекта ScreenMetrics, который доступен из класса 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.

Начало работы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.

Использование OrientationSensorUsing OrientationSensor

Добавьте в свой класс ссылку на Xamarin.Essentials:Add a reference to Xamarin.Essentials in your class:

using Xamarin.Essentials;

OrientationSensor включается вызовом метода Start для отслеживания изменений в ориентации устройства и отключается методом 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. Все изменения возвращаются через событие ReadingChanged.Any changes are sent back through the ReadingChanged event. Вот простой пример использования: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.
        }
    }
}

Показания OrientationSensor возвращаются в виде Quaternionс описанием ориентации устройства в двух трехмерных системах координат:OrientationSensor readings are reported back in the form of a Quaternion that describes the orientation of the device based on two 3D coordinate systems:

Устройство (обычно это телефон или планшет) использует трехмерную систему координат со следующими осями:The device (generally a phone or tablet) has a 3D coordinate system with the following axes:

  • Положительное значение X обозначает направление вправо от экрана в книжной ориентации.The positive X axis points to the right of the display in portrait mode.
  • Положительное значение Y обозначает направление вверх от устройства в книжной ориентации.The positive Y axis points to the top of the device in portrait mode.
  • Положительное значение Z обозначает направление вперед перпендикулярно экрану.The positive Z axis points out of the screen.

Трехмерная система координат относительно Земли имеет следующие оси:The 3D coordinate system of the Earth has the following axes:

  • Положительное значение X указывает на восток по касательной к поверхности Земли.The positive X axis is tangent to the surface of the Earth and points east.
  • Положительное значение Y указывает на север по касательной к поверхности Земли.The positive Y axis is also tangent to the surface of the Earth and points north.
  • Положительное значение X указывает вверх перпендикулярно поверхности Земли.The positive Z axis is perpendicular to the surface of the Earth and points up.

Quaternion описывает вращение системы координат устройства по отношению к системе координат Земли.The Quaternion describes the rotation of the device's coordinate system relative to the Earth's coordinate system.

Значение Quaternion очень тесно связано с поворотом вокруг оси.A Quaternion value is very closely related to rotation around an axis. Если ось вращения обозначить нормализованным вектором (x,y,z), а угол поворота — Θ, то компоненты кватерниона (X, Y, Z, W) вычисляются следующим образом: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))

Это правосторонние системы координат: если направить большой палец правой руки в направлении положительного изменения координат по оси вращения, изгиб пальцев будет указывать направление вращения с положительным значением угла поворота.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.

ПримерыExamples:

  • Если устройство лежит горизонтально на столе экраном вверх и при этом верхний край устройства (в книжной ориентации) указывает на север, эти системы координат совпадают.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. Значение Quaternion представляет единичный кватернион (0, 0, 0, 1).The Quaternion value represents the identity quaternion (0, 0, 0, 1). Все повороты можно анализировать относительно этой позиции.All rotations can be analyzed relative to this position.

  • Если устройство лежит горизонтально на столе экраном вверх и при этом верхний край устройства (в книжной ориентации) указывает на запад, Quaternion принимает значение (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). Это означает, что устройство повернуто на 90 градусов вокруг оси Z в системе координат Земли.The device has been rotated 90 degrees around the Z axis of the Earth.

  • Когда устройство удерживается вертикально так, что его верхняя часть (в книжной ориентации) направлена вверх, к небу, а задняя панель устройства расположена с северной стороны, устройство считается повернутым на 90 градусов вокруг оси 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. Значение Quaternion равно (0,707, 0, 0, 0,707).The Quaternion value is (0.707, 0, 0, 0.707).

  • Если устройство размещается так, что его левый край размещен на столе, в верхней край указывает на север, устройство считается повернутым на –90 градусов вокруг оси Y (или на 90 градусов вокруг отрицательной оси Y).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). Значение Quaternion равно (0, -0,707, 0, 0,707).The Quaternion value is (0, -0.707, 0, 0.707).

Скорость датчикаSensor Speed

  • Fastest (Максимальная) — максимально быстрое получение данных датчика (возврат в поток пользовательского интерфейса не гарантирован).Fastest – Get the sensor data as fast as possible (not guaranteed to return on UI thread).
  • Game (Игра) — скорость, подходящая для игр (возврат в поток пользовательского интерфейса не гарантирован).Game – Rate suitable for games (not guaranteed to return on UI thread).
  • Normal (Нормальная) — скорость по умолчанию, которая подходит для изменений ориентации экрана.Normal – Default rate suitable for screen orientation changes.
  • UI (Пользовательский интерфейс) — скорость, которая подходит для типичного пользовательского интерфейса.UI – Rate suitable for general user interface.

Если нет гарантии, что обработчик событий будет запущен в потоке пользовательского интерфейса, и этому обработчику событий требуется доступ к элементам интерфейса, используйте метод MainThread.BeginInvokeOnMainThread для запуска кода в потоке пользовательского интерфейса.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