控制台 退出登录
已成型 · 内部固件工具链 嵌入式 UI / 代码生成 / C99

XML-LayoutKit · 嵌入式屏幕声明式 UI 布局工作流

把 XML 作为嵌入式小尺寸屏幕(OLED / TFT)布局的单一事实来源:在构建期将声明式标签编译为零堆内存分配的 C99 `const` 静态布局表,并同步生成 PC 端像素级预览图。

XML Layout Python 3 Codegen C99 Static Structs Zero Runtime XML Overhead SSD1306 / ST7789
XML-LAYOUTKIT COMPILER · SINGLE SOURCE OF TRUTH 1. 声明式布局源文件 (panel_home.xml) <Screen width="128" height="64" pad="2"> <Row id="bar" height="14" align="between"> <Label id="title" text="ENV-MON"/> <Badge id="net" bind="mqtt_ok"/> </Row> <Column id="body" top="18" gap="4"> <BigNum id="val_t" bind="temp_c"/> <ProgressBar id="bar_h" max="100"/> </Column> </Screen> ✓ 构建期自动检查越界 (x+w <= 128) 2. 生成只读 C 表 (ui_panel_home.h) /* Auto-generated. DO NOT EDIT. */ static const UiWidget kHomeWidgets[] = { {UI_ROW, 2, 2, 124, 14, BIND_NONE}, {UI_LABEL, 4, 4, 56, 10, BIND_NONE}, {UI_BIGNUM,4, 20, 120, 24, BIND_TEMP}, {UI_BAR, 4, 48, 120, 8, BIND_HUMI} }; 3. 固件端极简渲染循环: MCU 无需解析 XML 字符串! 直接遍历 Flash 中的 kHomeWidgets 零 malloc · 编译耗时 < 40ms

01 能做什么(核心应用场景)

场景 A · 告别手算像素坐标

用 Row / Column 容器替代魔法数字

传统嵌入式写屏幕界面常出现满屏 `draw_str(14, 38, ...)`,插入一个图标就要重算后面所有元素坐标。用 XML 声明间距与对齐方式后,由构建脚本在编译期自动完成盒模型坐标求解。

场景 B · 不依赖真实硬件的 PC 端即时预览

修改保存即出像素级线框图

无需每次改完坐标都经历“交叉编译 → 串口烧录 → 盯屏幕看有没有偏 2 像素”的漫长循环。构建脚本直接渲染出 1:1 的屏幕边界预览图并高亮越界控件。

场景 C · 严苛 MCU 内存环境零负担运行

构建期静态展开,MCU 端 0 字节堆开销

所有 XML 解析与布局计算全部在开发机 Python 环境中完成,最终塞进固件的只有紧凑的 `const` 结构体数组(存放在 Flash ROM),哪怕只有几 KB RAM 的单片机也能直接复用。

02 我是怎么实现的(编译管线与工程取舍)

构建期静态编译与双端输出管线(支持点击放大查看)
1. XML 布局源码 • 屏幕尺寸与边距约束 • Row / Column 嵌套 • 数据绑定枚举键名 2. Python 布局求解器 • XSD 属性合法性校验 • 相对坐标转绝对坐标 • 越界与重叠静态报错 3A. 嵌入式固件头文件 (ui_generated.h) 每个控件仅占 12 Bytes `const` ROM 由 CMake/Makefile 在编译固件前自动触发 3B. PC 端像素预览图 (SVG / Framebuffer) 直观展示各控件 Bounding Box 与字号对齐 支持与设计稿或文档直接比对

关键技术选择与原因

  • 为什么选 XML 而非 JSON/YAML:UI 布局天然是树状嵌套结构,XML 的闭合标签与属性语法在表达 `` 时比缩进敏感的 YAML 或满屏大括号的 JSON 更直观,且可借用现成 XSD 能力在编辑器里做属性补全。
  • 为什么坚持“构建期编译”而非“运行时解析”:在 STM32 / ESP32 等嵌入式设备上,运行时解析 XML 既浪费宝贵的 RAM 又容易产生内存碎片;把解析放到 PC 构建阶段,设备端只读定长数组,兼顾开发效率与极致性能。

遇到的典型问题与工程取舍

  • 问题:动态长文本导致静态布局溢出 —— 传感器数值或状态文字长度变化时可能超出预设宽度。解决:在编译期强制为动态绑定字段生成 `max_width` 裁剪边界,渲染层超出宽度时自动安全截断,杜绝覆盖右侧图标。
  • 取舍:不支持复杂的弹性折行(Flex-wrap) —— 为了保证 C 端渲染器代码量控制在 300 行以内,主动放弃了复杂的流式折行,仅保留嵌入式最常用的固定宽高、`Row`、`Column` 与对齐属性。

03 如何集成到固件构建流

1. CMake / Makefile 自动生成集成

# 在固件 Makefile 中加入预构建规则:
UI_XML_SRCS := $(wildcard ui_layouts/*.xml)
UI_GEN_HDR  := include/ui_generated.h

$(UI_GEN_HDR): $(UI_XML_SRCS) tools/xml_layout_compiler.py
	python3 tools/xml_layout_compiler.py \
		--input ui_layouts/ \
		--output-header $(UI_GEN_HDR) \
		--preview-dir build/ui_preview/

2. C99 固件端控件结构定义

typedef struct {
    uint8_t  type;      // UI_LABEL, UI_ICON, UI_BAR...
    uint8_t  x, y;      // 构建期已算好的绝对像素坐标
    uint8_t  w, h;      // 裁剪宽高边界
    uint8_t  bind_id;   // 绑定的遥测变量枚举 ID
    const char *text;   // 静态文本指针 (ROM)
} ui_widget_t;

公开范围与已知限制说明:本工作流是我在嵌入式小屏项目中提炼的工程方法论,核心设计思路、单源约束原则与代码结构已在下方技术文章中详细阐述;当前主要针对 128×64 单色 OLED 与 240×240 TFT 状态屏,暂不包含触摸事件路由。

04 开发记录与关联文章

版本演进与下一步计划

  1. v1.1 · 2026-03

    增加构建期越界静态检查(Out-of-Bounds Check)与 SVG 线框预览导出能力。

  2. v1.0 · 2026-01

    完成基础 `Screen / Row / Column / Label` 标签解析与 C99 `const` 结构体数组生成器。

  3. Next · 规划中

    支持脏矩形局部刷新(Dirty Region)标记生成,进一步降低 SPI 屏幕刷新耗时。