一、这个 skill 是做什么的
当你在 128×160 / 240×320 这类小屏幕上看到"某一行只露出半截、像被上一行压住",或者左右两块文字互相挤压、数字被吃掉,就用这个 skill。
最常见的真根因:行容器的高度小于字体 line_height,文字被纵向裁剪(尤其换了字体后,行高变了而容器高度没跟着变)。比如容器设了 18px,但字体 line_height 是 25px,文字顶端 7px 就被裁掉了,看起来就像被上一行"压住"。
它也覆盖横向挤压、flex 把最后子项挤出、flex_grow 居中溢出等其它根因,并给出"先跑几何预算再烧录"的方法,避免你反复烧录试错。
二、什么时候用它
- "小屏上状态行 / 天气行只露出半截,像被压住。"
- "同一行里『云』压住了『18』的『1』,数字被吃掉。"
- "换了字体之后文字显示不全了。"
- "顶部行被盖住,中间行溢出到别的区域。"
- "单独看代码每块高度都对,就是放不下。"
三、前置条件 / 准备
- xiaozhi-esp32 / ESP-IDF / 纯 LVGL 项目(C/C++ 代码层)。
- 需要确认你实际加载的字体的 line_height(运行时实际字体可能与编译期兜底不同)。可用 grep 查字体 C 源码,或用
struct.unpack_from 读 cbin 二进制(lv_font_t.line_height 在 +12 偏移)。
- 建议准备一段 Python 几何预算脚本,排版前先算各块 y 区间、查相交与超屏。
四、具体用法(步骤)
① 诊断(先查 90% 的真根因)
打印各 label 字体的 line_height,和父容器高度对比——只要容器高 < line_height 就会裁字。改字体时(比如为显示中文从 basic 换到 common)最容易中招,因为只关注字库覆盖,忽略了行高变了。
② 修复纵向裁剪
容器高度 = max(设计高度, 字体 line_height)。空间不够就减字号或换小字号字体,而不是硬压容器高度。
③ 修复横向挤压
做宽度预算:图标宽 + 间隙 + 左侧文字 + 右侧文字 ≤ 可用宽(屏宽 - 左右 padding)。用"固定宽 + LV_LABEL_LONG_MODE_DOTS 截断"保证数值侧完整,不被吃掉。
④ 正解架构:固定高度 + 绝对定位 + 显式 y 区间
父容器三块全部 IGNORE_LAYOUT + 绝对定位 + 显式互不相交的 y 区间;中栏高度 = 屏高 - pad上下 - top_h - bottom_h。
进阶 / 可选:这段 C 代码是"顶栏 / 中栏 / 底栏三块互不重叠"的标准写法(仅需在项目里照此调整高度与对齐,不用全文照搬)。
// 三块全部脱离 flex 流,绝对定位、区间互不相交
lv_obj_t* top = lv_obj_create(page);
lv_obj_add_flag(top, LV_OBJ_FLAG_IGNORE_LAYOUT);
lv_obj_set_height(top, 24); // ≥ 字体 line_height
lv_obj_align(top, LV_ALIGN_TOP_MID, 0, 0);
lv_obj_t* mid = lv_obj_create(page);
lv_obj_add_flag(mid, LV_OBJ_FLAG_IGNORE_LAYOUT);
lv_obj_set_height(mid, 109); // = (屏高-pad上下) - top_h - bottom_h
lv_obj_align(mid, LV_ALIGN_TOP_MID, 0, 24);
lv_obj_t* bottom = lv_obj_create(page);
lv_obj_add_flag(bottom, LV_OBJ_FLAG_IGNORE_LAYOUT);
lv_obj_set_height(bottom, 24);
lv_obj_align(bottom, LV_ALIGN_BOTTOM_MID, 0, 0);
⑤ 改字号 / 字体时两处都要改
CreateXxxPage() 和 SetTheme() 两处都要改,否则主题刷新(assets 加载后)会把字体改回旧值,问题复发。
五、可直接照用的示例
你:我的小屏天气行只露出半截字,像被上一行压住了,但每块高度我都对过没问题啊。
AI大模型或AI智能体:八成是"容器高度 < 字体行高"被纵向裁了。比如你容器设了 18px,但换字体后 line_height 变成 25px,顶上 7px 就被裁掉。你把天气行的容器高度改成 ≥ 字体 line_height(空间不够就减字号),而不是硬压容器。改完记得 CreateXxxPage 和 SetTheme 两处字体都要同步。
你:同一行里"云"把"18"的"1"压住了,数字被吃掉一块。
AI大模型或AI智能体:这是横向宽度超了。你要先预算:图标宽 + 间隙 + 左文字 + 右文字 ≤ 可用宽。128px 屏可用约 120px,左侧「🌡26°多云」约 77px + 右侧「18~27°」约 52px = 129px 就超了。做法:给左或右设固定宽 + LV_LABEL_LONG_MODE_DOTS 自动省略号,保证数值优先完整。注意这个 DOTS 模式需要 label 有确定宽度,不能用 LV_SIZE_CONTENT。
六、常见注意 / 避坑
- 90% 情况是容器高度 < 字体行高导致裁字,先查这个,别急着改布局。
- 不要按字号猜行高:要用实际加载字体的 line_height(实测 basic_16_4=23,common_16_4=25,30_4=43),编译期兜底字体和运行时实际字体可能不同。
- IGNORE_LAYOUT 不阻止被压住:
LV_OBJ_FLAG_IGNORE_LAYOUT 只让元素脱离 flex 分配,必须保证每个元素的绝对区间互不相交。
- 横向 DOTS 需要确定宽度:
LV_LABEL_LONG_MODE_DOTS 要求 label 有固定宽(不能用 LV_SIZE_CONTENT)才生效;LVGL9 枚举名是 LV_LABEL_LONG_MODE_DOTS。
- 改字体两处都要改:
CreateXxxPage 和 SetTheme 都要改,图标字体也算,否则主题刷新后回归。
- 空间不够三板斧:减字号(最有效,30_4→20_4 省 15px)→ 减 padding → 删减信息行。128×160 屏可用高仅约 157px,极紧。
七、相关 skill / 延伸
- xiaozhi-lvgl-cjk-font-fallback:xiaozhi 中文显示为豆腐块 / 空白(裸字体缺 fallback),常和本 skill 的排版问题一起出现。
- esp32-spi-tft-whitescreen-debug:SPI TFT 屏幕白屏排查。
- reportlab-cjk-pdf-layout:虽是 PDF,但同样涉及"排版溢出 / 重叠"的排查思路,可借鉴其"先预算几何再动手"的方法。