ESP32玩转1.3寸ST7789小屏：手把手教你用TFT_eSPI库显示中文（附字库制作）-平芜编程栈

ESP32驱动ST7789屏幕实现中文显示的完整实战指南

在物联网设备的人机交互界面开发中，中文显示一直是个令人头疼的问题。上周我为一个智能温控器项目添加中文界面时，发现市面上大多数教程都停留在基础API调用层面，真正解决中文字库制作和集成的完整方案少之又少。本文将分享一套经过实战验证的解决方案，从字体处理到最终显示，带你彻底攻克ESP32+ST7789屏幕的中文显示难题。

1. 硬件准备与环境搭建

1.1 硬件组件清单

要完成这个项目，你需要准备以下硬件：

ESP32开发板（推荐使用ESP32-WROOM-32D）
1.3寸ST7789驱动IPS屏幕（240x240分辨率）
杜邦线若干（建议使用优质镀金线材）
USB数据线（用于供电和程序烧录）

硬件连接时最容易出错的是SPI引脚配置。根据我的实测经验，以下连接方式稳定性最佳：

屏幕引脚	ESP32引脚	备注
GND	GND	必须共地
VCC	3.3V	切勿接5V
SCL	GPIO18	SPI时钟线
SDA	GPIO23	SPI数据线(MOSI)
RES	GPIO17	复位引脚，低电平有效
DC	GPIO16	数据/命令选择
BLK	GPIO4	背光控制

注意：不同厂商的屏幕引脚定义可能略有差异，务必先查阅你的屏幕规格书。我曾遇到过一家厂商的DC和RES引脚定义完全相反的情况，导致调试了半天才发现问题。

1.2 软件环境配置

开发环境建议使用PlatformIO + VSCode组合，相比Arduino IDE更适合工程化开发。以下是关键配置步骤：

创建新项目时选择"ESP32 Dev Module"作为开发板
在platformio.ini中添加依赖库：

lib_deps = bodmer/TFT_eSPI@^2.4.79 bodmer/SPI@^1.0

关键库文件配置：

修改lib/TFT_eSPI/User_Setup.h中的以下参数：

#define ST7789_DRIVER #define TFT_WIDTH 240 #define TFT_HEIGHT 240 #define TFT_MOSI 23 #define TFT_SCLK 18 #define TFT_CS -1 // 未使用片选 #define TFT_DC 16 #define TFT_RST 17 #define LOAD_GLCD // 加载标准字体

2. 中文字库制作全流程

2.1 字体文件处理

制作字库的第一步是选择合适的字体文件。考虑到嵌入式设备的存储限制，我推荐使用以下两种开源字体：

文泉驿微米黑：完整覆盖GB2312标准，文件大小约4MB
阿里巴巴普惠体：商业授权免费，字形美观

字体处理流程：

# 安装字体工具链（Ubuntu示例） sudo apt install fontforge python3-fontforge # 提取子集字体（仅包含需要的字符） pyftsubset yahei.ttf --text-file=chars.txt --output-file=yahei_subset.ttf

其中chars.txt应包含所有需要显示的字符，例如：

你好，世界！0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz

2.2 使用Processing生成字模

TFT_eSPI库自带的Processing工具是生成字模的关键：

下载并安装Processing 3.5.4（新版可能有兼容性问题）
打开TFT_eSPI/Tools/Create_Smooth_Font/Create_font项目
修改关键参数：

static final int fontHeight = 24; // 字号 static final int[] unicodeBlocks = { 0x4E00, 0x9FA5, // 常用汉字范围 0x0030, 0x0039, // 数字0-9 0x0041, 0x005A, // 大写字母A-Z 0x0061, 0x007A // 小写字母a-z };

运行脚本后会生成.vlw格式字模文件，通常位于项目的FontFiles目录下

2.3 字模文件优化技巧

原始生成的.vlw文件可能过大，我们可以通过以下方法优化：

字符范围精确控制：只包含项目实际需要的字符
多字号合并：将不同字号的字模合并到一个文件中
压缩存储：使用PROGMEM关键字将字模存入Flash而非RAM

优化后的字模头文件示例：

// font_yahei24.h #pragma once #include <pgmspace.h> const uint8_t yahei24_ranges[] PROGMEM = { 0x4E,0x00,0x9F,0xA5, // 汉字 0x00,0x30,0x00,0x39, // 数字 // 其他字符范围... }; const uint8_t yahei24_bitmaps[] PROGMEM = { // 压缩后的字模数据... };

3. 中文显示实现与优化

3.1 基础显示实现

完成字库制作后，在代码中加载和使用就相对简单了：

