共用方式為

存取裝置感測器

  • 發行項

Browse sample. 流覽範例

裝置有各種可供您使用的感測器。 某些感測器可以偵測移動、環境中的其他變更，例如光線。 監視和回應這些感測器可讓您的應用程式動態適應裝置的使用方式。 您也可以回應感測器中的變更，並警示使用者。 本文提供 .NET 多平臺應用程式 UI （.NET MAUI） 所支援之常見感測器的簡短概觀。

裝置感測器相關類型可在命名空間中使用 Microsoft.Maui.Devices.Sensors 。

感測器速度

感測器速度會設定感測器將數據傳回應用程式的速度。 當您啟動感測器時，您會提供所需的感測器速度與 SensorSpeed 列舉：

  • Fastest
    儘快取得感測器數據（不保證會在UI線程上傳回）。

  • Game
    適合遊戲的速率（不保證會在UI線程上傳回）。

  • UI
    適用於一般使用者介面的速率。

  • Default
    適合螢幕方向變更的預設速率。

警告

一次監視太多感測器可能會影響速率感測器數據傳回您的應用程式。

在 .NET 8 中， SensorSpeed 所有平台的間隔都相同：

  • Default 會使用 200 毫秒的間隔。
  • UI 會使用 60 毫秒的間隔。
  • Game 會使用 20 毫秒的間隔。
  • Fastest 會使用5毫秒的間隔。

感測器事件處理程式

使用 Game 或 Fastest 速度 新增至感測器的事件處理程序不 保證會在UI線程上執行。 如果事件處理程式需要存取使用者介面元素，請使用 MainThread.BeginInvokeOnMainThread 方法在 UI 線程上執行該程式代碼。

加速計

加速計感測器會沿著裝置的三個軸測量裝置的加速。 感測器所報告的數據代表用戶行動裝置的方式。

介面 IAccelerometer 提供感測器的存取權，而且可透過 Accelerometer.Default 屬性取得。 IAccelerometer介面和Accelerometer類別都包含在 命名空間中Microsoft.Maui.Devices.Sensors。

開始使用

若要存取加速計功能，可能需要下列平臺特定設定：

如果您的應用程式以 Android 12+ （API 31+） 為目標，則系統會針對此感測器的數據重新整理速率設定 200 Hz 限制。 如果您的應用程式需要使用感測器速度收集感測器數據 Fastest ，您必須宣告 HIGH_SAMPLING_RATE_SENSORS 許可權。 您可以透過下列方式設定權限：

  • 新增元件型權限：

    開啟 Platform/Android/MainApplication.cs 檔案，並在 指示詞之後using新增下列元件屬性：

    [assembly: UsesPermission(Android.Manifest.Permission.HighSamplingRateSensors)]

    - 或 -

  • 更新 Android 指令清單：

    開啟 [平臺/Android/AndroidManifest.xml] 檔案，manifest然後在 節點中新增下列這一行：

    <uses-permission android:name="android.permission.HIGH_SAMPLING_RATE_SENSORS" />

    - 或 -

  • 更新指令清單編輯器中的 Android 指令清單：

    在 Visual Studio 中按兩下 [平臺/Android/AndroidManifest.xml ] 檔案，以開啟 Android 指令清單編輯器。 然後，在 [必要許可權] 底下，檢查HIGH_SAMPLING_RATE_SENSORS許可權。 這將會自動更新 AndroidManifest.xml 檔案。

注意

如果使用者使用 裝置切換關閉麥克風存取，無論是否宣告 HIGH_SAMPLING_RATE_SENSORS 許可權，動作和位置感測器一律會受到速率限制。

監視加速計感測器

若要開始監視加速計感測器，請呼叫 IAccelerometer.Start 方法。 .NET MAUI 會藉由引發 IAccelerometer.ReadingChanged 事件，將加速計數據變更傳送至您的應用程式。 IAccelerometer.Stop使用方法來停止監視感測器。 您可以使用 屬性來偵測加速計 IAccelerometer.IsMonitoring 的監視狀態，這會是 true 加速計已啟動且目前正在監視。

下列程式代碼範例示範監視加速計是否有變更：

public void ToggleAccelerometer()
{
    if (Accelerometer.Default.IsSupported)
    {
        if (!Accelerometer.Default.IsMonitoring)
        {
            // Turn on accelerometer
            Accelerometer.Default.ReadingChanged += Accelerometer_ReadingChanged;
            Accelerometer.Default.Start(SensorSpeed.UI);
        }
        else
        {
            // Turn off accelerometer
            Accelerometer.Default.Stop();
            Accelerometer.Default.ReadingChanged -= Accelerometer_ReadingChanged;
        }
    }    
}

