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

您可以透過封包式震動，藉由定義控制點序列，精確控制震動的振幅和頻率。這可讓開發人員打造更豐富、更細緻的觸覺回饋體驗。您可以使用 BasicEnvelopeBuilder 和 WaveformEnvelopeBuilder 類別建立這些震動。

相容性和需求

如要播放任何震動效果，應用程式必須在應用程式資訊清單中宣告 VIBRATE 權限。

如要檢查是否支援封裝效果，請呼叫 Vibrator.areEnvelopeEffectsSupported()。

基本信封建立工具

為打造流暢無縫的觸覺體驗，包絡效果的開始和結束強度必須為 \( 0.0 \)。API 會將開始強度設為零，並在結束強度不為零時擲回例外狀況，以便強制執行這項規定。這項限制可避免振動發生不必要的動態效果，因為振幅的間斷性可能會對使用者的觸覺感知造成負面影響。

為在各裝置上提供一致的包絡效果算繪，架構要求支援這項功能的裝置可處理控制點之間的最短時間為 10 毫秒，且包絡效果至少要有 16 個點。

波形封套建立工具

此架構不會修改開發人員提供的要求頻率和振幅值。不過，API 也會將起始振幅固定為零，以便建立流暢的轉場效果。

為了協助您最佳化應用程式的波形封套效果，並提供跨裝置的相容性，Android 提供 API 可用來查詢重要的裝置功能。這些方法會提供裝置限制的相關資訊，例如控制點之間的最大和最小轉場時間，以及單一效果支援的控制點上限：

getMaxSize()
擷取封套效果支援的控制點數量上限。
getMinControlPointDurationMillis()
擷取封套效果中兩個控制點之間支援的最短時間長度 (以毫秒為單位)。
getMaxControlPointDurationMillis()
擷取包絡效果中兩個控制點之間支援的最大時間長度 (以毫秒為單位)。
getMaxDurationMillis()
擷取封套效果支援的最大時間長度 (以毫秒為單位)。

如果特效超出裝置限制 (例如允許的控制點過多或時間長度超過上限)，架構會自動調整特效，使其符合允許的範圍。這個調整程序會盡可能保留設計的原始意圖和感受。

Envelope VibrationEffects 的用法

如要進一步瞭解如何建立封閉波形效果，請參閱使用封閉函數建立振動波形。

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 的「Touch feedback」 設定，如果是這種情況，則應抑制觸控回饋效果。您可以使用 HAPTIC_FEEDBACK_ENABLED 鍵查詢這項設定，其中值為零表示已停用。

震動屬性

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

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

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

振幅控制

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

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

封包效果支援

具有包絡效果的震動器可支援並產生更具動態且細緻的震動，提供更精確的強度和銳利度控制選項，帶來更豐富的觸覺體驗。使用 Vibration.areEnvelopeEffectsSupported 判斷裝置是否支援這項功能。如果沒有，系統就會忽略以包絡函數為依據的震動。