#include "font_yahei24.h" TFT_eSPI tft; void setup() { tft.init(); tft.setRotation(3); // 根据屏幕实际方向调整 // 加载自定义字体 if(tft.loadFont(yahei24_bitmaps, yahei24_ranges)) { Serial.println("字体加载成功"); } else { Serial.println("字体加载失败"); } // 显示中文 tft.fillScreen(TFT_WHITE); tft.setTextColor(TFT_BLACK); tft.drawString("温度:25.6℃", 10, 10); tft.drawString("湿度:62%RH", 10, 40); // 释放字体资源 tft.unloadFont(); }

3.2 显示性能优化

在实际项目中，我发现直接使用drawString()方法在刷新复杂界面时会出现明显卡顿。通过以下优化手段可以显著提升显示流畅度：

使用双缓冲技术：

TFT_eSprite sprite = TFT_eSprite(&tft); sprite.createSprite(240, 240); sprite.loadFont(yahei24_bitmaps); sprite.fillSprite(TFT_WHITE); sprite.drawString("正在更新...", 50, 100); sprite.pushSprite(0, 0); sprite.deleteSprite();

部分刷新策略：

// 只刷新变化部分而非整个屏幕 tft.setPartialWindow(10, 10, 100, 30); // 设置刷新区域 tft.drawString(newValue, 10, 10); tft.resetViewport(); // 恢复全屏刷新

字体预加载机制：

// 在setup中预加载常用字体 void setup() { tft.init(); tft.loadFont(smallFont); // 小字号字体 tft.loadFont(largeFont); // 大字号字体 } // 使用时快速切换 void showTemp(float temp) { tft.setFreeFont(largeFont); tft.drawString(String(temp), x, y); }

4. 实战案例：智能家居控制面板

下面通过一个完整的智能家居控制面板案例，展示中文显示的实际应用：

4.1 界面布局设计

// 定义界面元素位置 #define TITLE_X 20 #define TITLE_Y 10 #define TEMP_X 30 #define TEMP_Y 60 #define HUMI_X 130 #define HUMI_Y 60 #define BTN_X 70 #define BTN_Y 150 void drawUI() { tft.fillScreen(TFT_BLACK); // 标题 tft.setFreeFont(&yahei24pt); tft.setTextColor(TFT_CYAN); tft.drawString("智能家居控制", TITLE_X, TITLE_Y); // 温湿度显示 tft.setFreeFont(&yahei16pt); tft.drawString("温度", TEMP_X, TEMP_Y-30); tft.drawString("湿度", HUMI_X, HUMI_Y-30); // 按钮 tft.fillRoundRect(BTN_X, BTN_Y, 100, 40, 5, TFT_BLUE); tft.setTextColor(TFT_WHITE); tft.drawString("设置", BTN_X+30, BTN_Y+10); }

4.2 动态数据更新

对于频繁变化的数据，应该优化刷新逻辑：

void updateTemperature(float temp) { static float lastTemp = -100; if(abs(temp - lastTemp) >= 0.5) { // 只有温度变化≥0.5℃才刷新 tft.setFreeFont(&yahei16pt); tft.setTextColor(TFT_WHITE, TFT_BLACK); // 设置背景色避免残影 char buffer[10]; sprintf(buffer, "%.1f℃", temp); tft.drawString(buffer, TEMP_X, TEMP_Y); lastTemp = temp; } }

4.3 多语言支持方案

如果需要支持中英文切换，可以采用以下架构：

// 语言资源文件 const char* zh_CN[] = { "温度", "湿度", "设置" // 中文 }; const char* en_US[] = { "Temp", "Humi", "Setup" // 英文 }; // 根据设置加载不同语言 void drawStringByLang(int x, int y, int strId) { if(language == ZH_CN) { tft.drawString(zh_CN[strId], x, y); } else { tft.drawString(en_US[strId], x, y); } }

在项目开发过程中，我发现ST7789屏幕在低温环境下可能出现显示异常，这时需要调整SPI时钟频率：

// 在setup()中添加 SPI.begin(18, 23, -1, -1); // SCLK,MOSI,MISO,CS SPI.setFrequency(20000000); // 冬季可降至15MHz

另一个实用技巧是使用LVGL图形库配合TFT_eSPI，可以获得更丰富的UI效果。虽然会增加一些资源占用，但对于复杂界面来说非常值得：

// LVGL初始化示例 void lvgl_init() { lv_init(); lv_disp_drv_t disp_drv; lv_disp_drv_init(&disp_drv); disp_drv.hor_res = 240; disp_drv.ver_res = 240; disp_drv.flush_cb = my_flush_cb; // 使用TFT_eSPI的绘制函数 lv_disp_drv_register(&disp_drv); }