2.5 手势识别与交互系统

手势是移动端交互的核心。Flutter 提供了从低层级的 Listener 到高层级的 GestureDetector 一整套手势识别体系,并通过手势竞技场(Gesture Arena)解决手势冲突。


一、手势识别层级

复制代码
Layer 3(高层):GestureDetector / InkWell / Dismissible
  ↓ 封装了各种 Recognizer
Layer 2(中层):GestureRecognizer 系列
  ↓ 基于 PointerEvent 识别手势语义
Layer 1(低层):Listener / RawGestureDetector
  ↓ 直接监听原始指针事件
硬件层:PointerDownEvent / PointerMoveEvent / PointerUpEvent

二、GestureDetector

2.1 基本手势

dart 复制代码
GestureDetector(
  // ========= 点击类 =========
  onTap: () => print('单击'),
  onDoubleTap: () => print('双击'),
  onLongPress: () => print('长按'),
  onLongPressStart: (details) => print('长按开始: ${details.globalPosition}'),
  onLongPressEnd: (details) => print('长按结束'),

  // ========= 拖拽类 =========
  onPanStart: (details) => print('拖拽开始'),
  onPanUpdate: (details) {
    setState(() {
      _offset += details.delta; // 跟随手指移动
    });
  },
  onPanEnd: (details) => print('拖拽结束,速度: ${details.velocity}'),

  // ========= 缩放类(双指缩放 / 旋转)=========
  onScaleStart: (details) {
    _baseScale = _currentScale;
    _baseAngle = _currentAngle;
  },
  onScaleUpdate: (details) {
    setState(() {
      _currentScale = _baseScale * details.scale;
      _currentAngle = _baseAngle + details.rotation;
    });
  },

  // 子 Widget
  child: Transform(
    transform: Matrix4.identity()
      ..translate(_offset.dx, _offset.dy)
      ..scale(_currentScale)
      ..rotateZ(_currentAngle),
    alignment: Alignment.center,
    child: Image.asset('assets/photo.jpg'),
  ),
)

2.2 垂直 / 水平拖拽

dart 复制代码
// 仅监听垂直方向拖拽
GestureDetector(
  onVerticalDragUpdate: (details) {
    setState(() => _offsetY += details.delta.dy);
  },
  child: child,
)

// 仅监听水平方向拖拽
GestureDetector(
  onHorizontalDragUpdate: (details) {
    setState(() => _offsetX += details.delta.dx);
  },
  child: child,
)

// 注意:onPanUpdate 与 onVerticalDrag / onHorizontalDrag 不能同时使用!
// Pan = 垂直 + 水平 的联合手势

三、手势竞技场(Gesture Arena)

当多个 Widget 同时识别到手势时,Flutter 使用手势竞技场来决定谁赢得手势:

复制代码
手指按下 → 多个 GestureRecognizer 注册到 Arena

竞争规则:
  ① 任何 Recognizer 可以直接"声明胜利"(如 TapRecognizer 在手指抬起时)
  ② 如果只剩一个 Recognizer,自动胜出
  ③ 超时后,第一个注册的 Recognizer 胜出

常见冲突场景:
  ListView(ScrollGesture)↔ GestureDetector(Tap)
  → 短按不动 = Tap 胜出
  → 滑动 = ScrollGesture 胜出

3.1 解决手势冲突

dart 复制代码
// 问题:外部 GestureDetector 吞掉了内部的 onTap
GestureDetector(
  onTap: () => print('外部'),
  child: GestureDetector(
    onTap: () => print('内部'), // 可以正常接收
    child: child,
  ),
)
// → onTap 不冲突,因为子节点的 HitTest 先命中

// 问题:onPanUpdate 与 ListView 滚动冲突
// 解决:使用 RawGestureDetector + 自定义竞争策略
class AlwaysWinPanRecognizer extends PanGestureRecognizer {
  @override
  void rejectGesture(int pointer) {
    acceptGesture(pointer); // 强制赢得竞争
  }
}

