# kk_ui **Repository Path**: keysking/kk_ui ## Basic Information - **Project Name**: kk_ui - **Description**: 一套以 Agent Skills 的方式提供的轻量级单色 OLED 菜单 UI 系统，提供首页图标选择器、可嵌套菜单、常用页面、变量编辑、提示覆盖层、三键与编码器交互，以及流畅非线性动画。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 75 - **Forks**: 12 - **Created**: 2026-09-10 - **Last Updated**: 2026-10-04 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # KK_UI KK_UI 是一套依赖 [KK_OLED](https://gitee.com/keysking/kk_oled) 的轻量级 C 语言单色 OLED 菜单 UI 系统，提供首页图标选择器、可嵌套菜单、常用页面、变量编辑、提示覆盖层、三键与编码器交互，以及流畅的无回弹非线性动画。 KK_UI 面向资源受限的嵌入式设备，采用单例、静态页面拓扑和固定容量状态：不使用动态内存，不建立通用控件树，也不额外分配帧缓冲。应用负责页面描述、业务状态、字体和图标；KK_UI 负责导航、交互、动画、完整场景绘制与刷新调度。 ```text 应用页面与业务 ↓ KK_UI ↓ KK_OLED ↓ 显示控制器与总线驱动 ``` 当前正式参考布局为 128×64、1 bit 单色图形 OLED。其他主流 1 bit 单色屏不依赖运行时自动缩放，而是由移植 Skill 根据目标工程的实际逻辑尺寸调整可编辑源码副本。 ## 效果预览 以下动画来自正式 KK_UI 运行时、真实 KK_OLED graphics 和参考应用产生的 128×64 framebuffer，不是手工绘制的概念图。 | 首页图标选择器 | 普通菜单与嵌套导航 | |---|---| | ![首页图标选择器](assets/previews/home.gif) | ![普通菜单与嵌套导航](assets/previews/menu.gif) | | 整数编辑 | 开关编辑 | |---|---| | ![整数编辑](assets/previews/integer_editor.gif) | ![开关编辑](assets/previews/bool_editor.gif) | | 只读信息页与滚动 | 全屏自定义页、波形与进度条 | |---|---| | ![只读信息页与滚动](assets/previews/info_page.gif) | ![全屏自定义页、波形与进度条](assets/previews/custom_page.gif) | | 确认框与消息框 | Toast 提示 | |---|---| | ![确认框与消息框](assets/previews/dialogs.gif) | ![Toast 提示](assets/previews/toast.gif) | | 条目隐藏、禁用与返回 | |---| | ![条目隐藏、禁用与返回](assets/previews/menu_states.gif) | ## To 人类 如果目标工程还没有 KK_OLED，可以直接告诉你的编程 Agent（Codex、Trae 等均可）： > 将 https://gitee.com/keysking/kk_oled 和 https://gitee.com/keysking/kk_ui 中所提供的 Skills 添加到当前工程。根据项目实际情况接入 KK_OLED 和 KK_UI，并制作kk_ui的演示Demo。 如果当前工程尚未配置屏幕通讯和按键相关引脚，则按实际情况修改并使用如下Prompt： > 将 https://gitee.com/keysking/kk_oled 和 https://gitee.com/keysking/kk_ui 中所提供的 Skills 添加到当前工程。根据项目实际情况接入 KK_OLED 和 KK_UI，并制作kk_ui的演示Demo。 > 需要你帮我使用如下硬件：使用，SDA引脚为，SCL引脚为，UP按键引脚为, DOWN按键引脚为，OK按键引脚为 Agent 会先检查目标工程中已有的源码、构建配置、显示刷新方式和输入硬件，再选择对应的 Skill。安装后的 KK_UI 源码属于目标工程，可以继续修改，不是不可编辑的外部二进制库。 首次接入需要初始应用时，即使只要求“移植”，没有明确产品界面需求也会接入配套标准 Demo；无需先设计菜单。已有产品界面和本地修改继续保留，有具体产品需求时按需求实现。 标准 Demo 上电停在图标首页，包含“设置”“数据监测”“波形”“关于设备”四个入口。屏幕亮度编辑会实时控制支持该能力的 OLED，对比度修改可取消回滚；其他条目以开关、确认框、消息框、Toast 等组件名称展示。组件演示包含条目隐藏/禁用，波形进度自动运行、按方向键切换手动并显示波形页绘制 FPS。128×64 使用参考字体、图标、行高和动画。 Demo 自带应用、字模和图标，复制到项目自身源码目录后参与构建；文字和字号不变时直接复用资源。动画间隔实际控制波形速度；开关只演示临时状态。全部设置断电后恢复默认。移植时检查 `OLED_SetContrast()`：支持则接入实屏亮度，不支持则禁用条目并说明。完整接入与操作说明见 [标准 Demo](skills/kk-ui-use/references/standard-demo.md)。 ## To Agent 以下仅是建议，一切以用户的实际习惯、命令和目标工程为准： 1. 下载或克隆本仓库以及 KK_OLED 仓库。 2. 从本仓库的 `skills/` 中复制所有的完整 Skill 文件夹到目标工程的 Skill 目录中，通常是 `.agents/skills/`。 3. 按客户端要求重新加载 Agent、IDE 扩展或会话，使项目级 Skills 被重新发现。 4. 根据目标工程实际情况接入 KK_OLED 与 KK_UI；平台、总线或显示控制器问题使用 KK_OLED 对应的移植 Skill 处理。不要求 KK_OLED 先显示检测画面，也不指定目标工程使用的调试、下载或测量工具。 5. 首次接入、平台迁移、输入与刷新适配或显示尺寸迁移使用 `kk-ui-port`。首次接入未指定产品界面、需要初始应用时，衔接 `kk-ui-use` 安装完整标准 Demo，不停在最小菜单。工程已有 KK_UI 或产品界面时，以现有源码和本地修改为准，不得使用 Skill 资产静默覆盖。 6. 标准 Demo 安装及首页、菜单、信息页、变量绑定、事件、提示和自定义页面使用 `kk-ui-use` 在应用层实现。标准 Demo 使用已确定的方案；产品需求尚未明确时再讨论实际业务界面。 7. 只有内置模板和自定义页被证明无法合理完成需求，且用户明确同意扩展核心后，才使用 `kk-ui-extend`。 8. 沿用目标工程已有的构建、测试、运行和验收方式，说明已经执行的结果与仍待验证的内容，不用一种证据代替另一种证据。 目标工程不得直接把 Skill 的 `assets/` 目录作为构建输入。首次安装时应从资产建立一份独立、可编辑的项目源码副本。 标准 Demo 初始化顺序为 `OLED_Init()` 成功后调用 `KK_UI_AppReset(now_ms)`，随后 `KK_UI_Init(KK_UI_AppGet())`；循环依次调用 `KK_UI_AppUpdate()`、`KK_UI_Update()` 和 `KK_UI_AppProcessEvents()`。屏幕尺寸和刷新方式按目标工程实际信息显示。实屏条件暂不具备时完成其他可执行验证，并明确列出待验内容。 ## BaudForge 本仓库同时可作为 BaudForge 软件组件包使用。只需要在BaudForge工程的蓝图中添加kk_oled组件包和本kk_ui组件包，并为配置好相关配置即可。 ## 包含的 Skills | Skill | 用途 | 适用场景 | |---|---|---| | `kk-ui-port` | 首次接入、平台迁移、构建与刷新接线、输入适配和 1 bit 屏幕尺寸迁移 | 接入或迁移 KK_UI | | `kk-ui-use` | 安装完整标准 Demo，或建立首页、菜单、信息页、变量绑定、业务事件、提示和自定义页面 | 默认演示及具体产品界面开发 | | `kk-ui-extend` | 严格评估并扩展具有跨页面或跨项目复用价值的核心能力 | 内置模板和自定义页不足时评估核心扩展 | 三个 Skill 只面向 KK_UI。字体子集与缺字使用 KK_OLED 提供的 `kk-oled-font`；MCU、I2C/SPI 和 OLED 控制器驱动问题使用 `kk-oled-port`。 每个 Skill 的入口是其 `SKILL.md`，其中会按需引用 `references/`、`scripts/` 和 `assets/`。`agents/openai.yaml` 是可选的 OpenAI 客户端元数据，其他 Agent 可以忽略；本仓库不依赖 Codex Plugin。 ## 主要功能 - 带大图标和动态文字标签的横向首页选择器。 - 静态声明、可按配置深度嵌套的普通菜单。 - 菜单项动态隐藏、禁用和焦点自动修复。 - 带标题的只读信息页和应用完全控制的全屏自定义页。 - `int32_t` 整数编辑和 `bool` 开关编辑。 - 确认框、消息框和不透明非模态 Toast。 - 上、下、确定三键输入，以及旋转编码器档位输入。 - 固定容量 FIFO 业务事件队列。 - 时间驱动、允许跳帧、无回弹的非线性动画。 - Blocking、IT 或 DMA 刷新调度，以及异步超时和显示恢复。 - 进度条、焦点框、按钮、滚动条和开关等无状态绘制辅助。 - 页面和覆盖层独立编译开关，支持链接器裁剪未使用能力。 ## 设计边界 KK_UI 的重点是菜单和嵌入式设备常用页面，不发展成通用 GUI 框架。 - 不使用 `malloc`、`calloc`、`realloc` 或 `free`。 - 不建立运行时控件树、动态菜单容器或任意回调注册系统。 - 页面拓扑、跳转关系、变量绑定类型和事件 ID 在编译期确定。 - 动态能力仅用于长期有效的文字、变量值和菜单项显示状态。 - KK_UI 不创建额外 framebuffer；绘制缓冲和异步发送缓冲由 KK_OLED 持有。 - KK_UI 只依赖 KK_OLED 公共接口，不直接依赖 STM32 HAL、GPIO、I2C 或 SPI。 - 字体、图标、动态文字、变量和业务状态由应用层长期持有。 - 业务专用交互、波形和运行时数据列表优先使用全屏自定义页。 - 应用和自定义页不得绕过 KK_UI 并行清屏或提交完整画面刷新。 公共接口以运行时快照中的 `include/kk_ui.h` 和 `include/kk_ui_draw.h` 为准；配置默认值位于 `include/kk_ui_config.h`。 ## 仓库结构 ```text assets/previews/ README 动态预览 skills/kk-ui-port/ 移植 Skill skills/kk-ui-port/assets/kk-ui-runtime/ 可编辑 KK_UI 运行时快照 skills/kk-ui-use/ 应用开发 Skill skills/kk-ui-use/assets/kk-ui-demo/ 可编辑标准 Demo、字体与图标快照 skills/kk-ui-extend/ 受控扩展 Skill ``` 发布仓库中的运行时快照来自 KK_UI 开发仓库的正式源码。目标工程已有 KK_UI 时，Agent 必须先比较现有实现和本地修改，只做任务需要的增量变更。 ## 显示兼容与参考结果 KK_UI 当前验证目标是通过像素亮灭构成画面的 1 bit 单色图形 OLED。面板实际发光颜色不会改变 UI 数据模型。 当前参考工程采用 128×64 逻辑分辨率、三键与可选编码器输入，并验证了异步 DMA 刷新。换 MCU、SDK、总线或显示控制器属于 KK_OLED 移植范围。 迁移到 128×32、64×48 或其他 1 bit 尺寸时，`kk-ui-port` 会根据 KK_OLED 旋转后的逻辑宽高调整字体、图标、标题高度、行高、可见行数、边距、弹框和裁剪区域，并优先保持交互语义。第一版不提供运行时自动缩放、多分辨率布局档位、灰度或彩色像素格式支持。 当前完整功能 Release 参考结果： | 项目 | 测量结果 | |---|---:| | KK_UI 源文件已链接 Flash | 11,040 B | | KK_UI 单例静态 RAM | 416 B | | KK_UI 新增 framebuffer | 0 B | | KK_UI 最大单函数静态栈 | 120 B | 这些数字来自当前参考工程和特定工具链，不是所有编译器、配置与应用资源下的固定值。 ## 版本与许可证 - 版本：`0.1.0` - 许可证：MIT - 版权主体：青岛波特律动科技有限公司（Qingdao BaudDance Technology Co., Ltd.） 本仓库中的第一方 KK_UI 源码和 Skill 内容采用 [MIT 许可证](LICENSE)。应用使用的字体、图标和其他第三方资源仍受其各自许可证约束，不因采用 KK_UI 而自动转为 MIT 许可。