不能直接用digitalRead()轮询多个按键，因其会导致阻塞、抖动误触发及状态丢失；KeyManager通过封装去抖逻辑、三态状态机（PRESSED/HELD/RELEASED）和事件回调，实现短按/长按分离与解耦。
为什么不能直接用 digitalRead() 轮询多个按键
因为轮询会阻塞、抖动误触发、状态丢失——比如两个按键几乎同时按下，或长按期间没被扫到。封装成对象不是为了“显得面向对象”，而是把去抖逻辑、状态机、回调注册这些耦合细节收拢起来，让业务代码只关心“这个键按了/松了”。
KeyManager 类必须管理的三个核心状态
每个按键不是只有“高/低”两种状态，而是需要区分：PRESSED（刚按下）、HELD（持续按下）、RELEASED（刚松开），否则无法支持短按/长按分离。状态切换必须依赖时间戳和防抖窗口（通常 15–25ms）。
-
last_read_time：记录上次读取引脚的时间，用于计算间隔 -
debounce_ms：去抖阈值，硬定时器或millis()差值判断 -
state：枚举值，不是布尔值；且HELD状态需额外配一个hold_threshold_ms判断是否算长按
如何注册按键事件回调而不破坏实时性
不能在中断里直接调用用户函数（尤其含串口打印、浮点运算的），也不能用 std::function（Arduino 环境无 RTTI，且内存开销大）。实际做法是：在主循环中调用 update()，它内部完成去抖和状态迁移，再把已确认的事件（如 PRESSED）推入轻量环形缓冲区；业务层用 popEvent() 拿出后立刻处理。
- 回调本质是函数指针 + void* 用户数据，例如
void (*onPress)(void*) - 每个按键实例可独立设置
onPress、onRelease、onHold，互不影响 - 避免在回调里做延时、阻塞 I/O；复杂逻辑应只设标志位，由主循环响应
Arduino 上使用示例与典型坑
假设用 ESP32，GPIO 12、13、14 接三个上拉按键（低电平有效）：
KeyManager btnA(12, INPUT_PULLUP);
btnA.onPress = [](void*) { Serial.println("A pressed"); };
btnA.onHold = [](void*) { ledToggle(); }; // 长按翻转 LED
<p>// 主循环里必须高频调用
void loop() {
btnA.update(); // 不要放在 if(millis()-t>50) 里——会漏事件
delay(5); // 可以，但别超过去抖窗口一半（如 12ms）
}</p>
常见坑：INPUT_PULLUP 忘写导致引脚浮空误触发；update() 调用频率低于 100Hz 导致长按识别失败；多个 KeyManager 实例共用同一个定时源却没隔离 last_read_time ——结果是 A 键状态干扰 B 键判断。
最易被忽略的是：按键释放边沿也必须去抖，否则松手瞬间的抖动会触发两次 RELEASED；这要求每次读到低电平（按下）后，必须等到连续两次高电平（释放）且间隔达标才算真正松开。
C++免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 C++ 的入门与实战技巧！
