GestureDetector.OnGestureListener 六個回調 (onDown, onShowPress, onSingleTapUp, onLongPress, onScroll, onFling) 文檔缺失、行為微妙,導致開發者頻繁踩坑。本文基於源碼邏輯與大量實測,精準定義各手勢觸發條件、時序關係、互斥規則,並提供「點擊-長按-滑動-拋擲」完整決策樹與最佳實踐模式。
| 回調 | 觸發動作描述 | 觸發時機 | 關鍵參數/返回值含義 |
|---|---|---|---|
onDown(MotionEvent e) |
手指**剛接觸**屏幕瞬間 (ACTION_DOWN) | **最先觸發**,所有手勢前置 | 返回 true 表示消費事件,繼續後續手勢檢測;返回 false 則整個手勢流程終止 (極其關鍵!) |
onShowPress(MotionEvent e) |
手指**按住不動**超過 ViewConfiguration.getTapTimeout() (默認 ~100ms) 但未達長按閾值 |
onDown 返回 true 後,延遲 ~100ms 觸發 (若期間無移動/抬起) |
視覺反饋提示 (如高亮按鈕),**無返回值**。若期間移動/抬起則不觸發。 |
onSingleTapUp(MotionEvent e) |
手指**抬起** (ACTION_UP),且前序無移動、無長按、無雙擊 | 抬起瞬間,經過單擊確認延遲 (ViewConfiguration.getDoubleTapTimeout() ~300ms) 確認無二次點擊 |
返回 true 消費事件。標準「點擊」語義觸發點。 |
onLongPress(MotionEvent e) |
手指**長按不動**超過 ViewConfiguration.getLongPressTimeout() (默認 ~500ms) |
onShowPress 後再延遲 ~400ms 觸發 (若期間無移動/抬起) |
進入編輯模式、顯示上下文菜單等。**無返回值**。觸發後抬起不再觸發 onSingleTapUp。 |
onScroll(MotionEvent e1, MotionEvent e2, float distanceX, float distanceY) |
手指**滑動** (ACTION_MOVE),距離超過 ViewConfiguration.getScaledTouchSlop() (默認 ~8-16dp) |
onDown 後,首次移動超過閾值觸發,後續每次 MOVE 觸發 |
e1: 首次 DOWN 事件; e2: 當前 MOVE 事件; distanceX/Y: **上次調用到本次的位移增量** (非累計)。**返回 true 消費**。 |
onFling(MotionEvent e1, MotionEvent e2, float velocityX, float velocityY) |
手指**快速滑動並抬起** (ACTION_UP),速度超過 ViewConfiguration.getScaledMinimumFlingVelocity() (默認 ~50px/s) 且小於 Maximum |
抬起瞬間,滿足速度閾值 | e1: DOWN 事件; e2: UP 事件; velocityX/Y: **當前像素/秒速度** (含方向符號)。**返回 true 消費**。 |
ACTION_DOWN
│
├─► onDown() ──返回 false ──► 【流程終結】無後續任何回調
│
└─► 返回 true
│
├─► 移動超過 TouchSlop ──► onScroll() (可多次) ──► ACTION_UP ──► 【結束】(無 onSingleTapUp/onFling)
│
├─► 無移動/微動
│ │
│ ├─► 延遲 TapTimeout (~100ms) ──► onShowPress()
│ │ │
│ │ ├─► 繼續無動作 ──► 延遲 LongPressTimeout (~500ms) ──► onLongPress() ──► ACTION_UP ──► 【結束】
│ │ │
│ │ └─► 期間 移動/抬起 ──► 取消長按檢測
│ │
│ └─► 抬起 (在 TapTimeout 內) ──► 【進入單擊確認期】~300ms (DoubleTapTimeout)
│ │
│ ├─► 期間 無二次 DOWN ──► onSingleTapUp() ──► 【結束】
│ │
│ └─► 期間 有二次 DOWN ──► 進入雙擊檢測 (OnDoubleTapListener)
│
└─► 快速滑動 + 抬起 (速度 > MinFlingVelocity) ──► onFling() ──► 【結束】(無 onSingleTapUp)
onDown() 開始,且**必須返回 true** 才能進入後續檢測。這是最常見錯誤:默認返回 false 導致手勢失效。onLongPress 前必經 onShowPress,二者時間間隔約 400ms。onShowPress 和 onDown 後若無長按/滑動/拋擲,最終均以 onSingleTapUp 收尾 (經過雙擊確認延遲)。onLongPress、onScroll、onFling 觸發後,抬起**不再觸發 onSingleTapUp** (互斥)。onScroll 的 distanceX/Y 是**增量** (上次到這次),非累計。累計位移需自行累加 e2.getX() - e1.getX()。onFling 的速度是**瞬時速度** (像素/秒),可直接用於慣性滾動初速度。OnDoubleTapListener 並 setOnDoubleTapListener(this),onSingleTapConfirmed 才是真正的單擊回調 (排除雙擊第一下)。public class GestureHandler implements GestureDetector.OnGestureListener, GestureDetector.OnDoubleTapListener {
private GestureDetector detector;
private GestureCallback callback; // 自定義業務回調接口
public GestureHandler(Context context, GestureCallback callback) {
this.callback = callback;
detector = new GestureDetector(context, this);
detector.setOnDoubleTapListener(this); // 啟用雙擊檢測
}
public boolean onTouchEvent(MotionEvent event) {
return detector.onTouchEvent(event);
}
@Override public boolean onDown(MotionEvent e) { return true; } // 關鍵:消費 DOWN
@Override public void onShowPress(MotionEvent e) {
callback.onPressStart(e); // 視覺反饋
}
@Override public boolean onSingleTapUp(MotionEvent e) {
callback.onSingleTap(e); // 標準點擊
return true;
}
@Override public void onLongPress(MotionEvent e) {
callback.onLongPress(e); // 長按操作
}
@Override public boolean onScroll(MotionEvent e1, MotionEvent e2, float dX, float dY) {
callback.onScroll(dX, dY); // 拖拽/滑動
return true;
}
@Override public boolean onFling(MotionEvent e1, MotionEvent e2, float vX, float vY) {
callback.onFling(vX, vY); // 惯性滾動/翻頁
return true;
}
// 雙擊接口
@Override public boolean onSingleTapConfirmed(MotionEvent e) { return false; } // 已由 onSingleTapUp 處理
@Override public boolean onDoubleTap(MotionEvent e) { callback.onDoubleTap(e); return true; }
@Override public boolean onDoubleTapEvent(MotionEvent e) { return false; }
}
SimpleOnGestureListener 所有方法默認返回 false。**直接繼承它並只覆寫 onFling 會導致 onDown 返回 false,整個手勢流程不啟動!**
正確做法:繼承 SimpleOnGestureListener 並**重寫 onDown() return true;**,或直接實現 OnGestureListener 接口。
透徹理解這套時序邏輯與返回值契約,你就能精準控制複雜手勢交互,避免「長按觸發了單擊」、「滑動後抬起誤觸發點擊」等經典 Bug,構建絲滑的觸控體驗。