lvgl-skills

name	lvgl-skills
description	LVGL v9 嵌入式 UI 开发规范，强制工程化架构（screen/component/ui_manager 三层分离）、分辨率自适应布局、GUI Guider 兼容。触发条件：项目使用 LVGL v9 图形库，或用户请求生成 LVGL UI 代码、创建界面、设计嵌入式屏幕、开发 ESP32-S3/K230 等平台的 GUI 应用。

触发条件

以下任一情况自动加载本技能：

• 项目依赖 LVGL v9（components/lvgl/ 或 lvgl 出现在工程中）
• 用户请求创建/修改 LVGL 界面、屏幕、控件、动画
• 涉及 GUI Guider 导出代码的集成与改造
• 开发嵌入式 GUI 应用（ESP32-S3、K230 等 MCU/SoC 平台上的 LVGL）

LVGL Skills 模块

1. 定义

• 默认参考参数: 800x480, RGB565, 内存池 320KB（用于初始开发，不作为分辨率绑定）
• 用途: 约束 LVGL UI 代码生成，确保工程化、可维护、可移植
• 适用场景: ESP32-S3 / K230 / 其他 MCU 嵌入式小屏设备；同一套 UI 需可适配多种分辨率屏幕

2. CRITICAL（唯一禁止清单）

• 禁止 将 UI 代码写在 app_main() 或 main() 中
• 禁止 demo 风格代码（单函数堆砌控件）
• 禁止 UI 与业务逻辑耦合
• 禁止 在事件回调中编写复杂业务逻辑
• 禁止 单文件包含多个 screen
• 禁止 写死像素位置、固定宽高、魔法数布局
• 禁止 使用不基于屏幕参数的绝对坐标布局

3. 架构

3.1 工程基线（官方开发板 + GUI Guider 可移植）

• 新项目默认沿用本工程架构，确保可直接套用 GUI Guider 生成代码
• 允许保留 generated 自动生成层与 custom 手写扩展层并行
• UI 业务扩展优先写在手写层，避免直接改动生成文件导致下次导出覆盖

main/
├── APP/
│   ├── lvgl_demo.c                 # LVGL初始化、tick、主循环
│   └── ui/                         # 项目UI手写层（建议）
│       ├── ui_manager.h
│       ├── ui_manager.c
│       ├── screens/
│       └── components/

components/
└── BSP/
    ├── generated/                  # GUI Guider 导出层（setup_scr_xxx / events_init / gui_guider）
    └── custom/                     # 手写扩展层（定时器、业务桥接、二次封装）

3.2 GUI Guider 兼容约束

• GUI Guider 生成文件作为 UI 结构基底，负责控件创建和基础事件挂载
• 手写代码通过 custom 或 main/APP/ui 对生成层进行调用与扩展
• 页面切换可复用生成层的 ui_load_scr_animation(...)，或在 ui_manager 中统一封装
• 生成层与手写层之间只通过明确接口交互，避免跨层直接修改内部对象

布局规范（分辨率自适应）

• 所有布局必须由 screen_width、screen_height 驱动
• 必须定义 padding_left/right/top/bottom
• 统一可用区域：usable_width = screen_width - padding_left - padding_right
• 位置与尺寸必须通过计算得到，优先相对布局与对齐布局
• 文本必须按可用宽度约束，并在必要时调用 lv_obj_update_layout()
• 动画位移必须基于屏幕尺寸或元素尺寸计算
• 必须支持不同分辨率（如 240x240 / 320x240 / 480x320 / 800x480）、不同 padding、不同字体大小
• GUI Guider 导出后如出现固定坐标/固定尺寸，必须在手写层进行参数化与比例化改造后再用于项目

4. Screen

• 每个界面必须独立模块（一个 .c + 一个 .h)
• 必须包含 create()、destroy()、event_handler()

lv_obj_t *scr_xxx_create(void);
void scr_xxx_destroy(void);
static void scr_xxx_event_handler(lv_event_t *e);

5. Component

• 组件必须可复用
• 组件必须参数化创建
• 组件接口必须接受 parent 参数

lv_obj_t *comp_btn_create(lv_obj_t *parent, const char *text, lv_event_cb_t cb, void *user_data);

6. ui_manager

• 负责页面初始化、切换、生命周期管理
• 切换流程：destroy(old) -> create(new) -> lv_scr_load()/lv_scr_load_anim()
• 推荐函数指针注册表管理页面

7. 事件

• 所有用户交互使用 lv_obj_add_event_cb()
• 回调签名：static void xxx_event_cb(lv_event_t *e)
• 回调只做事件识别、UI 更新、业务接口调用

8. 内存

• lv_obj_create 创建对象必须可回收
• 页面切换必须确保旧页面已释放
• 动态 user_data 在 LV_EVENT_DELETE 中释放
• 页面销毁时同步释放相关定时器与动画资源

9. 定时器动画

• 使用 lv_timer_create() / lv_timer_del() 成对管理
• 动画使用 lv_anim_t + lv_anim_init() + lv_anim_start()
• 定时器回调禁止阻塞

10. 代码风格

• 语言：C
• 文件命名：scr_ 页面，comp_ 组件，ui_ 管理模块
• 函数命名：模块名_动作，如 scr_home_create()
• 内部辅助函数与回调使用 static

11. AI 约束

• 必须复用 screens/ + components/ + ui_manager/ 架构
• 必须兼容“官方开发板工程 + GUI Guider generated/custom 分层”
• 必须确保同一套 UI 代码可适配多种分辨率屏幕
• 必须实现页面模块化与生命周期接口
• 必须遵循 CRITICAL 唯一禁止清单