AI语音智能体开发日记（九）LVGL 8.4.0 中文字体配置全攻略

开发手记：LVGL 8.4.0 中文字体配置全攻略

在嵌入式GUI开发中，让屏幕正确显示中文往往是新手遇到的第一个"拦路虎"。默认的LVGL库通常只包含基础的ASCII字符，直接显示中文会变成方块或乱码。

今天这篇博客，我将详细记录在LVGL 8.4.0版本中，从零开始配置中文字体的完整流程。

我们将使用"阿里巴巴普惠体"作为示例，解决从字体获取、转换到代码适配的所有问题。

第一步：获取并转换字体文件

LVGL不能直接使用.ttf或.otf等矢量字体文件，我们需要将其转换为C语言数组。

选择字体

首先，我们需要一个支持中文且可免费商用的字体。这里推荐使用阿里巴巴普惠体 ，它字形清晰，非常适合屏幕显示。你可以从其官网或其他可信渠道下载.ttf格式的字体文件。阿里巴巴普惠体电脑版下载2026最新_阿里巴巴普惠体pc版免费下载_华军软件园
在线转换

LVGL官方提供了一个非常方便的在线字体转换工具：LVGL Font Converter。Font Converter --- LVGL
- Name : 给你的字体起个名字，例如 myFont。
- Size : 设置字体大小，例如 16。
- Bpp : 设置位深，4 bit-per-pixel 能在清晰度和内存占用之间取得不错的平衡。
- TTF/WOFF font : 点击"Browse"上传你下载的 AlibabaPuHuiTi-3-35-Thin.ttf 文件。
- Symbols: 这是最关键的一步！中文字库非常庞大，全部转换会导致生成的C文件巨大，耗尽MCU的Flash。因此，我们只转换项目实际需要用到的汉字。将所有需要用到的汉字（例如"重庆七月小玉门敦煌..."等）复制粘贴到这个文本框中。
- 点击"Submit"按钮，即可下载生成好的 myFont.c 文件。

第二步：将字体文件集成到工程

放置文件

将下载好的 myFont.c 文件复制到LVGL库的字体目录下。根据我们的项目结构，路径为：

project/ln_model_public/components/gui/lvgl-8.4.0/src/font/
版本兼容性修复（关键步骤）

由于LVGL版本迭代，在线转换工具生成的代码可能与LVGL 8.4.0不完全兼容，直接编译会报错。我们需要手动修改 myFont.c 文件。
- 打开 myFont.c，找到大约第217行，你会看到如下代码：
  复制代码
```
.static_bitmap = 0,
```
- 将其修改为条件编译的形式：
  复制代码
```
#if LVGL_VERSION_MAJOR >= 9
    .static_bitmap = 0,
#endif
```
这样修改后，.static_bitmap 字段只会在LVGL 9.x及以上版本中被包含，从而完美兼容LVGL 8.4.0。

第三步：在LVGL中注册新字体

文件就位后，我们需要在LVGL的配置文件中声明并启用它。打开 project/ln_model_public/components/gui/lvgl-8.4.0/lv_conf.h 文件进行修改。

声明字体

在 lv_conf.h 文件中找到 LV_FONT_CUSTOM_DECLARE 宏定义的位置（大约在第422行），添加我们的字体声明：
复制代码
```
#define LV_FONT_CUSTOM_DECLARE LV_FONT_DECLARE(myFont)
```
如果需要声明多个自定义字体，可以这样写：
复制代码
```
#define LV_FONT_CUSTOM_DECLARE \
    LV_FONT_DECLARE(alFont12) \
    LV_FONT_DECLARE(alFont18) \
    LV_FONT_DECLARE(alFont24)
```

设置为默认字体

接着，找到 LV_THEME_DEFAULT_FONT_NORMAL 宏定义（大约在第481行），将其指向我们的新字体：

复制代码

#define LV_THEME_DEFAULT_FONT_NORMAL &myFont //默认生成的字体文件

LVGL主题有四种字体设置：小字体、默认字体、副标题字体和标题字体。我们将最常用的"默认字体"替换为自定义的中文字体，这样大部分文本都能正常显示中文了。

复制代码

#define LV_THEME_DEFAULT_FONT_SMALL &lv_font_montserrat_16 //小字体
#define LV_THEME_DEFAULT_FONT_NORMAL &myFont //默认字体，我们默认使用这个
#define LV_THEME_DEFAULT_FONT_SUBTITLE &lv_font_montserrat_16 //副标题字体
#define LV_THEME_DEFAULT_FONT_TITLE &lv_font_montserrat_16 //标题字体

第四步：编写代码验证效果

最后，我们来编写一段测试代码，验证字体是否配置成功。在 usr_app.c 的 usr_app_task_entry 函数中，创建两个标签（Label）来分别显示数字和中文。

编译并烧录固件后，如果一切顺利，你的屏幕左上角将会清晰地显示出"2026"和"重庆"。

总结

为LVGL添加中文字体，核心流程就是"获取TTF -> 在线转换 -> 修复兼容 -> 配置声明 -> 代码使用"。

其中有两个关键点需要特别注意：

按需转换：务必在转换工具中只输入项目实际用到的汉字，避免生成的C文件过大。
版本兼容：LVGL 8.4.0需要手动修改生成的C文件，通过条件编译来规避版本差异导致的编译错误。