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. 如果需要确定设备的视频显示器是处于纵向模式还是横向模式,请使用可从 DeviceDisplay 类获得的 ScreenMetrics 对象的 Orientation 属性。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;

通过调用 Start 方法启用 OrientationSensor 以便监视对设备方向所做的更改,并通过调用 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()
            if (OrientationSensor.IsMonitoring)
        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.
  • Z 轴正方向与地球表面垂直并指向上边。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. 如果旋转的轴是规范化矢量 (ax, ay, az),并且旋转角度为 Θ,则四元数的 (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.


  • 如果设备平躺在桌子上,使其屏幕面朝上,设备顶部(在纵向模式下)指向北边,则会对齐这两个坐标系。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). 设备已绕地球的 Z 轴旋转 90 度。The device has been rotated 90 degrees around the Z axis of the Earth.

  • 如果设备直立,设备顶部(在纵向模式下)指向天空,设备背面朝向北边,则设备已绕 X 轴旋转 90 度。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).

  • 如果设备的左边缘在桌子上,顶部指向北边,则设备已绕 Y 轴旋转 –90 度(或绕 Y 轴负方向旋转 90 度)。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

  • 最快 – 尽快获取传感器数据(不保证在 UI 线程上返回)。Fastest – Get the sensor data as fast as possible (not guaranteed to return on UI thread).
  • 游戏 – 适合游戏的速度(不保证在 UI 线程上返回)。Game – Rate suitable for games (not guaranteed to return on UI thread).
  • 正常 – 适合屏幕方向更改的默认速率。Normal – Default rate suitable for screen orientation changes.
  • UI – 适合常规用户界面的速率。UI – Rate suitable for general user interface.

如果事件处理程序不能保证在 UI 线程上运行,并且如果事件处理程序需要访问用户界面元素,请使用 MainThread.BeginInvokeOnMainThread 方法在 UI 线程上运行该代码。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.