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 類別提供多個預先定義的常數，例如 CLICK、TICK 和 DOUBLE_CLICK。這些效果可能會針對裝置進行最佳化。

相容性和需求

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

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

Vibrator.areEffectsSupported 和 Vibrator.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.createOneshot 或 VibrationEffect.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 來檢查是否支援振幅控制功能。如果震動器不支援振幅，所有振幅值都會根據值是否為零/非零，對應為關閉/開啟。因此，如果裝置缺乏振幅控制功能，使用不同振幅的豐富觸覺回饋功能的應用程式應考慮停用這類功能。