Xamarin.Essentials：OrientationSensor

  • 發行項

OrientationSensor 類別可讓您監視裝置在三維空間中的方向。

注意

此類別可用來判斷裝置在 3D 空間中的方向。 若需要判斷裝置的影片顯示器是直向或橫向模式，請使用 ScreenMetrics 物件 (位於 DeviceDisplay 類別) 中的 Orientation 屬性。

開始使用

若要開始使用此 API，請閱讀 入門指南Xamarin.Essentials，以確保連結庫已正確安裝並設定在您的專案中。

使用 OrientationSensor

在類別中新增 的 Xamarin.Essentials 參考：

using Xamarin.Essentials;

OrientationSensor 的啟用方式是呼叫 Start 方法以監視裝置方向的變更，並透過呼叫 Stop 方法來停用。 所有變化都會透過 ReadingChanged 事件傳回。 以下是範例使用方式：


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 的形式回報，它以兩個 3D 座標系統為基礎來描述裝置的方向：

裝置 (通常是手機或平板電腦) 具有含有下列座標軸的 3D 座標系統：

  • 正 X 軸指向直向模式顯示器的右邊。
  • 正 Y 軸指向直向模式顯示器的上方。
  • 正 Z 軸指向螢幕背面方向。

地球的 3D 座標系統有下列座標軸：

  • 正 X 軸與地球表面相切並指向東邊。
  • 正 Y 軸也與地球表面相切並指向北邊。
  • 正 Z 軸與地球表面垂直並指向上方。

Quaternion 描述裝置座標系統相對於地球座標系統的旋轉。

Quaternion 值非常接近於繞著軸旋轉。 若旋轉軸是正規化向量 (x、y、z) 且旋轉角度是 Θ，則四元數的 (X, Y, Z, W) 分量是：

(x·sin(Θ/2)、y·sin(Θ/2)、z·sin(Θ/2), cos(Θ/2))

這些是右手座標系統，因此右手的拇指指向旋轉軸的正方向，食指的曲線指出正角度的旋轉方向。

範例：

  • 當裝置平放在桌上且螢幕朝上，且裝置頂端 (直向模式) 指向北邊時，兩個座標系統相對齊。 Quaternion 值代表識別四元數 (0, 0, 0, 1)。 所有旋轉都能以相對於此位置的方式來分析。

  • 當裝置平放在桌上且螢幕朝上，且裝置頂端 (直向模式) 指向西邊時，Quaternion 值是 (0, 0, 0.707, 0.707)。 裝置已沿地球的 Z 軸旋轉 90 度。

  • 當以正常方式拿裝置使得其頂端 (直向模式) 指向天空，且裝置的背面朝向北邊，則裝置已沿 X 軸旋轉 90 度。 Quaternion 值是 (0.707, 0, 0, 0.707)。

  • 如果裝置位於表格上，且頂點為北端，則裝置已繞 Y 軸旋轉 –90 度（或負 Y 軸周圍 90 度）。 Quaternion 值是 (0, -0.707, 0, 0.707)。

感應器速度

  • 最快 – 以最快的方式取得感應器資料 (不保證在 UI 執行緒上傳回)。
  • 遊戲 – 適合遊戲的費率 (不保證在 UI 執行緒上傳回)。
  • 預設值 – 適合螢幕方向變更的預設速率。
  • UI – 適合一般使用者介面的費率。

若您的事件處理常式不保證在 UI 執行緒上執行，且若事件處理常式需要存取使用者介面元素，請使用 MainThread.BeginInvokeOnMainThread 方法在 UI 執行緒上執行程式碼。

API