初始化版本

api/menu.h

@@ -0,0 +1,152 @@
+/**
+ * @file menu.h
+ * @brief 菜单组件对外暴露的核心接口（用户唯一需要包含的头文件）
+ * @note 工业级嵌入式菜单组件 - 对外API层
+ */
+#ifndef MENU_H
+#define MENU_H
+
+#include "menu_config.h"
+#include <stdint.h>
+#include <stdbool.h>
+
+/************************** 全局类型导出 **************************/
+/**
+ * @brief 菜单错误码（工业级错误处理：明确所有可能的错误类型）
+ */
+typedef enum {
+    MENU_OK = 0,                ///< 操作成功
+    MENU_ERR_INVALID_PARAM,     ///< 无效参数
+    MENU_ERR_OUT_OF_MEMORY,     ///< 内存不足（静态内存池已满）
+    MENU_ERR_NODE_NOT_FOUND,    ///< 菜单节点未找到
+    MENU_ERR_STACK_OVERFLOW,    ///< 菜单栈溢出（导航层级超过配置）
+    MENU_ERR_STACK_UNDERFLOW,   ///< 菜单栈下溢（已到根节点仍返回）
+    MENU_ERR_EVENT_QUEUE_FULL,  ///< 事件队列已满
+    MENU_ERR_NOT_SUPPORTED,     ///< 功能未启用（如未开启多语言）
+    MENU_ERR_HW_PORT_ERROR      ///< 硬件端口层错误
+} MenuErrCode;
+
+/**
+ * @brief 菜单事件类型（事件驱动核心：解耦按键与菜单逻辑）
+ */
+typedef enum {
+    MENU_EVENT_NONE = 0,        ///< 无事件
+    MENU_EVENT_KEY_UP,          ///< 上键按下
+    MENU_EVENT_KEY_DOWN,        ///< 下键按下
+    MENU_EVENT_KEY_ENTER,       ///< 确认键按下
+    MENU_EVENT_KEY_BACK,        ///< 返回键按下
+    MENU_EVENT_CUSTOM_BEGIN = 0x10, ///< 自定义事件起始标识（用户可扩展）
+} MenuEventType;
+
+/**
+ * @brief 菜单节点ID类型（统一标识）
+ */
+typedef uint16_t MenuNodeId;
+
+/**
+ * @brief 菜单回调函数类型（菜单选中/退出时的执行逻辑）
+ * @param node_id 触发回调的菜单节点ID
+ * @return 错误码
+ */
+typedef MenuErrCode (*MenuCallback)(MenuNodeId node_id);
+
+/************************** 核心接口声明 **************************/
+/**
+ * @brief 菜单组件初始化（必须首先调用）
+ * @return 错误码
+ */
+MenuErrCode menu_init(void);
+
+/**
+ * @brief 菜单主循环（需在用户主循环中调用，处理事件和刷新显示）
+ */
+void menu_main_loop(void);
+
+/**
+ * @brief 发送事件到菜单事件队列（如按键事件、自定义事件）
+ * @param type 事件类型
+ * @param param 事件附加参数（可选，如按键长按时间）
+ * @return 错误码
+ */
+MenuErrCode menu_post_event(MenuEventType type, uint32_t param);
+
+/**
+ * @brief 注册菜单节点（构建菜单树）
+ * @param parent_id 父节点ID（根节点填0）
+ * @param node_id 当前节点ID（唯一，不可重复）
+ * @param name_str 菜单名称字符串（或多语言索引）
+ * @param enter_cb 进入该菜单的回调函数（NULL表示无）
+ * @param exit_cb 退出该菜单的回调函数（NULL表示无）
+ * @return 错误码
+ */
+MenuErrCode menu_register_node(MenuNodeId parent_id, MenuNodeId node_id, const char* name_str, MenuCallback enter_cb, MenuCallback exit_cb);
+
+/**
+ * @brief 获取当前选中的菜单节点ID
+ * @param node_id 输出参数，当前节点ID
+ * @return 错误码
+ */
+MenuErrCode menu_get_current_node(MenuNodeId* node_id);
+
+/************************** 功能扩展接口声明（可裁剪） **************************/
+#if MENU_CONFIG_ENABLE_PARAM
+/**
+ * @brief 参数类型枚举
+ */
+typedef enum {
+    MENU_PARAM_TYPE_INT8,
+    MENU_PARAM_TYPE_UINT8,
+    MENU_PARAM_TYPE_INT16,
+    MENU_PARAM_TYPE_UINT16,
+    MENU_PARAM_TYPE_INT32,
+    MENU_PARAM_TYPE_UINT32,
+    MENU_PARAM_TYPE_FLOAT,
+} MenuParamType;
+
+/**
+ * @brief 注册参数到菜单节点（参数管理功能）
+ * @param node_id 菜单节点ID（参数与菜单绑定）
+ * @param param_id 参数ID（唯一）
+ * @param type 参数类型
+ * @param min_val 最小值（浮点型，内部自动转换）
+ * @param max_val 最大值（浮点型，内部自动转换）
+ * @param default_val 默认值（浮点型，内部自动转换）
+ * @param scale 缩放因子（如0.1表示保留1位小数）
+ * @return 错误码
+ */
+MenuErrCode menu_param_register(MenuNodeId node_id, uint16_t param_id, MenuParamType type, float min_val, float max_val, float default_val, float scale);
+
+/**
+ * @brief 设置参数值
+ * @param param_id 参数ID
+ * @param value 新值（浮点型，内部自动转换）
+ * @return 错误码
+ */
+MenuErrCode menu_param_set_value(uint16_t param_id, float value);
+
+/**
+ * @brief 获取参数值
+ * @param param_id 参数ID
+ * @param value 输出参数，当前值（浮点型）
+ * @return 错误码
+ */
+MenuErrCode menu_param_get_value(uint16_t param_id, float* value);
+#endif // MENU_CONFIG_ENABLE_PARAM
+
+#if MENU_CONFIG_ENABLE_LANG
+/**
+ * @brief 设置当前语言
+ * @param lang_id 语言ID（如0-中文，1-英文）
+ * @return 错误码
+ */
+MenuErrCode menu_lang_set_current(uint8_t lang_id);
+
+/**
+ * @brief 获取当前语言
+ * @param lang_id 输出参数，当前语言ID
+ * @return 错误码
+ */
+MenuErrCode menu_lang_get_current(uint8_t* lang_id);
+#endif // MENU_CONFIG_ENABLE_LANG
+
+#endif // MENU_H

