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 生成觸覺回饋」。

Envelope VibrationEffect

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

相容性和需求條件

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

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

基本信封建構工具

如要打造流暢無礙的觸覺體驗，包絡線效果的開始和結束強度都必須為 \( 0.0 \)。API 會將開始強度固定為零，如果結束強度不為零，則會擲回例外狀況，藉此強制執行這項規定。這項限制可避免因振幅不連續而產生不當的動態效果，對使用者的觸覺感知造成負面影響。

為確保裝置間的包絡線效果一致，架構要求支援這項功能的裝置，必須能處理控制點之間至少 20 毫秒的時間長度，以及包絡線效果至少 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 通常與觸覺設計原則不太一致，因為可能會產生震動觸覺效果，因此請盡量避免使用，除非是最後手段。

最常見的用途是通知，無論如何都希望有震動。波形震動也能無限重複模式，就像鈴聲一樣。

單次模式是指震動 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 鍵查詢，值為零表示已停用。

震動屬性

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

AudioAttributes 的建立方式請參閱類別說明文件，且應視為「震動」而非「聲音」。

一般而言，內容類型為 CONTENT_TYPE_SONIFICATION，用途可能是前台觸控回饋的 USAGE_ASSISTANCE_SONIFICATION 值，或是背景鬧鐘的 USAGE_ALARM 值。音訊旗標不會影響震動。

振幅控制

如果震動器可控制振幅，就能以不同強度震動。這項功能對於製作豐富的觸覺回饋非常重要，而且可能允許使用者控制預設的觸覺回饋強度。

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

支援信封效果

支援包絡效果的震動器可產生更動態細緻的震動，讓您更精確地控制震動強度和銳利度，打造更豐富的觸覺體驗。使用 Vibration.areEnvelopeEffectsSupported 確認裝置是否支援這項功能。如果沒有，系統會忽略封包震動。