Android 觸覺回饋 API 參考資料

本文將介紹 Android 中提供的各種觸覺回饋 API，說明如何建立不同的觸覺效果，以及如何檢查裝置是否支援必要功能。keywords_public: >Android、觸覺回饋、API、震動、HapticFeedbackConstants、VibrationEffect、包絡觸覺回饋、觸覺回饋、通知、振幅控制

本節將介紹 Android 中提供的各種觸覺技術 API。此外，本文也會說明如何檢查裝置是否支援觸覺效果，確保觸覺效果能如預期播放。

建立觸覺效果的方法有很多種，選擇時請務必考量 Android 觸覺技術設計原則。下表摘要說明這兩種方式的這些高階屬性：

  • 規劃行為回溯時，可用性尤其重要，且必須與檢查個別裝置支援功能一併進行。
  • 清晰的觸覺回饋是乾淨俐落的感覺，對使用者的干擾較小。
  • 豐富的觸覺回饋更具表現力，通常需要功能更豐富的硬體。
API 介面 可用性 清除觸覺回饋 豐富的觸覺回饋
HapticFeedbackConstants Android 1.5 以上版本
(每個常數)
預先定義的 VibrationEffect Android 10 以上版本
VibrationEffect 構圖 (建議) Android 16 以上版本 (26 年第 4 季)
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 樂曲

自 Android 16 (26Q4) 起，VibrationEffect.Builder 是偏好的 API，可沿著設計的時間軸排序多個觸覺元素，藉此組合豐富且富有表現力的觸覺效果。這項功能取代了 VibrationEffect.Composition，提供以時間軸為基礎的排程、原子封裝、混合事件支援 (結合預設值和封包)，以及內建的自動備援功能。

構成元素

製作工具可讓您依序排列下列觸覺元素：

  • VibrationEffect.Preset：預先定義的觸覺感受，代表常見的短脈衝，例如 PRESET_CLICK、PRESET_TICK 和 PRESET_LOW_TICK。預設集會取代 VibrationEffect.Composition API 中的簡短基本項目。如要使用時間較長、連續或漸變的音效 (先前由升降和其他基本元素處理)，請改用封包 (PWLE)。預設集可使用 Preset.create(presetId, scale) 從 0.0f 縮放至 1.0f。
  • VibrationEffect.Envelope：使用 BasicEnvelopeBuilder (含強度和銳利度) 或 WaveformEnvelopeBuilder (含頻率和振幅) 建立的分段線性包絡線 (PWLE)。信封是使用 Envelope.create(builder) 建構而成。
  • VibrationEffect.Event：從現有 VibrationEffect 使用 getEvents() 擷取的時間軸事件。可以使用 addEvents(startTimeShiftMillis, events) 加上時間軸偏移量來新增這些項目。

時間軸排程和驗證

每個元素都會新增至建構工具，並以 startTimeMillis 代表從組合開始的時間偏移 (以毫秒為單位)：

  • 建構時間驗證：新增元素的開始時間必須嚴格遞增。建構工具會在建構時間盡力驗證，檢查是否符合最短時間長度 (例如預設值為 1 毫秒，或波封的已知時間長度)。如果在建構時間偵測到重疊，系統會擲回 IllegalArgumentException。
  • 播放時間軸對齊：架構會在播放期間盡可能提供時間軸支援。如果前一個事件仍在執行，而下一個排定事件的開始時間已到，架構會自動將後續事件移至下一個最早可用的時段。這樣可避免事件在實體播放時重疊，並確保不會捨棄任何觸覺事件。

重複效果

您可以使用 setRepeatingEffect(startTimeMillis, repeatingEffect, durationMillis) 將重複效果新增至組合。設定重複效果後，就無法在建構工具中新增其他元素。

備用廣告支援

架構層級的自動備援支援功能預設為啟用，適用於 VibrationEffect.Builder 建立的震動效果：

  • 平台透明備援：如果裝置不支援要求的 Preset 或基本 Envelope，架構會在執行階段盡可能自動將不支援的元素替換為適當的支援震動。應用程式不需要在播放以 VibrationEffect.Builder 建構的樂曲前，手動檢查裝置功能 (例如 isPresetSupported)。
  • WaveformEnvelopeBuilder 例外狀況：由 WaveformEnvelopeBuilder 建立的包絡線效果 (以赫茲為單位指定絕對物理頻率，並以 G 為單位指定振幅) 不支援自動備援。由於進階 PWLE 依賴特定硬體頻率曲線 (FOAM)，因此自動替換會影響設計意圖。如果裝置不支援 PWLE 效果或要求的頻率，就不會播放這類震動。為確保普遍相容性，建議使用 BasicEnvelopeBuilder。

「VibrationEffect.Builder」方案用量

如需使用 VibrationEffect.Builder 合成效果的程式碼範例，請參閱「使用 VibrationEffect.Builder 建立以時間軸錨定的合成效果」。

VibrationEffect 基本組合

VibrationEffect 原始型別組合是使用 VibrationEffect.startComposition API 建立的震動效果。這個 API 可讓您建立一連串的基元。

相容性與需求條件

如要播放任何 VibrationEffect，應用程式資訊清單必須具備 VIBRATE 權限。

檢查基本支援

因此，使用 VibrationEffect.Composition API 時，您必須先使用 Vibrator.arePrimitivesSupported 或 Vibrator.areAllPrimitivesSupported 檢查每個圖元的支援情形，再開始播放。

您可以使用  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 確認裝置是否支援這項功能。如果沒有，系統會忽略封包震動。