private void Accelerometer_ReadingChanged(object sender, AccelerometerChangedEventArgs e)
{
    // Update UI Label with accelerometer state
    AccelLabel.TextColor = Colors.Green;
    AccelLabel.Text = $"Accel: {e.Reading}";
}

加速計讀數會在 G 中回報。G 是一個等於地球引力場 $（9.81 m/s^2） $（9.81 m/s^2） 所施加的重力單位。

座標系統會以其預設方向定義相對於裝置的螢幕。 當裝置的螢幕方向變更時，不會交換軸。

X 軸為水準，指向右側，Y 軸為垂直，向上點，Z 軸指向螢幕正面外部。 在此系統中，畫面後面的座標具有負 Z 值。

範例：

  • 當裝置位於桌子上平面，並將左側推向右側時， X 加速值會是正數。

  • 當裝置放在桌子上一般時，加速值為 +1.00 G 或 $（+9.81 m/s^2）$，其對應於裝置 $（0 m/s^2）$ 的加速，減去重力 $（-9.81 m/s^2）$ 的加速度，並標準化為 G。

  • 當裝置躺在桌子上，並以 A $m/s^2$ 的加速推向天空時，加速值等於 $A+9.81$ ，相當於裝置 $（+A m/s^2）$ 的加速度減去重力 $（-9.81 m/s^2）$ 的力，並以 G 正規化。

平臺特定資訊 （加速計）

沒有與加速計感測器相關的平臺特定資訊。

Barometer

晴雨錶感測器會測量環境氣壓。 感測器所報告的數據代表目前的氣壓。 此數據會在您第一次開始監視感測器時報告，然後在每次壓力變更時報告。

介面 IBarometer 提供感測器的存取權，而且可透過 Barometer.Default 屬性取得。 IBarometer介面和Barometer類別都包含在 命名空間中Microsoft.Maui.Devices.Sensors。

若要開始監視晴雨錶感測器，請呼叫 IBarometer.Start 方法。 .NET MAUI 會藉由引發 IBarometer.ReadingChanged 事件，將氣壓讀數傳送至您的應用程式。 IBarometer.Stop使用方法來停止監視感測器。 您可以使用 屬性來偵測晴雨錶 IBarometer.IsMonitoring 的監視狀態，如果目前正在監視晴雨錶，則為 true 。

壓力讀數以黑托帕斯卡表示。

下列程式代碼範例示範如何監視變更的晴雨錶：

public void ToggleBarometer()
{
    if (Barometer.Default.IsSupported)
    {
        if (!Barometer.Default.IsMonitoring)
        {
            // Turn on barometer
            Barometer.Default.ReadingChanged += Barometer_ReadingChanged;
            Barometer.Default.Start(SensorSpeed.UI);
        }
        else
        {
            // Turn off barometer
            Barometer.Default.Stop();
            Barometer.Default.ReadingChanged -= Barometer_ReadingChanged;
        }
    }
}

private void Barometer_ReadingChanged(object sender, BarometerChangedEventArgs e)
{
    // Update UI Label with barometer state
    BarometerLabel.TextColor = Colors.Green;
    BarometerLabel.Text = $"Barometer: {e.Reading}";
}

平臺特定資訊 （晴雨錶）

本節說明與晴雨錶感測器相關的平臺特定實作詳細數據。

沒有平台特定實作詳細資料。

指南針

指南針感測器會監視裝置的磁北向。

介面 ICompass 提供感測器的存取權，而且可透過 Compass.Default 屬性取得。 ICompass介面和Compass類別都包含在 命名空間中Microsoft.Maui.Devices.Sensors。

若要開始監視指南針感測器，請呼叫 ICompass.Start 方法。 .NET MAUI 會在指南針標題變更時引發 ICompass.ReadingChanged 事件。 ICompass.Stop使用方法來停止監視感測器。 您可以使用 屬性偵測指南針 ICompass.IsMonitoring 的監視狀態，如果目前正在監視指南針，將會 true 是。

下列程式代碼範例示範如何監視指南針是否有變更：

private void ToggleCompass()
{
    if (Compass.Default.IsSupported)
    {
        if (!Compass.Default.IsMonitoring)
        {
            // Turn on compass
            Compass.Default.ReadingChanged += Compass_ReadingChanged;
            Compass.Default.Start(SensorSpeed.UI);
        }
        else
        {
            // Turn off compass
            Compass.Default.Stop();
            Compass.Default.ReadingChanged -= Compass_ReadingChanged;
        }
    }
}

