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,就會停用檢視畫面上的所有觸覺回饋呼叫,包括預設呼叫。主要相關設定為 View.hapticFeedbackEnabled 屬性,如果設為 false,就會停用檢視畫面上的所有觸覺回饋呼叫,包括預設呼叫。此方法也會遵循使用者的系統設定,啟用觸控回饋功能。

唯一需要考量的相容性問題,是動作的特定常數 SDK 層級。

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

HapticsFeedbackConstants 的用量

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

預先定義 VibrationEffect

VibrationEffect 類別提供多個預先定義的常數,例如 CLICKTICKDOUBLE_CLICK。這些效果可能會針對裝置進行最佳化。

相容性和需求

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

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

Vibrator.areEffectsSupportedVibrator.areAllEffectsSupported API 可用於判斷是否有裝置最佳化實作。即使沒有最佳化實作,您還是可以使用預先定義的效果,並使用標準平台備用方案。因此,只有在應用程式想考量效果是否已針對裝置進行最佳化時,才需要使用這些 areEffectsSupported API。

效果檢查方法可傳回下列三個值之一:

由於 UNKNOWN 值表示檢查 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.createOneshotVibrationEffect.createWaveform 建立這些簡單的震動效果。

Notifications API

自訂應用程式通知時,您可以使用下列任一 API 將模式與各通知管道建立關聯:

所有這些表單都採用基本開關波形圖案,如前文所述,第一個項目是開啟震動器前的延遲時間。

基本概念

上述 API 介面都適用於幾個概念。

裝置是否有震動器?

您可以從 context.getSystemService(Vibrator.class) 取得非空值 Vibrator 類別。如果裝置沒有震動器,呼叫震動 API 不會有任何效果,因此應用程式不需要根據條件限制所有觸覺回饋。不過,應用程式可視需要呼叫 hasVibrator(),判斷這是否為實際的震動器 (true) 或存根目錄 (false)。

使用者是否已停用觸控觸覺回饋?

部分自訂導入方式可能需要手動檢查使用者是否已完全停用 Android 的「Touch feedback」 設定,如果是這種情況,則應抑制觸控回饋效果。您可以使用 HAPTIC_FEEDBACK_ENABLED 鍵查詢這項設定,其中值為零表示已停用。

震動屬性

您可以提供震動屬性 (目前為 AudioAttributes 格式),協助系統瞭解震動的目的。在應用程式處於背景執行時啟動震動效果時,必須使用此方法,因為背景使用模式僅支援注意力觸覺回饋。

AudioAttributes 的建立作業已在其類別文件中說明,應將其視為「震動」而非「聲音」

做為參考,在大多數情況下,內容類型為 CONTENT_TYPE_SONIFICATION,用途可能為 USAGE_ASSISTANCE_SONIFICATION (用於前景觸控回饋) 或 USAGE_ALARM (用於背景鬧鐘)。音訊旗標不會影響震動。

振幅控制

如果震動器有振幅控制功能,則可播放不同強度的震動。這是產生豐富的觸覺回饋的重要功能,也可能讓使用者控制預設的觸覺回饋強度。

您可以呼叫 Vibrator.hasAmplitudeControl 來檢查是否支援振幅控制功能。如果震動器不支援振幅,所有振幅值都會根據值是否為零/非零,對應為關閉/開啟。因此,如果裝置缺乏振幅控制功能,使用不同振幅的豐富觸覺回饋功能的應用程式應考慮停用這類功能。