RawGestureDetector(
  gestures: {
    AlwaysWinPanRecognizer:
        GestureRecognizerFactoryWithHandlers<AlwaysWinPanRecognizer>(
      () => AlwaysWinPanRecognizer(),
      (instance) {
        instance.onUpdate = (details) { /* 拖拽逻辑 */ };
      },
    ),
  },
  child: child,
)

四、Listener(底层指针事件)

dart 复制代码
Listener(
  onPointerDown: (event) => print('手指按下: ${event.position}'),
  onPointerMove: (event) => print('手指移动: ${event.delta}'),
  onPointerUp: (event) => print('手指抬起'),
  onPointerCancel: (event) => print('取消'),
  onPointerHover: (event) => print('悬停(鼠标/触控笔)'),
  onPointerSignal: (event) {
    // 鼠标滚轮事件(桌面/Web)
    if (event is PointerScrollEvent) {
      print('滚轮: ${event.scrollDelta}');
    }
  },
  child: child,
)

五、HitTest(命中测试)

复制代码
手指按下 → HitTest 从 RenderObject 树根节点开始
  ↓ 递归调用每个 RenderBox.hitTest()
  ↓ 收集所有命中的 Widget(HitTestResult 列表)
  ↓ 从内到外分发 PointerEvent

自定义 HitTest 区域:
dart 复制代码
// 忽略 Widget(事件穿透)
IgnorePointer(
  ignoring: true,
  child: OverlayWidget(), // 该 Widget 不响应触摸
)

// 吸收事件(不穿透到下方)
AbsorbPointer(
  absorbing: true,
  child: child, // 下方 Widget 不接收事件
)

// 扩大触摸区域
Padding(
  padding: const EdgeInsets.all(12), // 视觉不变,但可触摸区域增大
  child: GestureDetector(
    behavior: HitTestBehavior.opaque, // 让透明区域也响应
    onTap: () {},
    child: Icon(Icons.close, size: 24),
  ),
)

HitTestBehavior

dart 复制代码
GestureDetector(
  behavior: HitTestBehavior.deferToChild, // 默认:仅子 Widget 区域响应
  // behavior: HitTestBehavior.opaque,     // 自身整个区域都响应(不透传)
  // behavior: HitTestBehavior.translucent,// 自身整个区域响应(但透传给下方)
  child: child,
)

六、拖拽排序(Drag & Drop)

6.1 内置排序组件

dart 复制代码
ReorderableListView(
  onReorder: (oldIndex, newIndex) {
    setState(() {
      if (newIndex > oldIndex) newIndex--;
      final item = _items.removeAt(oldIndex);
      _items.insert(newIndex, item);
    });
  },
  children: _items.map((item) => ListTile(
    key: ValueKey(item.id), // 必须有 Key
    title: Text(item.name),
    trailing: ReorderableDragStartListener(
      index: _items.indexOf(item),
      child: const Icon(Icons.drag_handle),
    ),
  )).toList(),
)

6.2 Draggable + DragTarget

dart 复制代码
// 可拖拽的 Widget
Draggable<Product>(
  data: product, // 携带数据
  feedback: Material( // 拖拽时跟随手指的 Widget
    elevation: 8,
    child: ProductCard(product: product),
  ),
  childWhenDragging: Opacity( // 原位置的占位 Widget
    opacity: 0.3,
    child: ProductCard(product: product),
  ),
  child: ProductCard(product: product),
)

// 拖拽目标区域
DragTarget<Product>(
  onWillAcceptWithDetails: (details) => true, // 是否接受此拖拽
  onAcceptWithDetails: (details) {
    setState(() => _cart.add(details.data));
  },
  builder: (context, candidateData, rejectedData) {
    final isHovering = candidateData.isNotEmpty;
    return AnimatedContainer(
      duration: const Duration(milliseconds: 200),
      decoration: BoxDecoration(
        color: isHovering ? Colors.blue.withOpacity(0.2) : Colors.grey[100],
        border: Border.all(
          color: isHovering ? Colors.blue : Colors.grey,
          width: 2,
        ),
      ),
      child: const Center(child: Text('拖拽商品到此处')),
    );
  },
)

