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

唯一的相容性考量是動作中特定常數的 SDK 級別。

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

HapticsFeedbackConstants」的用量

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

預先定義的VibrationEffect

VibrationEffect 類別提供數個預先定義的常數,例如 CLICKTICKDOUBLE_CLICK。這些效果可能已根據裝置進行最佳化調整。

相容性和需求

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

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

Vibrator.areEffectsSupportedVibrator.areAllEffectsSupported API 用於判斷是否有裝置最佳化實作。即使未經過最佳化實作,仍然可以使用預先定義的「效果」,並且使用標準平台備用服務。因此,只有在應用程式希望考量效果是否已針對裝置進行最佳化調整時,才需要這些 areEffectsSupported API。

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

UNKNOWN 值表示檢查 API 無法使用,因此系統通常會針對所有效果傳回該 API,或是完全不傳回這類 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 建立這些簡易震動。

通知 API

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

上述所有形式都具有基本的關閉波形模式,第一個項目是開啟震動器前的延遲時間。

一般概念

上文所述的 API 介面適用幾個概念。

裝置是否有振動器?

您可以從 context.getSystemService(Vibrator.class) 取得非空值的 Vibrator 類別。如果裝置沒有震動器,呼叫震動 API 並不會產生任何效果,因此應用程式不需要限制應用程式對特定條件的所有觸覺。不過,如有需要,應用程式可以呼叫 hasVibrator(),判斷這是真正的震動器 (true) 或虛設常式 (false)。

使用者是否停用了觸控觸覺功能?

部分自訂實作項目可能需要手動檢查使用者是否完全停用的 Android 的「觸覺回饋」設定,在這種情況下,應抑制觸控回饋效果。您可以使用 HAPTIC_FEEDBACK_ENABLED 鍵查詢這項設定,如果值為「0」,表示已停用。

震動屬性

震動屬性 (目前格式為 AudioAttributes) 可以協助系統告知震動的目的。當應用程式在背景執行時,如要啟動震動,這項功能就必須這麼做,因為只有背景使用支援注意力觸覺。

有關 AudioAttributes 的建立說明,請參閱其類別說明文件,應將其視為「震動」而非「音效」

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

放大控制

如果震動器有增強效果,則會以不同強度來播放震動。這是產生豐富觸覺技術的重要功能,也可能允許使用者控制預設觸覺強度。

呼叫 Vibrator.hasAmplitudeControl 可以檢查音量控制支援。如果振動器不支援振幅,所有振幅值會根據是否為零/非零值對應關閉/開啟。因此,如果應用程式使用具有不同振幅的豐富觸覺技術,應考慮在裝置缺少振幅控制的情況下停用。