Flutter 原始指针事件处理

封面图 • 2025-11-04 • Flutter

在 Flutter 中，**原始指针事件处理（Raw Pointer Event Handling）** 是一种低层次的输入事件处理方式，它允许你直接接收来自触摸屏、鼠标、触控笔等设备的原始输入事件。Flutter 提供了 `RawPointerListener` 和 `PointerEvent` 来实现这种功能。

---

## ✅ 1. 原始指针事件的基本概念

Flutter 中的指针事件（Pointer Events）是通过 `PointerEvent` 类来表示的，它包含了以下信息：

- **Pointer ID**：唯一标识一个指针（如手指、鼠标、触控笔）
- **Position**：指针在屏幕上的坐标
- **Down / Up / Move / Cancel**：事件类型
- **Pressure**：按压力度（适用于触控笔）
- **Tangential Pressure**：切向压力（用于触控笔）
- **Smoothing**：是否启用平滑处理（默认为 false）

---

## ✅ 2. 使用 `RawPointerListener`

`RawPointerListener` 是一个可以监听原始指针事件的小部件，适用于需要精细控制输入的场景（例如游戏、绘图应用等）。

### 示例代码：

```dart
import 'package:flutter/material.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text('Raw Pointer Event Example')),
        body: RawPointerListener(
          onPointerDown: (event) {
            print('Pointer Down: ${event.localPosition}');
          },
          onPointerMove: (event) {
            print('Pointer Move: ${event.localPosition}');
          },
          onPointerUp: (event) {
            print('Pointer Up: ${event.localPosition}');
          },
          onPointerCancel: (event) {
            print('Pointer Cancel: ${event.localPosition}');
          },
          child: Center(
            child: Container(
              width: 200,
              height: 200,
              color: Colors.blue,
              child: Center(child: Text('Touch Me!')),
            ),
          ),
        ),
      ),
    );
  }
}
```

---

## ✅ 3. 指针事件类型

`RawPointerListener` 支持以下回调：

| 回调 | 说明 |
|------|------|
| `onPointerDown` | 当指针按下时触发 |
| `onPointerMove` | 当指针移动时触发 |
| `onPointerUp` | 当指针抬起时触发 |
| `onPointerCancel` | 当指针事件被取消时触发（如系统中断） |

---

## ✅ 4. 获取指针位置

你可以通过 `event.localPosition` 或 `event.globalPosition` 获取指针相对于小部件或屏幕的位置。

```dart
print('Local Position: ${event.localPosition}');
print('Global Position: ${event.globalPosition}');
```

---

## ✅ 5. 高级用法：多点触控

如果你需要处理多点触控（如手势识别），可以使用 `PointerEvent` 的 `pointerId` 来区分不同的指针。

```dart
Map<int, Offset> _pointers = {};

void onPointerDown(PointerEvent event) {
  _pointers[event.pointerId] = event.localPosition;
  print('Pointer ${event.pointerId} down at ${event.localPosition}');
}

void onPointerMove(PointerEvent event) {
  _pointers[event.pointerId] = event.localPosition;
  print('Pointer ${event.pointerId} moved to ${event.localPosition}');
}

void onPointerUp(PointerEvent event) {
  _pointers.remove(event.pointerId);
  print('Pointer ${event.pointerId} up');
}
```

---

## ✅ 6. 注意事项

- `RawPointerListener` 不会自动处理事件的冒泡或捕获，它是“原始”的。
- 如果你需要更高级的手势识别（如缩放、拖动等），建议使用 `GestureDetector` 或 `GestureRecognizer`。
- 在某些平台上（如 Web），`RawPointerListener` 可能不支持所有类型的指针事件（如触控笔）。

---

## ✅ 7. 总结

| 功能 | 说明 |
|------|------|
| `RawPointerListener` | 监听原始指针事件 |
| `PointerEvent` | 包含指针事件的所有信息 |
| 多点触控 | 通过 `pointerId` 区分不同指针 |
| 适用场景 | 游戏、绘图、自定义手势识别等 |

---

如果你有具体的使用场景（比如绘图、手势识别、游戏开发等），我可以提供更针对性的示例和建议！