為活動新增觸覺回饋

在 Android 應用程式中實作觸覺回饋，方法是使用 View 元件、預先定義的 VibrationEffect API，以及以 VibrationEffect.Builder 為錨點的時間軸組合。keywords_public: > Android 開發、觸覺技術、觸覺回饋、UI、檢視區塊、VibrationEffect、View.performHapticFeedback、Vibrator、觸覺常數

觸覺技術最基本的用途之一，就是為使用者互動提供回饋。時間挑選器、虛擬鍵盤上的按鍵按下動作和文字選取是觸覺回饋的常見用途。如要進一步瞭解何時及如何套用觸覺效果，請參閱「觸覺技術設計原則」。

本頁說明提供觸覺回饋的三種方式。

這些方法會使用裝置層級定義的基元，提供根據手邊裝置量身打造的高品質意見回饋。

根據預設，所有觸覺回饋方法都會遵守使用者的觸控回饋設定。

使用 View 元件產生觸覺回饋

使用 View.performHapticFeedback 方法產生觸覺回饋。HapticFeedbackConstants 定義的觸覺常數著重於應用程式中的功能，而非執行的觸覺效果類型。

實際的實作方式可能因裝置和硬體功能而異，但應用程式只需要考量在特定情境中提供的意見回饋類型。著重於功能，即可為類似互動啟用觸覺回饋。使用者會隨著時間，將不同觸覺感受與不同意義建立關聯。

必要條件：啟用觸覺回饋

只要 View 可見，即可對其事件使用觸覺回饋。 部分事件 (例如按住) 具有預設觸覺回饋，如果檢視畫面上的監聽器處理事件 (傳回 true)，就會觸發這類回饋。

Android View 可以將 View.hapticFeedbackEnabled 屬性設為 false，停用觸覺回饋。停用這項屬性會導致系統提供預設意見回饋。

performHapticFeedback 方法也會遵守系統設定 HAPTIC_FEEDBACK_ENABLED，讓使用者可能為整個系統停用這些設定。

與其他觸覺 API 不同，使用 HapticFeedbackConstants 和 View 不需要 VIBRATE 權限。

選擇HapticFeedbackConstant

搭配 HapticFeedbackConstants 使用 View 元件時，不需要評估特定裝置支援，因為這些常數會在必要時提供備援行為。唯一考量是所需常數的 SDK 層級。

範例 1：按鍵

以下範例說明如何在 View 中使用觸控事件監聽器，為觸控輸入新增觸覺回饋。這些效果會模擬按下按鈕再放開的感覺。

Kotlin

class HapticTouchListener : View.OnTouchListener {
  override fun onTouch(View view, MotionEvent event) : Boolean {
    when (event.actionMasked) {
      MotionEvent.ACTION_DOWN ->
        view.performHapticFeedback(HapticFeedbackConstants.VIRTUAL_KEY)
      MotionEvent.ACTION_UP ->
        view.performHapticFeedback(HapticFeedbackConstants.VIRTUAL_KEY_RELEASE)
    }
    return true
  }
}

Java

class HapticTouchListener implements View.OnTouchListener {
  @Override
  public boolean onTouch(View view, MotionEvent event) {
    switch (event.getAction()) {
      case MotionEvent.ACTION_DOWN:
        view.performHapticFeedback(HapticFeedbackConstants.VIRTUAL_KEY);
        break;
      case MotionEvent.ACTION_UP:
        view.performHapticFeedback(HapticFeedbackConstants.VIRTUAL_KEY_RELEASE);
        break;
    }
    return true;
  }
}

範例 2：提交按鈕

觸覺回饋用途不只是模擬與裝置的實體互動，也可能用來傳達抽象意義。舉例來說，一般預期 CONFIRM 效果是短暫的輕微震動，而 REJECT 可能是較強烈的回饋，用來表示失敗。以下是提交按鈕意見回饋的範例。

Kotlin

submitButton.setOnClickListener { view ->
  val successful = performSubmit()
  if (successful) {
    view.performHapticFeedback(HapticFeedbackConstants.CONFIRM)
  } else {
    view.performHapticFeedback(HapticFeedbackConstants.REJECT)
  }
}

Java

submitButton.setOnClickListener(view -> {
  boolean successful = performSubmit();
  if (successful) {
    view.performHapticFeedback(HapticFeedbackConstants.CONFIRM);
  } else {
    view.performHapticFeedback(HapticFeedbackConstants.REJECT);
  }
});

使用預先定義的 VibrationEffect 生成觸覺回饋

使用View 型方法時，重點在於使用者互動，因此建議採用這種方法，確保系統一致性。不過，您也可以叫用特定的預先定義 VibrationEffect API，自訂觸覺回饋效果。

預先定義的效果會以 VibrationEffect 常數的形式提供，並可透過 Vibrator 服務檢查支援情形及播放，如下列範例所示。

瞭解裝置對 VibrationEffect API 的支援

以基本用法來說，應該不需要檢查個別 VibrationEffect API 的支援情形。系統會使用 Vibrator.areEffectsSupported 和 Vibrator.areAllEffectsSupported 等 API，判斷裝置是否自訂常數的實作方式。如果沒有自訂效果，應用程式仍可播放效果，並使用平台定義的回退實作。

詳情請參閱「預先定義VibrationEffect」。

先決條件：載入 Vibrator 和 VIBRATE 權限

大多數震動效果都可以透過 Vibrator 服務播放，載入方式如下：

Kotlin

import android.os.Vibrator

val vibrator = context.getSystemService(Vibrator::class.java)

Java

import android.os.Vibrator;

Vibrator vibrator = context.getSystemService(Vibrator.class);

應用程式必須具備 VIBRATE 權限，才能透過這項服務震動裝置。您可以在應用程式資訊清單檔案中新增這項權限：

<uses-permission android:name="android.permission.VIBRATE"/>

播放預先定義的 VibrationEffect

您可以使用 VibrationEffect.createPredefined 準備預先定義的特效，然後在 Vibrator 上使用其中一種 vibrate 方法播放。

這個範例會播放「按一下」效果。

Kotlin

val vibrator = context.getSystemService(Vibrator::class.java)
...
// Requires VIBRATE permission
vibrator.vibrate(VibrationEffect.createPredefined(VibrationEffect.EFFECT_CLICK))

Java

Vibrator vibrator = context.getSystemService(Vibrator.class);
...
// Requires VIBRATE permission
vibrator.vibrate(VibrationEffect.createPredefined(VibrationEffect.EFFECT_CLICK));

使用 VibrationEffect.Builder 建立組合

從 Android 16 (26Q4) 開始，VibrationEffect.Builder API 提供最彈性且具表現力的方式，可沿著時間軸排序離散預設值、封包和其他震動元素，建立自訂觸覺回饋。此外，使用 VibrationEffect.Builder 建立的組合，在支援的元素中內建自動備援支援功能。

如要進一步瞭解如何使用 VibrationEffect.Builder (和 VibrationEffect.Composition API) 撰寫觸覺效果，請參閱「建立自訂觸覺效果」。