From 810dcd2c9963d74e4f2bc6e62a0fca0cd6d81fa7 Mon Sep 17 00:00:00 2001 From: xueben Date: Sat, 7 Mar 2026 23:19:38 +0800 Subject: [PATCH] =?UTF-8?q?NEW:=20=E8=A1=A5=E5=85=85=E6=A0=B8=E5=BF=83?= =?UTF-8?q?=E7=8A=B6=E6=80=81=E6=9C=BA=E8=BF=90=E8=A1=8C=E5=8E=9F=E7=90=86?= =?UTF-8?q?=E8=AF=B4=E6=98=8E=20Why:=201.=20=E6=96=B0=E5=A2=9E=20usage=5Fg?= =?UTF-8?q?uide.md=20=E6=A0=B8=E5=BF=83=E7=8A=B6=E6=80=81=E6=9C=BA?= =?UTF-8?q?=E8=BF=90=E8=A1=8C=E6=9C=BA=E5=88=B6=E7=AB=A0=E8=8A=82=EF=BC=88?= =?UTF-8?q?=E5=90=AB=20Mermaid=20=E7=8A=B6=E6=80=81=E6=B5=81=E8=BD=AC?= =?UTF-8?q?=E5=9B=BE=EF=BC=89=EF=BC=9B=202.=20=E5=9C=A8=20api.md=20?= =?UTF-8?q?=E4=BA=8B=E4=BB=B6=E7=B1=BB=E5=9E=8B=E5=A4=84=E6=B7=BB=E5=8A=A0?= =?UTF-8?q?=E9=93=BE=E6=8E=A5=E6=8C=87=E5=90=91=E6=96=B0=E7=AB=A0=E8=8A=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit TEST: 48 Tests 0 Failures 0 Ignored - C++ 兼容性测试: 全部通过 --- docs/api.md | 2 ++ docs/usage_guide.md | 37 +++++++++++++++++++++++++++++++++++++ 2 files changed, 39 insertions(+) diff --git a/docs/api.md b/docs/api.md index 48e89db..b391709 100644 --- a/docs/api.md +++ b/docs/api.md @@ -213,6 +213,8 @@ typedef enum { > **注意**: 内部状态机状态（如 IDLE, RELEASE_WINDOW 等）不再暴露给用户，仅在库内部使用。 +> **详细的事件流转时序和判定逻辑，请参阅《使用指南》中的[核心状态机运行机制](./usage_guide.md#核心状态机运行机制)。** + ## 错误码枚举 ```c diff --git a/docs/usage_guide.md b/docs/usage_guide.md index 8e479b2..88165c5 100644 --- a/docs/usage_guide.md +++ b/docs/usage_guide.md @@ -11,6 +11,43 @@ BitsButton是一个轻量级、高性能的按键检测库，支持单按键和 - **C标准兼容**：支持C89/C99/C11 - **轻量化**：RAM占用少于20字节/按键 +## 核心状态机运行机制 + +BitsButton 的核心是一个基于时间窗口（Time Window）的有限状态机。理解状态的流转机制有助于您正确使用各类按键事件（尤其是 `RELEASE` 与 `FINISH` 的区别）。 + +### 状态流转图 + +```mermaid +stateDiagram-v2 + [*] --> IDLE : 初始化 / 重置 + + IDLE --> PRESSED : 物理按下持续时间 > short_press_time_ms\n(抛出 BTN_EVENT_PRESSED) + + PRESSED --> LONG_PRESS : 按下状态保持 > long_press_start_time_ms\n(抛出 BTN_EVENT_LONG_PRESS) + LONG_PRESS --> LONG_PRESS : 每隔 long_press_period_trigger_ms\n(循环抛出 BTN_EVENT_LONG_PRESS) + + PRESSED --> RELEASE : 物理松开\n(抛出 BTN_EVENT_RELEASE) + LONG_PRESS --> RELEASE : 物理松开\n(抛出 BTN_EVENT_RELEASE) + + RELEASE --> RELEASE_WINDOW : 进入判定等待窗口\n(等待可能的下一次双击/连击) + + RELEASE_WINDOW --> PRESSED : 窗口期内再次物理按下\n(连击计数 + 1) + + RELEASE_WINDOW --> FINISH : 窗口期超时无动作 (time_window_time_ms)\n(抛出 BTN_EVENT_FINISH，结算连击值) + FINISH --> IDLE : 本次按键生命周期结束 +``` + +### 关键机制说明 + +1. **消抖处理（Debounce）**： + - 物理按下必须持续超过 `short_press_time_ms` 才会进入 `PRESSED` 状态。小于此时间的抖动会被丢弃。 +2. **多击判定窗口（Release Window）**： + - 当用户松开按键（`RELEASE`）时，系统**不会立即判定动作结束**，而是进入等待窗口。 + - 只有在 `time_window_time_ms` 时间内没有新的按下动作，系统才会抛出终结事件 `BTN_EVENT_FINISH`。 + - **如果您想检测"双击"或"三连击"，请务必在 `BTN_EVENT_FINISH` 事件中读取 `key_value`。** +3. **长按周期触发（Long Press Hold）**： + - 进入长按状态后，只要不松手，系统会每隔 `long_press_period_trigger_ms` 抛出一次长按事件。 + ## 快速开始 ### 1. 集成库文件