xiaozhi-esp32LVGL中文乱码字体 fallbackCJK豆腐块

xiaozhi / LVGL 中文乱码 — 裸字体缺 fallback(xiaozhi-lvgl-cjk-font-fallback)

解决屏幕上中文显示为豆腐块 / 空白,根因是 label 用了裸 lv_font_t* 指针缺 fallback 链

一、这个 skill 是做什么的

当你的 xiaozhi-esp32 / ESP-IDF LVGL 项目里,"屏幕上的中文显示为乱码(豆腐块)或空白"——典型如城市名、天气描述、自定义中文 label 不显示,而系统自带的日期 / 农历 / 菜单中文却正常——就用这个 skill。

根因几乎总是:给 label 绑了"裸 lv_font_t* 指针"(如 &font_noto_sans_basic_14_1),它没有 fallback 链,字库只含极少量汉字。

修复方法是改用 theme->text_font()->font()(common 版 cbin,带动态字形缓存)。它也覆盖"直接解析 cbin / 字体 C 源码验证字形覆盖"的方法,帮你确认根因。

二、什么时候用它

三、前置条件 / 准备

四、具体用法(步骤)

① 找到所有裸字体用法

搜项目里的 font_noto_sans_basic 用法(排除声明宏),重点看 main/display/lcd_display.cc 里日历页 / 自定义页的 label。

② 改为 theme 字体

把 const lv_font_t* small_font = &font_noto_sans_basic_14_1;(裸指针,无 fallback)改成 const lv_font_t* small_font = text_font;(text_font = lvgl_theme->text_font()->font(),含完整 CJK + 动态 fallback)。

③ 创建处 + SetTheme 处都要改

两处缺一不可:CreateXxxPage 里绑定的字体,以及 SetTheme() 里重新绑定的字体——后者若不改,assets 加载后会持有旧字体指针甚至野指针。

④ 尺寸中性检查

basic_14_1 与 common_14_1 的 line_height 都是 16,互换不影响布局(basic_16_4/common_16_4=25;30_4=43)。

⑤ 编译验证

Windows 遇并发冲突按上面处理;编译通过即说明字体指针改对了。

进阶 / 可选:这两步是真正"定位裸字体"和"验证字形覆盖"的操作(需要本地环境)。第一句搜出所有裸字体用法;后面是用 Python 读 cbin 看这个字体到底含多少汉字。
# 1) 找出所有裸字体用法(排除声明宏) grep -rn "font_noto_sans_basic" main/ | grep -v "LV_FONT_DECLARE" # 2) 读 cbin 看字形覆盖(验证根因) python -c "import struct; d=open('font_noto_sans_common_14_1.bin','rb').read(); print('common 总码点/ CJK 数见解析结果')"

五、可直接照用的示例

你:我的小屏上城市名和天气描述显示成方块了,但日期和农历都正常,这是咋回事?

AI大模型或AI智能体:这是典型"裸字体缺 fallback"——你给城市名那个 label 绑了裸 &font_noto_sans_basic_14_1,这个精简字体只有 206 个汉字,且全是系统功能字,地名用字(佛山广州多云雨晴阴)全缺。而日期农历用的是 theme->text_font(),含 5377 个汉字所以正常。我把那个 label 改成用 text_font 就行,记得 CreateXxxPage 和 SetTheme 两处都改。

你:我把字体从 basic 换成 common 了,怎么显示还是乱码?

AI大模型或AI智能体:很可能你只改了 CreateXxxPage 一处,SetTheme() 里还绑着旧裸字体——assets 加载后主题刷新会把字体改回旧值甚至野指针。两处必须同步改。另外别被字体 C 源码里的 range_length=63692 骗了,SPARSE 类型实际只认 unicode_list 里那 531 项,不能据此说"覆盖全部 CJK"。

六、常见注意 / 避坑

七、相关 skill / 延伸

← 返回 SKILL 库