api/menu_config.h

@@ -0,0 +1,67 @@
+/**
+ * @file menu_config.h
+ * @brief 菜单组件用户配置文件（工业级：集中管理所有可配置项）
+ * @note 用户可根据项目需求修改此文件
+ */
+#ifndef MENU_CONFIG_H
+#define MENU_CONFIG_H
+
+/************************** 核心配置 **************************/
+/**
+ * @brief 最大菜单节点数（静态内存，根据项目调整）
+ */
+#define MENU_CONFIG_MAX_NODES        32
+
+/**
+ * @brief 菜单栈深度（最大导航层级，如根→子→孙，深度为3）
+ */
+#define MENU_CONFIG_STACK_DEPTH      8
+
+/**
+ * @brief 事件队列长度（存储按键/自定义事件，避免丢失）
+ */
+#define MENU_CONFIG_EVENT_QUEUE_LEN  16
+
+/**
+ * @brief 是否启用断言（调试时开启，发布时关闭）
+ */
+#define MENU_CONFIG_ENABLE_ASSERT    1
+
+/**
+ * @brief 是否启用调试打印（调试时开启，发布时关闭）
+ */
+#define MENU_CONFIG_ENABLE_DEBUG     1
+
+/************************** 功能扩展配置（可裁剪） **************************/
+/**
+ * @brief 是否启用参数管理功能
+ */
+#define MENU_CONFIG_ENABLE_PARAM     1
+
+/**
+ * @brief 是否启用多语言功能
+ */
+#define MENU_CONFIG_ENABLE_LANG      1
+
+/**
+ * @brief 最大参数数量（启用参数管理时有效）
+ */
+#define MENU_CONFIG_MAX_PARAMS       16
+
+/**
+ * @brief 支持的最大语言数量（启用多语言时有效）
+ */
+#define MENU_CONFIG_MAX_LANGS        2
+
+/************************** 硬件无关配置 **************************/
+/**
+ * @brief 事件处理超时时间（ms，防止事件队列阻塞）
+ */
+#define MENU_CONFIG_EVENT_TIMEOUT    100
+
+/**
+ * @brief 菜单刷新间隔（ms，控制显示刷新频率）
+ */
+#define MENU_CONFIG_REFRESH_INTERVAL 50
+
+#endif // MENU_CONFIG_H