private void Compass_ReadingChanged(object sender, CompassChangedEventArgs e)
{
    // Update UI Label with compass state
    CompassLabel.TextColor = Colors.Green;
    CompassLabel.Text = $"Compass: {e.Reading}";
}

平臺特定資訊（指南針）

本節說明與指南針功能相關的平臺特定實作詳細數據。

Android 不提供用來擷取指南針標題的 API。 .NET MAUI 會使用加速計和磁力計感測器來計算Google 建議的磁北向。

在罕見的情況下，您可能會看到不一致的結果，因為感測器需要校正。 在 Android 上重新調整指南針會因手機型號和 Android 版本而異。 您必須在因特網上搜尋如何重新調整指南針。 以下是兩個連結，可協助重新調整指南針：

同時從您的應用程式執行多個感測器可能會損害感測器速度。

Lowpass 篩選

由於 Android 指南針值如何更新和計算，因此可能需要將值平滑化。 您可以套用 Lowpass 篩選條件，以平均角度的正弦值和餘弦值，bool applyLowPassFilter而且可以使用接受 參數的方法多載來開啟Start：

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

這隻會套用在Android平臺上，而且iOS和 Windows 上會忽略 參數。 如需詳細資訊，請參閱這個 GitHub 問題註解。

動搖

雖然本文將搖擺列為感測器，但不是。 加速 計 可用來偵測裝置何時搖動。

介面 IAccelerometer 提供感測器的存取權，而且可透過 Accelerometer.Default 屬性取得。 IAccelerometer介面和Accelerometer類別都包含在 命名空間中Microsoft.Maui.Devices.Sensors。

注意

如果您的應用程式需要使用感測器速度收集加速計感測器數據 Fastest ，您必須宣告 HIGH_SAMPLING_RATE_SENSORS 許可權。 如需詳細資訊，請參閱 加速計。

偵測搖動 API 會從加速計使用原始讀數，以計算加速。 其會使用簡易的佇列機制，偵測 3/4 的最近加速計事件是否在最後半秒內發生。 加速度是藉由從加速計新增 X、Y 和 Z 的平方（$x^2+y^2+z^2$）讀數，並將其與特定閾值進行比較來計算。

若要開始監視加速計感測器，請呼叫 IAccelerometer.Start 方法。 偵測到搖動時， IAccelerometer.ShakeDetected 會引發 事件。 IAccelerometer.Stop使用方法來停止監視感測器。 您可以使用 屬性來偵測加速計 IAccelerometer.IsMonitoring 的監視狀態，這會是 true 加速計已啟動且目前正在監視。

建議針對 使用 Game 或更快 SensorSpeed。

下列程式代碼範例示範如何監視事件的加速計 ShakeDetected ：

private void ToggleShake()
{
    if (Accelerometer.Default.IsSupported)
    {
        if (!Accelerometer.Default.IsMonitoring)
        {
            // Turn on accelerometer
            Accelerometer.Default.ShakeDetected += Accelerometer_ShakeDetected;
            Accelerometer.Default.Start(SensorSpeed.Game);
        }
        else
        {
            // Turn off accelerometer
            Accelerometer.Default.Stop();
            Accelerometer.Default.ShakeDetected -= Accelerometer_ShakeDetected;
        }
    }
}

private void Accelerometer_ShakeDetected(object sender, EventArgs e)
{
    // Update UI Label with a "shaked detected" notice, in a randomized color
    ShakeLabel.TextColor = new Color(Random.Shared.Next(256), Random.Shared.Next(256), Random.Shared.Next(256));
    ShakeLabel.Text = $"Shake detected";
}

平臺特定資訊 （搖動）

沒有與加速計感測器相關的平臺特定資訊。

迴轉儀

陀螺儀感測器測量裝置三個主要軸周圍的角度旋轉速度。

介面 IGyroscope 提供感測器的存取權，而且可透過 Gyroscope.Default 屬性取得。 IGyroscope介面和Gyroscope類別都包含在 命名空間中Microsoft.Maui.Devices.Sensors。

開始使用

若要存取陀螺儀功能，可能需要下列平臺特定設定：

