UI 菜单初步完成

2026-09-07 10:48:18 +08:00
parent 89462d8aa1
commit 2b41bdccb5
30 changed files with 2226 additions and 859 deletions
@@ -0,0 +1,109 @@
+/*
+ * 模块名称：UI Menu View (菜单显示模型渲染层)
+ * 模块功能：以 LVGL 基元控件实现《菜单页面设计.md》§四⑧"横向级联子框"显示模型：
+ *           右贴靠（子框左缘=父框右缘、共享边框列）+ 框宽内容自适应 +
+ *           顶对齐/底对齐上移；持有全部 LVGL 对象（样式/4 层容器/框/行/根框装饰），
+ *           不持有任何导航状态——状态由逻辑层 ui_menu.c 经本接口驱动
+ * 适用平台：STM32F407ZGTx / PC 模拟器（两端共用）
+ * 作者：王建锋
+ * 创建日期：2026-09-04
+ * 修改记录：
+ *     2026-09-04  王建锋  创建：自旧 ui_menu.c 单页模型拆分出显示层（高内聚低耦合）
+ */
+#ifndef UI_MENU_VIEW_H
+#define UI_MENU_VIEW_H
+
+#include <stdint.h>
+#include <stdbool.h>
+
+#include "lvgl.h"
+
+#define MENU_PAGE_MAX   4   /* 页面深度上限（根框 + 3 级子框） */
+#define MENU_ITEM_MAX   16  /* 单框最大条目数 */
+
+#define MENU_SCREEN_W   160 /* 屏幕宽（px，与 ui_port.h / 模拟器一致） */
+#define MENU_SCREEN_H   160 /* 屏幕高（px） */
+
+/*
+ * 函数功能：初始化显示层（样式 + 4 层持久容器 + 根框装饰 + 根框框体）
+ * 入口参数：无
+ * 返回值：0 - 成功，其他 - 失败（对象创建失败）
+ * 限定条件：LVGL 已初始化且活动屏幕存在（ui_port_init / sim_port_init 已完成）
+ * 函数说明：1. 4 层容器每深度一个、全屏覆盖、持久不删（焦点/键入口，防悬空）
+ *           2. 根框装饰（浅 V + 状态行）与根框框体只属根层（d=0）
+ *           3. 行对象不在此建，由逻辑层调 ui_menu_view_frame_build 按需建
+ */
+int ui_menu_view_init(void);
+
+/*
+ * 函数功能：取指定深度的持久容器
+ * 入口参数：depth - 深度 0..MENU_PAGE_MAX-1  uint8_t
+ * 返回值：容器对象  lv_obj_t *  越界返回 NULL
+ * 限定条件：ui_menu_view_init() 已完成
+ * 函数说明：逻辑层在容器上绑定输入组与键事件（显示层不碰输入）
+ */
+lv_obj_t *ui_menu_view_container(uint8_t depth);
+
+/*
+ * 函数功能：构建指定深度的框（几何现算 + 行对象创建 + 选中/滚动应用）
+ * 入口参数：depth  - 深度（0=根框）  uint8_t
+ *           node   - 本框展示节点（行 = 其子项）  uint8_t
+ *           sel    - 本框选中行  uint8_t
+ *           scroll - 本框滚动偏移（px，0=顶部）  uint16_t
+ * 返回值：无
+ * 限定条件：depth>0 时 depth-1 层框已建（父框几何是其对齐依据）
+ * 函数说明： 1. d=0：根框框体已存在，仅（重）建行对象
+ *           2. d>0：右贴靠父框右缘；顶边=父框选中行行顶，超屏底则
+ *              上移使本框底边对齐父框选中行行底，仍超顶则钳制顶部并改框内滚动
+ *           3. 框宽 = 最宽行（文本 + ▶ + 左右留白）+ 边框；条目现算不落地
+ */
+void ui_menu_view_frame_build(uint8_t depth, uint8_t node, uint8_t sel, uint16_t scroll);
+
+/*
+ * 函数功能：销毁指定深度的框（框体连同行对象，容器保留）
+ * 入口参数：depth - 深度  uint8_t
+ * 返回值：无
+ * 限定条件：depth>0（根框持久不可销毁）
+ * 函数说明：返回（关最右框）时调用，LVGL 池内存随即回落
+ */
+void ui_menu_view_frame_destroy(uint8_t depth);
+
+/*
+ * 函数功能：刷新指定深度框的选中高亮
+ * 入口参数：depth - 深度  uint8_t
+ *           sel   - 新选中行  uint8_t
+ * 返回值：无
+ * 限定条件：ui_menu_view_frame_build(depth,…) 已完成
+ * 函数说明：只改行状态与文字色 + 跟随滚动，不重建对象
+ */
+void ui_menu_view_frame_refresh(uint8_t depth, uint8_t sel);
+
+/*
+ * 函数功能：应用指定深度框的滚动偏移
+ * 入口参数：depth  - 深度  uint8_t
+ *           scroll - 滚动偏移（px）  uint16_t
+ * 返回值：无
+ * 限定条件：该层框已建
+ * 函数说明：行对象重建后按此还原用户滚动位置
+ */
+void ui_menu_view_set_scroll(uint8_t depth, uint16_t scroll);
+
+/*
+ * 函数功能：读取指定深度框当前滚动偏移
+ * 入口参数：depth - 深度  uint8_t
+ * 返回值：滚动偏移（px）  uint16_t  未建框返回 0
+ * 限定条件：无
+ * 函数说明：跟随滚动后由逻辑层读回，写入导航状态持久化
+ */
+uint16_t ui_menu_view_get_scroll(uint8_t depth);
+
+/*
+ * 函数功能：焦点移至指定深度的容器
+ * 入口参数：depth - 深度  uint8_t
+ * 返回值：无
+ * 限定条件：ui_menu_view_init() 已完成且容器已加入输入组
+ * 函数说明：焦点=最右框；进/退时由逻辑层调用
+ */
+void ui_menu_view_focus(uint8_t depth);
+
+#endif /* UI_MENU_VIEW_H */