Android 觸覺回饋 API 參考資料

本節將介紹 Android 提供的各種觸覺 API。也會說明檢查任何必要裝置支援的時機和方式，確保您的觸覺效果可以如預期播放。

有幾種不同的方式可以建立觸覺效果，在選擇觸覺效果時，請務必考量 Android 觸覺技術的設計原則。下表摘要說明每個方法的這些高階屬性：

  • 在規劃行為回退時，可用性特別重要，需要與檢查個別裝置支援情況搭配使用。
  • 清楚觸覺技術是一種簡潔明瞭的感覺，不會對使用者造成困擾。
  • 豐富的觸覺技術較具表達能力，通常需要功能更豐富的硬體。
API 介面 產品供應資訊 清晰觸覺回饋 豐富的觸覺回饋
HapticFeedbackConstants Android 1.5 以上版本
(每個常數)
預先定義的 VibrationEffect Android 10 以上版本
VibrationEffect 組成 Android 11 以上版本 (每個常數)
開啟/關閉、一次性和波形震動 Android 1

此外，本頁所述的通知 API 可讓您自訂傳入通知的觸覺效果。

本頁也會說明橫跨 API 介面的其他概念：

HapticFeedbackConstants

HapticFeedbackConstants 類別提供動作常數，可讓應用程式新增整個裝置體驗一致的觸覺回饋，而非每個應用程式對常見動作產生不同的效果。

相容性和需求

使用 View.performHapticFeedback 方法搭配這些常數，不需要應用程式的任何特殊權限。該屬性適用 View.hapticFeedbackEnabled 屬性，如果設為 false，就會停用檢視畫面的所有觸覺回饋呼叫，包括預設呼叫。如果設為 false，主要相關設定會停用 View.hapticFeedbackEnabled 屬性，這會停用檢視畫面上所有的觸覺回饋呼叫，包括預設權限。這個方法也會依據使用者的系統設定，啟用觸控回饋功能。

唯一的相容性考量是動作中特定常數的 SDK 級別。

使用 HapticFeedbackConstants 時，不需要提供備用行為。

「HapticsFeedbackConstants」的用量

如要進一步瞭解如何使用 HapticFeedbackConstants，請參閱「為事件新增觸覺回饋」。

預先定義的VibrationEffect

VibrationEffect 類別提供數個預先定義的常數，例如 CLICK、TICK 和 DOUBLE_CLICK。這些效果可能已根據裝置進行最佳化調整。

相容性和需求

想播放任何 VibrationEffect 時，需要應用程式資訊清單中的 VIBRATE 權限。

使用預先定義的 VibrationEffect 時，您不需要提供備用行為，因為沒有裝置最佳化實作的常數會還原為標準平台備用項目。

Vibrator.areEffectsSupported 和 Vibrator.areAllEffectsSupported API 用於判斷是否有裝置最佳化實作。即使未經過最佳化實作，仍然可以使用預先定義的「效果」，並且使用標準平台備用服務。因此，只有在應用程式希望考量效果是否已針對裝置進行最佳化調整時，才需要這些 areEffectsSupported API。

效果檢查方法可能會傳回下列三個值其中之一：

UNKNOWN 值表示檢查 API 無法使用，因此系統通常會針對所有效果傳回該 API，或是完全不傳回這類 API。這些裝置會以動態方式恢復運作。

使用預先定義的 VibrationEffect

如要進一步瞭解如何使用預先定義的 VibrationEffect，請參閱「使用預先定義的 VibrationEffect 產生觸覺回饋」。

VibrationEffect構圖

VibrationEffect 組合是使用 VibrationEffect.startComposition API 建立的震動效果。這個 API 可以透過建立一系列可自訂延遲和強度的原始基元，進行更生動的觸覺回饋。但請特別留意，確保裝置支援結合使用的功能，避免整體體驗不一致。

相容性和需求

想播放任何 VibrationEffect 時，需要應用程式資訊清單中的 VIBRATE 權限。

並非所有裝置都支援組合 API 的所有功能，因此請務必確保可使用基本功能。

檢查震動基本支援

您可以使用 Vibrator.arePrimitivesSupported 方法擷取個別支援。您也可以使用 Vibrator.areAllPrimitivesSupported 方法一併檢查一組原始版本，這相當於使用 AND 的基本支援。