如果您的應用程式以 Android 12+ （API 31+） 為目標，則系統會針對此感測器的數據重新整理速率設定 200 Hz 限制。 如果您的應用程式需要使用感測器速度收集感測器數據 Fastest ，您必須宣告 HIGH_SAMPLING_RATE_SENSORS 許可權。 您可以透過下列方式設定權限：

  • 新增元件型權限：

    開啟 Platform/Android/MainApplication.cs 檔案，並在 指示詞之後using新增下列元件屬性：

    [assembly: UsesPermission(Android.Manifest.Permission.HighSamplingRateSensors)]

    - 或 -

  • 更新 Android 指令清單：

    開啟 [平臺/Android/AndroidManifest.xml] 檔案，manifest然後在 節點中新增下列這一行：

    <uses-permission android:name="android.permission.HIGH_SAMPLING_RATE_SENSORS" />

    - 或 -

  • 更新指令清單編輯器中的 Android 指令清單：

    在 Visual Studio 中按兩下 [平臺/Android/AndroidManifest.xml ] 檔案，以開啟 Android 指令清單編輯器。 然後，在 [必要許可權] 底下，檢查HIGH_SAMPLING_RATE_SENSORS許可權。 這將會自動更新 AndroidManifest.xml 檔案。

注意

如果使用者使用 裝置切換關閉麥克風存取，無論是否宣告 HIGH_SAMPLING_RATE_SENSORS 許可權，動作和位置感測器一律會受到速率限制。

監視陀螺儀感測器

若要開始監視陀螺儀感測器，請呼叫 IGyroscope.Start 方法。 .NET MAUI 會藉由引發 IGyroscope.ReadingChanged 事件，將陀螺儀數據變更傳送至您的應用程式。 此事件所提供的數據是以 rad/秒（每秒弧度）來測量。 IGyroscope.Stop使用方法來停止監視感測器。 您可以使用 屬性來偵測陀螺儀的監視狀態，如果true陀螺儀IGyroscope.IsMonitoring已啟動且目前正在監視中，則為 。

下列程式代碼範例示範監視陀螺儀：

private void ToggleGyroscope()
{
    if (Gyroscope.Default.IsSupported)
    {
        if (!Gyroscope.Default.IsMonitoring)
        {
            // Turn on gyroscope
            Gyroscope.Default.ReadingChanged += Gyroscope_ReadingChanged;
            Gyroscope.Default.Start(SensorSpeed.UI);
        }
        else
        {
            // Turn off gyroscope
            Gyroscope.Default.Stop();
            Gyroscope.Default.ReadingChanged -= Gyroscope_ReadingChanged;
        }
    }
}

private void Gyroscope_ReadingChanged(object sender, GyroscopeChangedEventArgs e)
{
    // Update UI Label with gyroscope state
    GyroscopeLabel.TextColor = Colors.Green;
    GyroscopeLabel.Text = $"Gyroscope: {e.Reading}";
}

平臺特定資訊 （陀螺儀）

沒有與陀螺儀感測器相關的平臺特定資訊。

磁力計

磁力計感測器表示裝置相對於地球磁場的方向。

介面 IMagnetometer 提供感測器的存取權，而且可透過 Magnetometer.Default 屬性取得。 IMagnetometer介面和Magnetometer類別都包含在 命名空間中Microsoft.Maui.Devices.Sensors。

開始使用

若要存取磁力計功能，可能需要下列平臺特定設定：

如果您的應用程式以 Android 12+ （API 31+） 為目標，則系統會針對此感測器的數據重新整理速率設定 200 Hz 限制。 如果您的應用程式需要使用感測器速度收集感測器數據 Fastest ，您必須宣告 HIGH_SAMPLING_RATE_SENSORS 許可權。 您可以透過下列方式設定權限：

  • 新增元件型權限：

    開啟 Platform/Android/MainApplication.cs 檔案，並在 指示詞之後using新增下列元件屬性：

    [assembly: UsesPermission(Android.Manifest.Permission.HighSamplingRateSensors)]

    - 或 -

  • 更新 Android 指令清單：

    開啟 [平臺/Android/AndroidManifest.xml] 檔案，manifest然後在 節點中新增下列這一行：

    <uses-permission android:name="android.permission.HIGH_SAMPLING_RATE_SENSORS" />

    - 或 -

  • 更新指令清單編輯器中的 Android 指令清單：

    在 Visual Studio 中按兩下 [平臺/Android/AndroidManifest.xml ] 檔案，以開啟 Android 指令清單編輯器。 然後，在 [必要許可權] 底下，檢查HIGH_SAMPLING_RATE_SENSORS許可權。 這將會自動更新 AndroidManifest.xml 檔案。

注意

