简介面向单片机与嵌入式开发者的 LVGL 中文拼音输入法完整工程基于 LVGL 8.0.1 改写 lv_keyboard.c新增 lv_cn_keyboard.c 及以 lv_cn_ 开头的对外接口实现键盘按键输入、拼音候选字匹配与触摸点选。工程使用 Qt 5.14 创建打开即可运行模拟器并附带 QT 编译报错时的构建目录调整说明适合需要为 MCU 界面快速集成中文输入的开发者参考。压缩包共 897 个文件约 22.71MB以 342 个 C、245 个 H 源码文件为主体覆盖 LVGL 底层组件与新增键盘实现此外包含 md 文档、py 辅助脚本、png/jpg 界面预览图及 pro/ino 等工程文件便于直接编译、查看界面效果并二次移植到单片机工程。目前已有 1704 人学习下载。通过该工程可以直观理解拼音输入法在 LVGL 控件体系下的扩展思路获得自带中文字库与字体资源、可直接仿真验证的完整代码减少从零搭建中文输入键盘的工作量。1. 在 QT 仿真里先解决中文输入再交给 LVGL 8.0.1 真机做 HMI 项目时我遇到过最别扭的场景屏幕上的文本框只能敲英文和数字操作员想把设备备注改成中文只能等上位机下发。后来把方案落到 LVGL 8.0.1 上在 QT 仿真环境里先跑通一个完整的拼音输入法工程中文输入才真正脱离了上位机依赖。这个工程要解决的不只是“能出字”而是字体、拼音码表、候选栏、键盘和 textarea 五样东西能在一个仿真工程里闭环。这套东西适合所有想给嵌入式界面加中文输入能力的人尤其是用 LVGL 开发工控屏、家电屏、带触摸的小面板又没条件在目标板上一遍遍烧录调试的开发者。在 PC 上把 QT 仿真里的输入法调顺再往真机上搬能省掉大量重复烧板时间。正文会按工程搭建、拼音内核、UI 联动、常见坑、真机验证的顺序展开所有命令和参数都可以直接抄。2. 把 LVGL 8.0.1 完整工程架到 QT 仿真里配置、字体与最小窗口2.1 为什么中文输入法必须先在 QT 仿真里验证LVGL 8.0.1 本身提供的是图形库 MVVM 那一层的控件能力字符如何进来、候选窗如何弹出它不帮你决定。我们常用做法是把它跑在某公司维护的 QT 仿真模板里鼠标当触摸PC 键盘当实体键盘。这样做的直接收益是调试周期从“编译烧录看屏”变成“编译看窗口”每次提交候选词、翻页逻辑几分钟就能看到结果。还有一个容易忽略的点中文字体的选择在真机上试错成本很高。一套包含常用汉字的字库文件动辄几百 KB放进单片机 Flash 后再发现渲染不对就得重新生成字体、重新烧录。QT 仿真里可以把字体、IME 逻辑、候选布局全部先验证完真机上只做一次移植。再加上 LVGL 8.0.1 的按键事件模型在 QT 和真机上是同一套 API仿真里调通的回调逻辑搬到真机基本不用改这是我最看重的一点。2.2 建立工程骨架目录与 lv_conf.h 关键开关所谓“完整工程”不是把 LVGL 源码复制进去就完事而是让仿真模板、IME 数据、UI 代码、字体文件分开放。常见目录结构是这样的lvgl8_ime_qt/ ├── lvgl/ # LVGL 8.0.x 源码保持官方原样 ├── lv_drivers/ # 显示器和输入设备驱动QT 仿真需要用到 ├── qt_sim/ # QWidget、QTimer 等仿真入口代码 ├── ime/ # 拼音表、候选索引、输入状态机 ├── ui/ # 键盘、候选栏、文本框界面 ├── assets/ # 生成的字体 C 文件、候选词数据 ├── lv_conf.h └── CMakeLists.txt把 lvgl 源码和业务代码分开是必要的否则升级 LVGL 小版本时散落在业务代码里的控件调用会很难维护。CMakeLists 里只需要把lvgl、lv_drivers、qt_sim、ime、ui这五个目录加进编译再让assets里的字体 C 文件被lv_conf.h声明为外部字体即可。lv_conf.h 里这几个参数和中文输入直接相关建议按下面的值开#define LV_COLOR_DEPTH 16 #define LV_TICK_CUSTOM 1 #define LV_USE_PERF_MONITOR 1 #define LV_FONT_MONTSERRAT_14 1 #define LV_FONT_CUSTOM_DECLARE extern lv_font_t cn_16; #define LV_USE_LABEL 1 #define LV_USE_TEXTAREA 1 #define LV_USE_KEYBOARD 1LV_COLOR_DEPTH 要跟目标屏一致。如果你最终真机是 16 位色屏仿真里也设 16否则颜色误差会一层层叠加模拟器上为图好看设成 32到了真机反而会出现色斑。LV_FONT_CUSTOM_DECLARE 是在声明我们后面生成的中文字体 cn_16这个名字要和字体工具输出保持严格一致。千万别漏了 LV_USE_KEYBOARD虽然这个工程最终用的是自绘键盘方案但 LVGL 8.0.1 的标准键盘控件在调试阶段能帮你快速验证 textarea 的回调逻辑。2.3 用字体工具生成“够用”的中文字库LVGL 8.0.1 官方字体默认只覆盖 ASCII中文全字库必须自己生成。常见做法是用 lv_font_conv 这个命令行工具它能把 TTF 或 TTC 字体转成 C 源码。下面是我常用的命令lv_font_conv --font msyh.ttc --size 16 --bpp 2 \ --range 0x20-0x7F \ --range 0x4E00-0x9FA5 --no-compress \ -o assets/cn_16.c这里--size 16是像素高度HMI 屏幕一般 16 20 适中--bpp 2表示字母抗锯齿用 2bit兼顾观感和内存。最重要是--range 0x4E00-0x9FA5这一整段是常用汉字区加上 ASCII 段后拼音输入法里能打出来的候选汉字基本都在里面。但这段范围覆盖了六千多个汉字全部生成出来的字库在真机上会占掉不少 Flash。取舍办法是先让字库完整可用等输入法跑通后再用自己维护的“常用字表”收窄范围。模拟器阶段不要一上来就裁否则候选词里出现没有字形的字你会分不清是字库问题还是拼音表问题。字体生成后在 C 文件里会暴露一个const lv_font_t cn_16符号把它加入 LV_FONT_CUSTOM_DECLARE再通过lv_style_set_text_font给控件设置即可。2.4 在 QWidget 里喂 LVGL 心跳并刷新QT 仿真的核心不是画几个按钮而是让 LVGL 的心跳跑起来。LVGL 8.0.1 的事件处理依赖lv_timer_handler()被周期性调用在 QT 里我习惯用一个 QTimer 驱动并把 paint 事件绑定到刷新上。#include QTimer #include QWidget #include lvgl/lvgl.h class SimWidget : public QWidget { public: SimWidget(QWidget *parent nullptr) : QWidget(parent) { QTimer *timer new QTimer(this); connect(timer, QTimer::timeout, this, [this]() { lv_timer_handler(); // LVGL 处理定时器、动画、输入事件 update(); // 触发 paintEvent 重绘 }); timer-start(5); // 每 5ms 喂一次相当于 200 帧上限 } };这段代码里的 5ms 是血泪经验总结出来的值。太快会让 PC 仿真占满 CPU太慢则动画和输入响应明显发涩。一般 PC 上 2 10ms 都能跑推荐先设 5ms真机再改由 RTOS 的任务周期调度。注意 LV_TICK_CUSTOM 打开后LVGL 会用一个专门的 tick 源仿真里不能只依赖 QTimer 而让lv_tick_get()一直返回 0否则定时器相关控件全部不工作。到这里QT 窗口能把 LVGL 桌面跑起来、中文字体也能显示接下来才是真正的输入法内核部分。3. 中文拼音输入法的内核拼音表、候选索引与输入态机3.1 本地拼音输入法的组成键盘码、拼音串、候选词不少人一听“输入法”三个字就想到复杂的字典树、动态规划对 LVGL 这种小型 GUI 来说完全没必要。一个能用的中文拼音输入法逻辑链路只有三段键盘产生键码 → 键码拼成拼音串 → 拼音串查表得到候选汉字。三段都不需要智能联想先做到“能按拼音打出汉字”就能满足 90% 的 HMI 场景。键盘码处理有个细节LVGL 8.0.1 中控件按键不是直接拿 ASCII 码而是由 lv_group 转发事件。所以不管是 PC 键盘还是屏幕上的软键盘最终到 textarea 的按键统一表现为键码。我们只需要关心 a-z、数字 0-9、退格、回车这几个把它们转成本工程的输入事件。拼音串就是一个最长 6 位的小字符串用户输入“zhong”期间每按一个字母就重新查一次候选字符串超过 6 位就拒绝接收这是拼音的基本规则。候选词则来自一张本地拼音表。表里每一行记录一个拼音和对应的汉字码点工程启动时把表加载进内存查询时二分查找。这种方案没有黑匣子数据完全可以自己维护出问题能直接看表排查非常适合嵌入式环境。3.2 把拼音表做成有序数组查找时问 bsearch 而不是字典树单机版拼音输入法最常见的错误是一上来就建字典树内存和代码量都上去了效果和有序数组二分差不了多少。常见的做法是把拼音表做成静态有序数组然后用 C 标准库的 bsearch 精确查找。先看结构定义typedef struct { const char *pinyin; // 全拼例如 zhong const uint16_t *cand; // 候选汉字码点数组 uint8_t cand_cnt; // 候选数量 } pinyin_entry; static const uint16_t zhong_cands[] {0x4E2D, 0x91CD, 0x59CB, 0x8877}; static const pinyin_entry dict[] { {ba, (uint16_t[]){0x628A, 0x5DF4}, 2}, {zhong, zhong_cands, 4}, // 后面继续按拼音字母序排 };bsearch 要求数组按 key 升序所以 dict 里的拼音必须严格按字母序排列。为了不手写排序可以用脚本把拼音表导入后统一 sort。手动排一旦中间插了一个错序项查询结果就开始玄学这是必须避免的。代码实现如下static int cmp_py(const void *a, const void *b) { const char *key *(const char **)a; const pinyin_entry *en (const pinyin_entry *)b; return strcmp(key, en-pinyin); } const pinyin_entry *ime_find(const char *py) { if (strlen(py) 0 || strlen(py) 6) { return NULL; } return bsearch(py, dict, sizeof(dict) / sizeof(dict[0]), sizeof(dict[0]), cmp_py); }cmp_py 里的 key 类型是const char **因为 bsearch 的第一个参数是元素地址。dict 里的 pinyin 是const char *strcmp 可以直接比较。这套逻辑在 PC 仿真和真机上结果完全一致因为没有任何平台相关的依赖。候选数量上限 64 就够HMI 输入法不需要像手机输入法那样动辄几十个候选超过 64 个会直接把界面撑爆。3.3 输入状态机与“拼音→候选”的提交规则有了查询函数还需要一个状态机把连续按键聚合成拼音串。状态机一共三个状态空闲、输入拼音、候选展开。它们之间的跳转决定了用户按空格、数字、退格时的行为直接上代码更清楚typedef enum { IME_IDLE, IME_PINYIN, IME_CAND_SELECT } ime_state_t; static ime_state_t ime_state IME_IDLE; static char ime_py[7]; // 当前拼音串最多 6 个字母 \0 static const pinyin_entry *ime_cur NULL; void ime_key_event(uint32_t key) { if (key a key z) { if (strlen(ime_py) 6) { snprintf(ime_py strlen(ime_py), 2, %c, key); ime_cur ime_find(ime_py); ime_state IME_PINYIN; ime_update_candidate(); // 刷新候选 UI } } else if (key LV_KEY_BACKSPACE) { if (strlen(ime_py) 0) { ime_py[strlen(ime_py) - 1] \0; ime_cur ime_find(ime_py); } else { ime_state IME_IDLE; } } else if (key ime_cur ! NULL) { ime_commit(ime_cur-cand[0]); // 空格默认选第一个候选 } else if (key 0 key 9) { int idx key - 0; if (ime_cur idx ime_cur-cand_cnt) { ime_commit(ime_cur-cand[idx]); } } }这个状态机值得注意的一点是没有做太复杂的“继续组词”。用户输入“zhong”候选出来“中 重 钟 衷”此时再按字母应该继续往拼音串里追加而不是贪心地去匹配“zhongguo”。很少量的汉字输入场景用全拼逐个选字更顺等候选窗出现后按数字键就提交。ime_commit 里需要调用lv_textarea_add_char或按码点追加文本注意 LVGL 8.0.1 的 textarea 输入是按 UTF-8 字节处理的提交前要把 UTF-8 码点转成字节序列再插入直接用整数赋值会乱码。3.4 候选窗口容量与翻页参数的取舍候选窗口的界面参数是个容易被忽略但很影响体验的地方。我把常用的参数和建议值整理成一张表方便直接套用参数建议值理由每页候选数79触摸屏上数字键一屏可容纳翻页次数少翻页按键上页/下页LVGL 没有自带拼音翻页组件用左右软键代替候选超时不自动清除HMI 场景操作节奏慢拼音串保留到退格或提交拼音串长度上限6汉语拼音最长 6 个字母超过直接拒绝输入默认选中第一个候选空格直接上屏常用字命中率高每页候选数不建议超过 9因为软键盘上的数字选择键通常只画 0-9超过以后用户得靠翻页才能选更多候选操作成本反而高。翻页键我习惯放在候选栏左右两侧做成两个小按钮左边上翻、右边下翻。候选栏高度固定不随候选数量跳动这样界面布局才稳定。拼音表本身的范围也需要控制。常见做法是把拼音表拆成py_common.c和py_ext.c两个文件常用拼音放前者生僻字放后者真机 Flash 不够时可只保留前者。这种拆法的问题在于又要对齐又要排序建议先用一个 Python 脚本统一生成两个 C 文件别手写否则拼音排序出错时很难肉眼找到。4. 把 IME 和界面绑在一起键盘、候选栏与 textarea 的联动4.1 借用 LVGL 键盘还是自绘键盘LVGL 8.0.1 自带lv_keyboard控件开箱就能绑定 textarea但它的按键布局是英文的拼音字母没问题候选选择键却不顺手。实际工程里我见过两条路一是直接扩展lv_keyboard的键位映射二是在自绘按键矩阵里复用lv_btnmatrix的样式。两者对比看这个表方案优点缺点扩展 LVGL 自带键盘事件回调已被框架处理字符输入简单键位和候选按钮布局难定制样式和真机不一致自绘 btnmatrix 键盘键位任意排布能加“清空、翻页”按钮需要自己把一次按键翻译成拼音键码我一般选择自绘键盘。原因很简单HMI 的键盘布局常常要设计成“上排拼音、下排数字、右侧候选”自带键盘做不到这种布局。自绘核心是用lv_btnmatrix_create建一个按钮矩阵它的回调 CVent 里拿到的只是按键下标还需要把下标映射成业务键码。代码里放一组静态表做映射即可键盘 UI 和输入逻辑只通过键码交互互不依赖。4.2 按键回调里把键码改造成拼音串键盘按钮按下后最终要触发 textarea 的事件回调。在 LVGL 8.0.1 里给 textarea 绑定lv_obj_add_event_cb并监听LV_EVENT_KEY就能拿到统一键码。这里有一个很容易踩的坑键盘回调把键码发给了按钮所在的 group而不是直接发给 textarea。所以必须让 textarea 和键盘在同一 group 中并且确保 textarea 获得了焦点。static void ta_event_cb(lv_event_t *e) { if (lv_event_get_code(e) LV_EVENT_KEY) { uint32_t key lv_event_get_key(e); ime_key_event(key); // 交给状态机处理 lv_event_stop_bubbling(e); // 避免键盘默认行为再插入一遍字符 } } void ui_bind_keyboard(lv_obj_t *ta) { lv_obj_add_event_cb(ta, ta_event_cb, LV_EVENT_KEY, NULL); }逻辑上所有字母、数字、退格都会先到 ta_event_cb这里统一交给第三章的 ime_key_event。lv_event_stop_bubbling 这行很重要如果不加某些键盘场景下默认事件会把字母再送到 textarea于是出现“拼音串已处理一遍文本框又被塞进一个字母”的翻车现场。按键码统一以 LVGL 键码为准和 PC 键盘的 ASCII 未必一致所以 ime_key_event 里判断 a-z 时最好先做一次key tolower(key)。4.3 选字、退格、清空与光标的行为细节候选栏选字动作发生在焦点离开键盘、转到候选按钮时。按数字键选字提交问提交之后拼音串要不要清空常见做法是提交后清空拼音串并关闭候选栏这样连续输入两个汉字时状态是干净的。退格则分两层拼音串不为空时先删拼音拼音串为空时再调用lv_textarea_del_char删文本框里的汉字这个优先级一定要固定。void ime_commit(uint16_t codepoint) { char utf8[4]; size_t len unicode_to_utf8(codepoint, utf8); utf8[len] \0; lv_textarea_insert_text(active_ta, utf8); // 在光标处插入 ime_py[0] \0; ime_cur NULL; ime_state IME_IDLE; ime_update_candidate(); }这段说明了一个容易忽略的点lv_textarea_add_char只能插入单个 UTF-8 字符而lv_textarea_insert_text可以插入字符串。中文汉字经 UTF-8 编码后是 3 字节用 add_char 也可以但 insert_text 更通用。unicode_to_utf8 这个函数建议自己实现因为 LVGL 8.0.1 内部有 UTF-8 处理函数但不一定暴露成公共 API我这里手写 3 行移位就行避免依赖某些平台上没有的库函数。光标位置在输入汉字后应自动移动到新文本后面。lv_textarea 默认插入点是光标位置所以只有用户用上下左右键移动过光标时才需要手动处理。HMI 输入场景我建议禁止移动光标把LV_OBJ_FLAG_SCROLLABLE关掉减少光标带来的逻辑分支。5. 避坑QT 仿真中文输入工程最常见的 5 个翻车点5.1 候选显示成“豆腐块”的字体覆盖坑现象候选栏能弹出来但每个汉字显示成一个小方框或问号英文正常。原因字体文件里没有覆盖候选汉字的码点范围。很多人在 lv_font_conv 时只把 ASCII 范围写进去忘记加0x4E00-0x9FA5LVGL 找不到字形就画豆腐块。解决先用一个独立测试页把“中文字体显示测试”这几个字用 cn_16 字体渲染文本内容硬编码成 UTF-8 字符串。如果测试页能显示再排查候选框是不是设置了别的字体如果测试页也显示方块说明字体文件范围不够回到 2.3 节的命令重新生成。注意 QT 仿真里的中文直写源码时文件编码必须是 UTF-8不然源码里的字符串本身就是乱码字体再大也没用。5.2 窗口坐标偏移导致按键落到错误控件现象在 QT 仿真窗口里点击软键盘“q”实际按到的是“a”或者根本没触发鼠标位置越靠近边缘越不准。原因QT 窗口在高分屏下开启了 devicePixelRatio 缩放LVGL 拿到的触摸坐标是逻辑坐标而窗口回调给的是物理像素坐标两者没有换算。仿真里因为窗口缩放坐标偏移会放大得特别明显真机上倒是少见但一旦发生在真机基本是触摸驱动坐标和分辨率没对齐。解决在 QT 仿真入口处把 QMouseEvent 里的坐标先除devicePixelRatio()再传给 LVGL 的指示设备驱动。真机上则用lv_indev_drv里统一输入像素坐标并保证hor_res、ver_res与驱动上报范围一致。这个坑最容易伪装成“按键不灵”实际是坐标被整体平移了。5.3 源码字符编码混用进 textarea 变成乱码现象拼音串和候选都对但提交后的汉字在文本框中显示成“锟斤拷”或一串问号。更诡异的是仿真里第一次提交正常第二次就乱了。原因工程源文件在 Windows 上被存成 GBK部分文件被 IDE 自动存成 UTF-8LVGL 8.0.1 的渲染链路要求字符串是 UTF-8一旦混入 GBK 字节流UTF-8 解码就断裂。解决整个工程强制 UTF-8CMakeLists 里给编译器加 UTF-8 选项QT 源文件在编辑器里统一设为 UTF-8 无 BOM。拼音候选表里的汉字以码点数组形式保存不用字符串直写这是最保险的办法。IME 代码里所有中文字符串用一个头文件集中管理避免散落各处后编码风格不统一。5.4 全部字库一次性编进去Flash 和内存双双告急现象仿真没问题编译完发现固件体积超了或者启动时 LVGL 分配内存失败屏幕刷新明显卡顿。原因6000 汉字范围生成的 cn_16.c在 bpp2 时也有几百 KB 的字体数据放进内部 Flash 会直接挤占业务代码空间运行时字体数据还要通过 LVGL 字体缓存加载内存占用也不小。解决先用“常用字 拼音表实际覆盖字”交集生成一个精简字库。做法是导出拼音表里所有候选码点再去重最后把这个码点列表传进 lv_font_conv 的--range。这样生成的字库通常只有几百个汉字体积大幅下降。真机上如果还是有压力再把 bpp 降到 1牺牲一点抗锯齿换取一半体积。字体缓存大小通过LV_MEM_SIZE控制建议根据字库文件的字形总量估算留出 20% 余量。5.5 仿真 5ms 心跳换成真机定时器后输入丢字现象QT 仿真里键入“zhong”候选刷新流畅移植到真机后快速输入会丢中间字母按快了甚至只出来“zg”。原因真机上 lv_timer_handler 的调用周期不稳定或者它在低优先级任务里被拖住。LVGL 的按键事件是顺序处理的如果两次按键间隔小于一个 timer 周期事件队列会合并或丢弃表现就是丢字。解决真机必须给 LVGL 一个独立的心跳源lv_tick_get由硬件定时器提供而lv_timer_handler放在按键事件之后、渲染之前的高优先级位置。输入部分还可以加一个 16 字节的按键 FIFO键盘回调只压队列状态机从队列取键这样输入不会因 timer 周期抖动而丢。这个 FIFO 在仿真里看不出差异但真机按键抖动环境下差距非常明显。6. 上真机前先量化这三项内存热点、输入时序、帧率6.1 用 lv_mem_monitor 找出占内存的真凶中文输入工程在仿真里看不出资源问题必须量化。LVGL 8.0.1 自带内存监控接口把它接到一个调试按钮上候选栏每切换一页打一次数据。lv_mem_monitor_t mon; lv_mem_monitor(mon); LV_LOG_USER(size total%d free%d used%d, (int)mon.total_size, (int)mon.free_size, (int)mon.total_size - (int)mon.free_size);建议在三种状态下各打一次刚启动、候选栏打开、连续输入 50 个汉字后。如果第三态内存比第一态涨了明显的一块多半是候选窗口对象没有正确释放或者 textarea 的文本长度无上限。真机内存紧张时优先把候选栏做成复用对象而不是每次都 create 新对象这个优化动作仿真里几乎看不出来但能立省几 KB。6.2 同一份输入脚本在 QT 与真机上回放对比输入时序是中文输入法最容易被环境差异放大的部分。我习惯把按键序列写成一组宏例如z h o n g SPACE l i SPACE在 QT 仿真和真机上分别串行执行然后对比 textarea 里最终结果是否一致。只要两次结果相同输入链路就是可靠的。static const char *input_script[] { z, h, o, n, g, , l, i, , b, e, i, , j, i, n, g, , };脚本回放时每两个按键之间加固定的 20ms 延迟模拟真实触摸的间隔。真机上把这个脚本放进一个 page 自动执行再截图比对文本框内容。这一步能把状态机里隐藏的边界问题暴露出来比如“bei jing”连输时拼音串是否被正确截断、空格选字后状态是否复位。我现在每次改完 IME都会先在仿真里把这三组脚本跑通再合代码真机拿到手只是验证很少再折腾输入逻辑。这个习惯帮我省掉了不少来回烧板的麻烦也希望帮到你。本文还有配套的精品资源点击获取