使用 VibrationEffect 個樂曲

如要進一步瞭解如何使用 VibrationEffect 組合，請參閱「建立震動組成」。

開啟、單次和波形震動

Android 支援最舊的震動形式，是簡易的震動模式，可設定時間長度。這些 API 通常不符合觸覺技術設計原則，因為這類 API 可以產生震動觸覺回饋；除非是不得已時才使用，

關閉震動最常見的用途為通知，而不需要震動。波形震動功能也能專門允許模式無限期重複，就像您可能想出鈴聲。

「單樣本模式」是指 N 毫秒振動一次。

波形模式有兩種類型：

  • 限時活動。此類型的波形描述交替持續時間和持續時間。時間始於閒置時間長度。因此，波形模式通常會從零值開始，表示要立即開始震動。
  • 色調和振幅此類型的波形有額外的振幅陣列，以便與每個時間數字進行比對，而不會採用第一個形式的隱含作用。然而，請務必檢查裝置是否支援振幅的控制項，以確保能夠達成您想要的資源調度。

相容性和需求

「關閉震動」是最舊的震動形式，這類震動功能可在所有「具有震動功能」的裝置上運作，詳情請參閱本頁後續內容。

要播放任何 VibrationEffect 或較舊的樣式 vibrate 呼叫，都需要應用程式資訊清單中的 VIBRATE 權限。

在波形中使用不同振幅值時，強烈建議您確保裝置支援振幅控制。

檢查振幅控制支援

在無振幅控制的裝置上，非零振幅值會無條件進位至 100%，因此請務必使用 Vibrator.hasAmplitudeControl 檢查檔案是否提供支援。詳情請參閱振幅控制相關說明。

您應審慎評估效果是否在沒有精細控制的情況下提供足夠的品質。改用特別設計的震動功能可能會比較好。

開啟/關閉震動的使用

在較新的 SDK 級別中，所有震動模式都合併為單一表達式 VibrationEffect 類別，並使用 VibrationEffect.createOneshot 或 VibrationEffect.createWaveform 建立這些簡易震動。

通知 API

自訂應用程式通知時，您可以使用下列任一 API，將模式與每個通知管道建立關聯：

上述所有形式都具有基本的關閉波形模式，第一個項目是開啟震動器前的延遲時間。

一般概念

上文所述的 API 介面適用幾個概念。

裝置是否有振動器？

您可以從 context.getSystemService(Vibrator.class) 取得非空值的 Vibrator 類別。如果裝置沒有震動器，呼叫震動 API 並不會產生任何效果，因此應用程式不需要限制應用程式對特定條件的所有觸覺。不過，如有需要，應用程式可以呼叫 hasVibrator()，判斷這是真正的震動器 (true) 或虛設常式 (false)。

使用者是否停用了觸控觸覺功能？

部分自訂實作項目可能需要手動檢查使用者是否完全停用的 Android 的「觸覺回饋」設定，在這種情況下，應抑制觸控回饋效果。您可以使用 HAPTIC_FEEDBACK_ENABLED 鍵查詢這項設定，如果值為「0」，表示已停用。

震動屬性

震動屬性 (目前格式為 AudioAttributes) 可以協助系統告知震動的目的。當應用程式在背景執行時，如要啟動震動，這項功能就必須這麼做，因為只有背景使用支援注意力觸覺。

有關 AudioAttributes 的建立說明，請參閱其類別說明文件，應將其視為「震動」而非「音效」。

在大多數情況下，內容類型為 CONTENT_TYPE_SONIFICATION，用途則可能是 USAGE_ASSISTANCE_SONIFICATION 用於前景觸控意見回饋，或用於背景鬧鐘的 USAGE_ALARM。音訊旗標不會影響震動。

放大控制

如果震動器有增強效果，則會以不同強度來播放震動。這是產生豐富觸覺技術的重要功能，也可能允許使用者控制預設觸覺強度。

呼叫 Vibrator.hasAmplitudeControl 可以檢查音量控制支援。如果振動器不支援振幅，所有振幅值會根據是否為零/非零值對應關閉/開啟。因此，如果應用程式使用具有不同振幅的豐富觸覺技術，應考慮在裝置缺少振幅控制的情況下停用。