如果使用者使用 裝置切換關閉麥克風存取，無論是否宣告 HIGH_SAMPLING_RATE_SENSORS 許可權，動作和位置感測器一律會受到速率限制。

監視磁力計感測器

若要開始監視磁力計感測器，請呼叫 IMagnetometer.Start 方法。 .NET MAUI 會藉由引發 IMagnetometer.ReadingChanged 事件，將磁力計數據變更傳送至您的應用程式。 此事件所提供的數據是以 $uT$ （microteslas） 來測量。 IMagnetometer.Stop使用方法來停止監視感測器。 您可以使用 屬性來偵測磁力計的監視狀態，如果true磁力計IMagnetometer.IsMonitoring已啟動且目前正在監視中，則為 。

下列程式代碼範例示範如何監視磁力計：

private void ToggleMagnetometer()
{
    if (Magnetometer.Default.IsSupported)
    {
        if (!Magnetometer.Default.IsMonitoring)
        {
            // Turn on magnetometer
            Magnetometer.Default.ReadingChanged += Magnetometer_ReadingChanged;
            Magnetometer.Default.Start(SensorSpeed.UI);
        }
        else
        {
            // Turn off magnetometer
            Magnetometer.Default.Stop();
            Magnetometer.Default.ReadingChanged -= Magnetometer_ReadingChanged;
        }
    }
}

private void Magnetometer_ReadingChanged(object sender, MagnetometerChangedEventArgs e)
{
    // Update UI Label with magnetometer state
    MagnetometerLabel.TextColor = Colors.Green;
    MagnetometerLabel.Text = $"Magnetometer: {e.Reading}";
}

平臺特定資訊 （磁力計）

沒有與磁力計感測器相關的平臺特定資訊。

方向

方向感測器會監視 3D 空間中的裝置方向。

注意

此感測器不會用於判斷裝置的視訊顯示是否處於直向或橫向模式。 請改用 DeviceDisplay.Current.MainDisplayInfo.Orientation 屬性。 如需詳細資訊，請參閱 裝置顯示資訊。

介面 IOrientationSensor 提供感測器的存取權，而且可透過 OrientationSensor.Default 屬性取得。 IOrientationSensor介面和OrientationSensor類別都包含在 命名空間中Microsoft.Maui.Devices.Sensors。

若要開始監視方向感測器，請呼叫 IOrientationSensor.Start 方法。 .NET MAUI 會藉由引發 IOrientationSensor.ReadingChanged 事件，將方向數據變更傳送至您的應用程式。 IOrientationSensor.Stop使用方法來停止監視感測器。 您可以使用 屬性來偵測方向 IOrientationSensor.IsMonitoring 的監視狀態，也就是 true 方向已啟動且目前正在監視。

下列程式代碼範例示範監視方向感測器：

private void ToggleOrientation()
{
    if (OrientationSensor.Default.IsSupported)
    {
        if (!OrientationSensor.Default.IsMonitoring)
        {
            // Turn on orientation
            OrientationSensor.Default.ReadingChanged += Orientation_ReadingChanged;
            OrientationSensor.Default.Start(SensorSpeed.UI);
        }
        else
        {
            // Turn off orientation
            OrientationSensor.Default.Stop();
            OrientationSensor.Default.ReadingChanged -= Orientation_ReadingChanged;
        }
    }
}

private void Orientation_ReadingChanged(object sender, OrientationSensorChangedEventArgs e)
{
    // Update UI Label with orientation state
    OrientationLabel.TextColor = Colors.Green;
    OrientationLabel.Text = $"Orientation: {e.Reading}";
}

IOrientationSensor 讀數是以 Quaternion 的形式回報，它以兩個 3D 座標系統為基礎來描述裝置的方向：

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

  • 正 X 軸會以直向模式指向顯示器右側。
  • 正 Y 軸會以直向模式指向裝置頂端。
  • 正 Z 軸會指出螢幕。

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

  • 正 X 軸是地球表面的正切值，指向東點。
  • 正 Y 軸也是地球表面的正切線，指向北點。
  • 正 Z 軸與地球表面垂直，並指向上。

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

值 Quaternion 與繞軸旋轉密切相關。 如果旋轉軸是標準化向量（$a_x、a_y、a_z$），而旋轉角度為 $\theta$，則四元數的 （X、 Y、 Z、 W） 元件為：

$（a_x \times \sin（\theta/2），a_y \times \sin（\theta/2），a_z \times \sin（\theta/2），\cos（\theta/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)。

平臺特定資訊 （方向）

沒有與方向感測器相關的平臺特定資訊。