6.3 LongPressDraggable

dart 复制代码
// 长按后才能拖拽(更自然的移动端体验)
LongPressDraggable<String>(
  data: 'hello',
  delay: const Duration(milliseconds: 300), // 长按触发时间
  hapticFeedbackOnStart: true, // 触觉反馈
  feedback: child,
  child: child,
)

七、桌面 / Web 交互适配

dart 复制代码
// 鼠标光标
MouseRegion(
  cursor: SystemMouseCursors.click,
  onEnter: (_) => setState(() => _isHovering = true),
  onExit: (_) => setState(() => _isHovering = false),
  child: AnimatedContainer(
    duration: const Duration(milliseconds: 150),
    transform: Matrix4.identity()..scale(_isHovering ? 1.05 : 1.0),
    child: Card(child: content),
  ),
)

// 键盘快捷键
Shortcuts(
  shortcuts: {
    LogicalKeySet(LogicalKeyboardKey.control, LogicalKeyboardKey.keyS):
        const SaveIntent(),
    LogicalKeySet(LogicalKeyboardKey.control, LogicalKeyboardKey.keyZ):
        const UndoIntent(),
  },
  child: Actions(
    actions: {
      SaveIntent: CallbackAction<SaveIntent>(
        onInvoke: (_) => _save(),
      ),
    },
    child: Focus(
      autofocus: true,
      child: child,
    ),
  ),
)

// 右键菜单
Listener(
  onPointerDown: (event) {
    if (event.kind == PointerDeviceKind.mouse &&
        event.buttons == kSecondaryMouseButton) {
      _showContextMenu(event.position);
    }
  },
  child: child,
)

小结

概念 要点
GestureDetector 高层手势封装:tap / drag / scale
手势竞技场 解决多手势冲突,子节点优先
HitTestBehavior deferToChild / opaque / translucent
Draggable 拖拽交互,配合 DragTarget
MouseRegion 桌面 hover、光标适配
Listener 低层指针事件,全平台兼容

👉 下一节:2.6 表单与输入处理

相关推荐
程序员老刘2 小时前
跨平台开发地图 | 2026年11月
flutter·ai编程·客户端
zhanlang02178 小时前
HTML 零基础入门到企业实战【第七章 表单标签|7.1 表单核心作用:数据收集、用户交互原理】
前端·html·交互
传奇开心果编程8 小时前
【Flutter踩坑排雷】第30课:异常未捕获坑|未捕获异常直接闪退,全局兜底故障处理
android·flutter·ios·移动开发·dart·ui框架·声明式ui
恋猫de小郭10 小时前
Flutter Native Interop 稳定了,Platform Channel 要退场了
android·前端·flutter
好的佩奇20 小时前
Dart 之可迭代对象与生成器
android·flutter·dart
恋猫de小郭1 天前
Flutter Analyzer 系列坑推进,必看,AI 时代这玩意最吃你内存
android·前端·flutter
LinXunFeng2 天前
拿竞品 App 一扫,技术栈全暴露了
android·flutter·开源
传奇开心果编程2 天前
【Flutter踩坑排雷】第28课:平台目录缺失与修复坑|`flutter create` 的“重建”与“覆盖”边界
android·flutter·ios·移动开发·跨平台·dart·声明式ui
程序员老刘·3 天前
Flutter 3.50更新,开发者应该关注什么?
flutter·ai编程·跨平台开发
时间的情敌3 天前
Cesium 流动管线、管道动画、管线流向仿真,管网、油气、水利孪生高频需求
前端·交互·cesium