TouchGFX自定义屏幕键盘：从重复代码到可复用组件实践

做嵌入式的都懂凡是要让用户填点东西的界面迟早得面对屏幕键盘。我之前做一台带网口配置的仪表客户要求能在触摸屏上输入IP、掩码、网关和SSID。第一版图省事直接在配置界面里拖了整整一排按钮用的时候还挺顺利。等第二个界面需要输入上传服务器地址时我把那排按钮复制粘贴了一份改改回调也能用。但到第三个界面要输入用户名密码时我开始觉得不对劲键盘逻辑、大小写切换、退格、长按重复这些代码散落在三个View里想统一改一次键位得开三个文件来回翻。后来痛定思痛用TouchGFX的Custom Container把键盘做成了一个独立组件一个文件改逻辑所有界面跟着升级。这篇就分享整个设计过程包括UI骨架怎么搭、对外接口怎么定、按键逻辑怎么封装以及工程里那些不踩不知道的坑。1. 为什么固定键盘控件救不了自己的项目1.1 内置Keyboard的边界TouchGFX 自带的 Keyboard 控件其实不算差开箱就能弹出一个标准键盘也能直接对接 TextArea很多 Demo 工程里都这么用。但它最大的问题是“够用但不好改”。内置键盘的布局、按键数量、字符集、特殊键行为都绑在一套相对固定的配置里。你想把 Shift 键改成切换数字页想把回车键放在右侧竖排想加一个清除全部文本的按键都会发现要绕不少弯。更深一层的限制是内置键盘把“按键渲染”和“文本输入逻辑”耦合在了一起你在工程里很难把它当成一个独立可替换的组件。我做那块仪表时输入IP地址的界面需要纯数字键盘输入SSID的界面需要带字母和符号的完整键盘稍一深入就发现内置 Keyboard 的方案有点拧巴。与其花时间反向适配它的模式不如直接用 Custom Container 做自己的键盘把每一个按键、每一段逻辑都握在自己手里。1.2 自定义容器在TouchGFX中的定位Custom Container 在TouchGFX里是一个很“实在”的机制。它的本质就是一个touchgfx::Container子类你可以像搭积木一样把多个 Button、TextArea、Box 放进去Designer 会自动生成对应的 Base 类和初始化代码。这个容器一旦建好内部所有控件和逻辑都被封装起来外面只看到一个整体——可以放进任意 Screen可以设置坐标、缩放、透明度也可以整体显示/隐藏。这不是结构上的巧合而是TouchGFX刻意支持的复用方式。Container 本身参与事件分发、重绘和动画系统你在里面放多少个按钮对外不增加任何负担。真正让它“可变复用”的关键是把对外接口设计清楚键盘需要告诉外部“我按了哪个键”但不需要知道外部是更新 TextArea、存到变量还是做别的动作。这个边界必须从第一天就画清楚否则做出来的“容器”还是换了个名字的重复代码。2. 搭骨架在TouchGFX Designer里画出可复用键盘2.1 新建Custom Container与UI分层打开TouchGFX Designer在左侧组件列表里找到 Custom Container拖到画布上。先别着急放按键第一步把尺寸和分层想好。以一块800x480的屏为例键盘通常放在屏幕下半部分我习惯把容器宽度设成800高度设成240底部和屏幕对齐。这样键盘弹出来时不至于挡住上半部分的输入框和说明文字。容器内部的分层建议是这样的底层放一个 Box 做键盘面板背景颜色最好和主界面有明显区分否则按键边界看不清背景之上放一行特殊键位区退格、Shift、符号切换、回车再往下是字母和数字按键区。用 Box 而不是图片做背景可以省掉一份图片资源和解码时间视觉上也干净。新建容器后Designer会自动生成两个类CustomKeyboardBase和CustomKeyboard。Base类里是所有的控件初始化和布局代码非必要别去改否则Designer下次重新生成会直接覆盖你的改动。自己的业务逻辑全部写在上层类里。这是整个复用体系的第一个原则生成代码和手写代码隔离。2.2 按键布局与统一事件入口按键布局我推荐用标准的 QWERTY 变体但要根据产品实际输入场景裁剪。比如我做的那台仪表用户只需要输入IP、SSID、密码和服务器地址所以留了26个英文字母、0-9数字、退格、Shift、回车和一个“清空”键就够用。没有必要放F1到F12也没有必要放主键盘区右侧那一堆编辑键。布局坐标可以用表格规划以800x240的容器为例我用了下面这组参数行内容按键宽度按键高度与上一行间距1数字0-9退格7040顶边距82字母QWERTYUIOP624083字母ASDFGHJKL回车624084Shift字母ZXCVBNM清空62408按键一律用 ButtonWithLabel或者用 Button 叠加 TextArea。我比较推荐 ButtonWithLabel因为Designer直接支持按键的按下/松开图片或填充色文本也自带居中省掉不少对齐的功夫。给每个按键取一个有意义的名字比如keyA、keyShift、keyBackspace生成代码里就会对应同名变量后面写逻辑时一眼能认出是哪个键。事件绑定用统一入口在 Base 类里所有按键的setAction都会指到同一个buttonCallback回调最终进入buttonClickedHandler(const AbstractButton src)。不要每个键单独挂一个回调那样处理函数会膨胀到没法维护。统一回调后所有按键命中都走同一段代码你只需要在回调里判断src指向的是哪个按钮就行。2.3 大小写/符号页的控件布局策略键盘做成自定义容器一个绕不开的问题是大小写、符号、数字页怎么呈现。最简单的方案是每个页面做一套独立的容器根据状态切换可见性。但这样会浪费RAM而且页面之间切换时有明显的瞬间跳变。更实用的做法是只画一份按键切换页面时改的是按键上显示的文字和按下后发送的字符。这样容器内部控件数量固定状态切换只是改ButtonWithLabel的文本和映射表索引动画也平滑。对于产品里固定使用的键盘这种“单套控件状态切换”的方案长期来看最好维护。但有一点要注意符号页的键位不一定和字母页一一对应比如我放了一个“清空”键在字母页和符号页都需要它但在数字页可能想换成小数点。处理方式是在状态切换函数里根据目标页面改变某些键的文本和映射。这个逻辑集中在switchPage(KeyboardPage page)函数里不要散落在各个按键回调里。3. 定契约键盘容器与外部世界的通信方式3.1 只发事件不碰业务键盘容器做出来之后第一件要定的事就是它怎么把“用户按了什么”告诉外部。我强烈建议用事件回调而不是让容器直接持有目标 TextArea 的指针去改文本。理由很简单如果容器只发事件它就是一个纯输入组件可以非常轻易地被替换、扩展和测试如果容器直接操作某个具体 TextArea那么它就和那个界面绑死了。我在代码里定义了一个精简的事件结构struct KeyEvent { enum Type { CHAR, // 普通字符 BACKSPACE, // 退格 ENTER, // 回车/确认 CLEAR, // 清空当前输入 SWITCH_PAGE // 切换键盘页面仅内部使用 }; Type type; uint16_t ch; // 当typeCHAR时有效 KeyEvent() : type(CHAR), ch(0) {} KeyEvent(Type t, uint16_t c 0) : type(t), ch(c) {} };容器内部持有一个touchgfx::GenericCallbackKeyEvent* listener每次按键命中就执行listener-execute(event)。宿主View在初始化时把自己的处理函数传进来keyboard.setListener(touchgfx::GenericCallbackKeyEvent cb);这样键盘容器完全不知道外部是更新一个 TextArea还是把字符追加到某个数组里。它只知道“我发出了什么事件”。这就是复用的核心容器的职责边界清晰外部接口稳定内部怎么改都不影响调用方。3.2 直接写TextArea的简化方案当然不是所有项目都值得做这么干净的事件层。如果你的产品只有一个输入界面或者只想快速验证效果那让容器直接持有 TextArea 指针也完全可以。做法是在容器里加一个setTargetTextArea(TextArea ta)接口按字符时直接操作ta.setWildcard(buffer)退格时自己维护buffer的长度。这个方案的坏处是一旦界面里有多个输入框你要反复切换容器持有的目标指针稍不留神就会指错。而且验证逻辑、输入长度限制、字符过滤都堆在容器里时间一长容器会变得很臃肿。我个人的经验是如果超过两个界面需要键盘就老老实实走事件回调。前期的接口设计成本会在后面的每一个新增输入界面里连本带利还回来。3.3 特殊键语义与事件编码事件编码也要提前约定。字母和数字可以直接用对应的Unicode码但退格、回车、清空这些控制键不能被误当成字符。所以上面用了KeyEvent::Type来区分。宿主View收到事件后只需要关心几种情况CHAR把event.ch追加到输入缓冲BACKSPACE从缓冲尾部删除一个字符ENTER执行“确认输入”逻辑比如跳转界面或保存配置CLEAR清空缓冲并把显示区域刷新为空白在这个协议里Shift 键和符号切换键其实不需要对外发事件。它们属于键盘自身的状态管理用户按一下 Shift容器内部把页面从“小写”切到“大写”然后更新按键上的标签后续按字母键时发出大写字符。外部完全感知不到这个过程。把内部状态和外部事件分开界面层才能保持简单。4. 填逻辑按键映射、状态机和文本输入链路4.1 从按钮指针到KeyEvent的映射Designer 生成的 Base 类里每个按键都是一个成员变量。在派生类里我把它们整理成一个查找表避免在buttonClickedHandler里写几十行 if-else。touchgfx::Button* keyWidgets[KEY_COUNT] { keyA, keyB, /* ... */ }; const uint16_t keyLower[KEY_COUNT] { a, b, /* ... */ }; const uint16_t keyUpper[KEY_COUNT] { A, B, /* ... */ }; const uint16_t keySymbol[KEY_COUNT] { 1, 2, /* ... 根据布局自己定义 */ };buttonClickedHandler收到按键指针后先查这个序号再根据当前页面选择对应的字符数组for (uint8_t i 0; i KEY_COUNT; i) { if (src keyWidgets[i]) { uint16_t ch; switch (page) { case KB_UPPER: ch keyUpper[i]; break; case KB_SYMBOL: ch keySymbol[i]; break; default: ch keyLower[i]; break; } sendEvent(KeyEvent(KeyEvent::CHAR, ch)); return; } }控制键单独判断比如keyShift、keyBackspace、keyEnter。把普通字符键和控制键分开处理逻辑清晰以后新增一个按键也不需要动回调结构只要往表里加一行。4.2 大小写切换与页面切换的状态机页面切换用一个简单的状态枚举就够了enum KeyboardPage { KB_LOWER, KB_UPPER, KB_SYMBOL };Shift 键按下的行为要提前定义好。我建议按一次 Shift 只让下一个字母大写再按一次恢复小写双击 Shift 则锁定大写。这个交互习惯和手机键盘一致用户基本不需要学习成本。实现上Shift 按下时先判断当前是不是大写如果是大写则回到小写否则切到大写并启动一个“一次性大写”标记。切换页面后需要调用一个刷新按键文本的函数比如updateKeyLabels()。它会遍历按键数组根据当前页面把ButtonWithLabel的文本改成对应的字符。注意不要只改发送字符不改显示文本否则用户会看到键帽上写的是 a按下去却输出了 A这种体验非常扣分。符号页的切换键不只是 Shift还要有一个专门的“符号/数字”切换键。它可以和 Shift 分开也可以复用 Shift 的键位。我更喜欢单独放一个#键因为符号页里通常还有数字它和字母大小写是完全独立的两个维度。4.3 TextArea字符缓冲的维护与刷新键盘发出事件后真正的文本输入逻辑在 View 里完成。TouchGFX 的 TextArea 要显示动态文本通常走 wildcard 机制也就是TextArea通过setWildcard(Unicode::UnicodeChar* buf)指向一个缓冲区显示内容就是缓冲区的字符串。我在 View 里用一个固定长度数组做输入缓冲static const uint8_t BUF_LEN 32; Unicode::UnicodeChar inputBuf[BUF_LEN]; uint8_t inputLen 0;收到 CHAR 事件时先检查inputLen BUF_LEN - 1防止越界。然后把event.ch放进inputBuf[inputLen]在inputBuf[inputLen]补\0最后调用textArea.setWildcard(inputBuf)和textArea.invalidate()。这里一定要先补结束符再刷新否则 TextArea 会继续读旧缓冲里的残留内容。收到 BACKSPACE 时if (inputLen 0) inputLen--;同样清结束符并刷新。收到 CLEAR 时把inputLen归零并清空第一个字符。这段逻辑虽然简单但很容易在边界条件上出问题尤其是“缓冲区已经满了还要输入”和“空缓冲还要退格”这两种情况必须写清楚退出条件。5. 实战排坑刷新、字体、触摸和内存5.1 别让一次按键触发整屏重绘TouchGFX 的重绘是按区域来的理论上每次按键只需要刷新被修改的那个 TextArea 附近区域。但如果回调里误调用了screen.invalidate()或者container.invalidate()整块键盘都会被重新绘制在低主频的 STM32 上能明显感觉到卡顿。实测下来一次完整的键盘重绘在 STM32F429 上可能吃掉十几毫秒如果用户快速连续点按UI 线程就扛不住了。正确做法是只失效真正变化的部分改的是 TextArea 的显示就调用textArea.invalidate()改的是 ButtonWithLabel 的文本就调用按钮的invalidate()。只有当整个键盘从隐藏切到显示或者显示切到隐藏时才需要刷新整个容器区域。如果你的界面用了双缓冲或多缓冲还要留意帧缓冲切换时的带宽。TouchGFX 会对比前后帧的差异来决定无效区域只要你刷新的区域足够小这个机制基本不会成为瓶颈。真正拖慢速度的往往是按键背景图太大、每张图都是全屏尺寸这种习惯要趁早改掉。5.2 字体裁剪与多语言输入的现实方案屏幕上键盘不是字词库它每个键只显示一个字符理论上字体资源不需要太大。但如果你的工程要支持中文输入或者符号页放了很多生僻符号情况就复杂了。TouchGFX 的字体生成工具是按文本资源自动裁剪的键盘上显示的字符必须在字体文件里存在否则键帽上会显示成方框。我碰到的实际问题是默认字体只包含ASCII符号页里的±°μ这些单位符号全部缺失。排查了半天才发现是字体没有把这些字符包含进来后来在字体生成配置里把常用符号手动加进字符集才解决。所以做键盘前先把你需要输入的字符范围列成清单一次性配置到字体的Unicode块里避免做到一半再回头补字体。对于中文这种大字符集的输入我建议在产品里换一种策略不在设备上做全拼输入而是提供常见短语和数字键盘或者让用户通过上位机配置。STM32 的资源放不下完整的汉字输入法和庞大的字库勉强做出来体验也不会好。这是很多项目倒在流程末端的坑提前和产品经理谈清楚。5.3 触摸热区与模态遮挡屏幕键盘的按键通常比普通按钮更密集在7寸以下的小屏上尤其明显。按键热区如果小于40x40像素用户就很容易点偏。官方推荐的最小触摸区域至少是40x40我自己的底线是不要低于36x36。按键之间的间隙不要紧挨着留2到4像素否则误触概率很高。另一类问题是模态遮挡。如果你在键盘上方加了一层半透明 Box 做遮罩这个 Box 默认是 touchable 的它会吃掉所有触摸事件导致下面的按键全部失灵。解决方法是把遮罩 Box 的touchable属性关掉只保留绘制功能或者把 Box 放到容器后面确保按键始终在所有遮罩控件之上。5.4 多屏幕实例化的内存开销Custom Container 复制到多个 Screen 使用时每个 Screen 的 View 里都会实例化一份完整的按钮对象。一次键盘实例大约增加几十KB RAM具体取决于按键数量和文本缓冲。如果项目里有四五个 Screen 都要输入文本一份键盘放五个地方RAM 就很吃紧了。更合理的做法是把键盘放在一个专门的 Screen 上输入界面通过ScreenTransition跳转过去或者把键盘容器放在一个全局可见的顶层容器里其他界面只是切换它的显示内容。这样 RAM 只花一份而且键盘状态比如当前在大写页也能保留。缺点是多了一次界面切换的动画成本但对于大多数配置类交互场景这种切换反而是符合用户预期的。如果你确实必须在多个 Screen 里各放一个键盘实例建议把键盘内部的大缓冲区统一放到共享内存或者静态区别让每个实例都分配一份。这个优化在总量上很可观。6. 经验小结与下一步扩展这套自定义键盘方案做下来我最大的体会是组件复用能不能成功不在于控件本身被拖了多少个地方而在于外部接口是否稳定、内部状态是否自治。按键布局、页面切换、字符发送都收在容器内部界面只处理“收到事件后更新哪个输入框”改造和增删都变得很轻。最后分享一个我自己实践出来的小技巧键盘容器设置一个“初始页面参数”接口比如setInitialPage(KB_UPPER)这样在密码输入界面可以直接以小写字母页出现但不消耗额外状态代码。另一个可以扩展的方向是把按键音反馈、按键长按重复也做进容器内部这样连界面层都不用感知。这个思路不止适用于键盘任何需要反复出现在多个界面里的复杂控件——比如日期选择器、下拉列表、数字拨盘——都可以用同样的“容器回调状态机”套路去实现。TouchGFX 的 Custom Container 本质就是专门为这种需求准备的把它用好很多界面逻辑会变得清爽很多。