1. 项目全貌解析：SquareLine_Studio到底解决了什么问题
先说结论：如果你还在手工硬怼SPI TFT屏幕的坐标、像素缓冲和控件重绘代码，那SquareLine_Studio就是来解放你的。它不是替代你写底层驱动，而是把UI逻辑层和视觉层从单片机工程里整个抽离出去，让你在一个所见即所得的图形环境里把界面拖出来，生成纯C代码，然后丢进你的STM32或者其他MCU工程里直接编译运行。事实上，很多人第一次听见“SPI TFT”和“SquareLine_Studio”这两个词放在一起时，第一反应是“这不就是个串口屏上位机吗？”还真不是。串口屏是屏端自己跑协议，MCU发指令让屏去画；而SquareLine_Studio生成的是LVGL的应用层代码，渲染还是在你的MCU上完成，屏幕只是将像素数据通过SPI写进去的一块显存画布。两者的架构本质完全不同。
这也就决定了这个组合的适用人群和场景。如果你是做STM32F103这类入门级MCU、准备驱动一块1.8寸128x160或者2.4寸240x320的SPI TFT彩屏，又希望界面不是那种裸画像素级别的原始体验，而是带按钮、带滑块、带动态进度条甚至带简单动画的UI，那这套方案会让你少走一个月的弯路。对嵌入式工程师、电子竞赛学生、以及想快速做产品验证原型的创客来说，它最大的意义不是“不用写代码”，而是“不再把时间浪费在UI逻辑状态机的自我维护上”。
对于抖音、B站上那些动不动就给你贴几百行LVGL代码让你抄的人，我的态度是：代码可以抄，但架构理解不能省。SquareLine_Studio提供的是一条可视化到代码生成再到硬件落地的完整链路，它把LVGL的“窗口、控件、样式、动画、事件”全部封装成了图形化操作。但底层怎么刷新、SPI为什么要开DMA、为什么你的UI在F103上跑起来卡成幻灯片，这些问题它帮不了你，只能靠你在实战中去摸透。这也是我下文要展开的重点。
1.1 核心需求拆解：你要的其实不是UI工具，而是一条“可视化到硬件的链路”
标题里写了“从零构建”，这意味着假定读者是第一次接触SquareLine_Studio，也是第一次接触SPI TFT屏幕。那么整个项目的链路需要完成以下几步：
第一步，把一块SPI接口的TFT屏幕点亮，确认底层读写无误。第二步，跑通LVGL移植，至少在屏上能显示一点简单内容。第三步，在PC上用SquareLine_Studio设计UI并导出代码。第四步，把导出的代码与移植好的LVGL工程做合并，编译、下载、调试。第五步，做性能调优，解决刷新率不足和UI交互卡顿问题。
很多人死在第四步。因为SquareLine_Studio导出的UI工程默认假设你用的是Directories标准路径，它自带一个ui/目录，里面包含ui.c、ui_helpers.c、ui_events.c以及若干资源文件，这些文件依赖LVGL的特定版本，比如它可能默认基于LVGL 8.3.x生成。如果你的工程里LVGL版本不对，编译阶段就会冒出一堆莫名其妙的错误。这不是工具的问题，而是版本管理的问题。
所以这篇文章不是带你走马观花点一遍鼠标，而是把整条链路里的“为什么”都拆开讲清楚：为什么选择SPI而不是并口、为什么UI刷新要开DMA、为什么双缓冲对这个场景不是最优解、为什么图片资源要转换格式而不是直接塞进数组。这些问题搞懂了，你在任何型号的SPI TFT屏上迁移这套方案都只是改改初始化参数而已。
2. 方案选型：从屏幕到工具，每个选择背后都有取舍
2.1 为什么这个项目选择了SPI TFT而不是并口屏或RGB屏
先看数据，这是决定后续所有方案的基础。一块320x240分辨率的RGB565屏幕，单帧原始像素数据是320乘240乘2字节，等于153600字节，约150KB。如果用8位并口总线刷新一帧，假设总线速度是10MB/s，那么刷新一帧约需要15毫秒，理论上能跑到60fps。但前提是MCU要有足够多的GPIO引脚、要有外部并行总线的控制器、而且要能承受持续的数据搬运负担。对于STM32F103这种48脚甚至64脚封装，RGB屏的引脚根本不够分。
而SPI屏的优势在于引脚极少。以常见的ST7735S驱动芯片为例，一颗1.8寸128x160的屏幕，只需要VCC、GND、CS、RS（DC）、SDA、SCL、RESET和背光这8个引脚，其中数据相关的实际上就CS、DC、SDA、SCL四根线。引脚占用少，布线简单，几乎任何MCU都能驱动。代价是速度上限。SPI的时钟频率在F103上理论上可以到18MHz，实际稳妥跑在10MHz到12MHz之间，扣除协议开销和像素格式转换时间，刷一帧128x160的全屏图像大约需要30到40毫秒，也就是25fps左右。如果是240x320的屏幕，全屏刷新一帧的耗时大约要90到110毫秒，直白说就是10fps。这个速度跑静态UI完全没问题，跑滑动列表和复杂动画就会肉眼可见卡顿。
所以这个项目选择SPI TFT，本质上是拿刷新速度换了引脚数量和开发成本。项目定位如果不是游戏机、视频播放器这一类高刷新率场景，SPI屏搭配UI方案是完全没有问题的。项目标题中的“SPI”三个字，基本决定了整套技术栈的约束边界。
2.2 为什么选SquareLine_Studio而不是直接用LVGL手写
LVGL本身是一个开源的图形库，手写代码完全可行。问题出在开发效率上。在PC上运行一个UI编辑器，拖一个按钮进去，设置颜色、圆角、文字对齐、点击事件，若干秒就能完成。写代码的话，先要搞清楚lv_obj_t、lv_style_t、lv_btn_t这些结构体关系，再去查每个API的调用方式，一次典型的控件创建加样式设置至少要写几十行纯C代码，而且这还只是静态视觉部分。想要调整一下布局，就要改一堆坐标宏定义，重新编译烧录，直接在真机上看到效果。这个过程来回反复，极其消磨耐心。
SquareLine_Studio在2011年正式商业化后的企业版虽然收费，但那个面向个人和评估用途的社区版是免费的，而且功能上有很大一部分可用，比如多屏幕设计、事件绑定、动画编辑器、字体和图片资源管理。它的底层是通过TAG的方式把UI设计映射成LVGL的C代码，生成的是类似ui_Screen1_screen_init()这样的函数。这些函数做的事情就是创建对象、设置样式、绑定事件回调。你对LVGL手工需要写的内容，它帮你自动生成。
我的观点是，SquareLine_Studio适合那些对LVGL本身有一定了解的开发者，不一定要求非常深入，但至少要能看懂生成的C代码在做什么。如果完全看不懂LVGL代码，从零开始直接用它，一旦生成的代码有编译问题，你就会束手无策。反过来，如果你能看懂生成代码的逻辑，比如哪个函数负责哪块区域、哪个变量传递了哪个事件，那这个工具就是效率放大器。
3. 开发环境准备与工程初始化：老手也要拿着清单核对一遍
3.1 硬件平台选择与接线方法
我用的是STM32F103C8T6蓝色Pill板、一块1.8寸ST7735S SPI TFT屏，分辨率128x160。这套组合是成本最低的学习平台，全网资料最多，踩坑记录也最好查。如果你手头是ESP32、F103ZET6或其他MCU，流程是一样的，只是引脚映射不同。
F103C8T6的SPI1引脚：PA5接SCL，PA7接SDA（MOSI），PA6可以接MISO（ST7735S这个屏没有MISO输出，不接也行），PA4作为硬件NSS或者普通GPIO接CS，PB0接DC，PB1接RESET，PB10接背光。这里有一个细节要注意：ST7735S这类屏幕通常要求RESET引脚在初始化前拉低至少120微秒再拉高，保证芯片复位。有的模块板已经把RC复位电路做好了，RESET引脚悬空也行，但为了稳，还是用MCU引脚控制比较好。
接线完成后的第一件事，不是写代码，而是先把背光引脚接个3.3V让屏幕亮起来，确认没有接反烧屏。顺便说一句，SPI TFT屏幕的背光串的限流电阻一般在几十欧姆以内，3.3V供电没问题，别图省事直接给5V，屏幕一般会烫，长时间做有烧坏背光灯珠的风险。
3.2 CubeMX配置要点：SPI模式、时钟分频、DMA设置
打开STM32CubeMX，选择芯片型号，在Pinout视图里把PA5、PA7、PA4分别配置为SPI1_SCK、SPI1_MOSI、SPI1_NSS。然后打开SPI1的配置界面，关键的几个参数如下：
- Mode：Transmit Only Master。因为这个屏只需要往屏幕写数据，不需要从屏读数据。不过ST7735S是支持读显存的，但实际驱动里访问慢，极少用。Transmit Only模式能省一个引脚，且不会发生总线冲突。
- Hardware NSS Signal：Disable。这里如果你用的是PB0这类普通GPIO做CS，就把NSS禁用，自己用GPIO操作片选。如果你要用硬件NSS，可以考虑把NSS Config Type设置为Output，由SPI外设自动控制CS拉低拉高。两者各有优缺点，后面会单独展开。
- Maximum Speed（Data Rate）：建议先设置为4Mbps，后续再拉高。F103的APB2最高是36MHz，SPI1最大时钟是18MHz，4Mbps只是初始调试用的低速值，确保时序稳定性。
- CPOL/CPHA：SPI Mode 0和Mode 3是ST7735S最常用的两种组合。ST7735S的数据手册里写的是在SCL的上升沿采样数据，对应的就是CPOL=0、CPHA=0，也就是SPI Mode 0。如果屏幕显示花屏或者颜色错乱，优先怀疑这个参数——有一半的SPI屏问题是CPOL/CPHA搞反了。
DMA配置是重点。在CubeMX的DMA Settings选项卡里添加SPI1_TX通道，方向设为MemoryToPeripheral，优先级设为High。为什么需要DMA？因为SPI刷一帧全屏数据，128x160x2字节，等于40KB数据，如果靠CPU一个一个字节往SPI数据寄存器里塞，每一步都要等待TXE标志位。即便每次中断都打满，CPU也要全程盯着这件毫无价值的机械劳动。而DMA可以把数据从数组搬运到SPI发送寄存器，搬运完成再触发一次中断，整个过程CPU只负责启动一次搬运，然后可以去处理其他任务。实测下来，同样是4线SPI刷新128x160屏幕，不开DMA的CPU占用接近100%，开了DMA之后CPU占用可以降到20%以下，瞬间释放出来的算力就是给LVGL绘制的。
3.3 经典坑点：硬件片选与软件片选的取舍，以及复位时序问题
硬件片选和软件片选，这个坑刚接触时很容易纠结。硬件片选由SPI外设自动控制CS引脚的高低电平，好处是每次传输前自动拉低、传输完成后自动拉高，软件里少写几行GPIO操作代码。但折点在于：如果你用一个SPI总线上挂了多个SPI设备，比如屏幕上挂一个Flash，硬件片选就意味着每次切换从设备时要改外设的NSS输出配置或者用GPIO模拟，效率不高且容易出错。软件片选则不同，CS引脚完全由GPIO控制，换设备只是换个GPIO置低置高。ST7735S初始化时要求CS在写入命令和写入数据之间保持稳定，软件片选的时机更可控。
我的建议是统一用软件片选，哪怕SPI总线上只挂了屏幕这一个设备。原因有两条：其一，引脚复用更灵活，你可以选任何一个GPIO来做CS，不受芯片硬件NSS引脚的束缚；其二，初始化时序中需要连续操作CS和DC引脚，软件驱动能精确控制顺序。硬件片选唯一的优势是少写代码，但省那两行代码的代价是排查问题的成本增加。这个项目里CS接普通GPIO输出，写一个LCD_CS_ENABLE宏和LCD_CS_DISABLE宏，在每次SPI传输前后调用，简单可靠。
复位时序的问题很多新手没意识到。ST7735S上电后，INIT引脚需要拉低至少10毫秒再拉高，等待20毫秒以上才能发送初始化命令。有些屏模块自带RC复位电路，上电自动复位；有些没有，必须在主程序中用GPIO手动复位。如果上电后发现屏幕灰屏或者显示一条条竖线，先查复位时序，再查SPI参数，这个排查顺序能帮你快速定位问题。
3.4 LVGL移植：从源码到第一个像素点
LVGL的移植步骤看起来繁琐，其实核心就三步：第一步，把lvgl源码的src目录下所有c文件和h文件加到工程里，或者用keil的Manage Run-Time Environment直接勾选LVGL组件。第二步，配置lv_conf.h头文件里的颜色深度、屏幕分辨率、内存池大小等参数。第三步，注册占位刷新接口，让LVGL知道像素数据最终往哪里送。
这几个配置项直接影响后续SquareLine_Studio的接入：
LV_COLOR_DEPTH改为16。ST7735S支持RGB565格式，16位色深一个像素两个字节，刷新数据量是RGB888的三分之二。LV_HOR_RES_MAX设为128，LV_VER_RES_MAX设为160，跟屏幕分辨率一致。LV_MEM_SIZE至少设置为16KB。这是一个经常被忽视的参数，它决定了LVGL能创建多少个控件对象、多少条样式。值太小，运行时会出现lv_mem_alloc和lv_mem_defrag相关的断言失败；值太大，又挤占了其他模块需要的RAM。F103C8T6总RAM只有20KB，你还要给堆栈和DMA缓冲留空间，所以16KB是合理的下限，实际操作中可以把LVGL内存池和LCD的DMA缓冲区分开。
lv_conf.h里还有一项LV_TICK_CUSTOM，建议设置为1。它会用自定义的tick源，你只需要在工程里实现lv_tick_inc()，在定时器中断里每1毫秒调用一次。这个tick是LVGL处理动画、触摸长按、超时事件的时间基准，不用系统滴答计时器会导致动画速度不稳定。
完成这些之后，在main函数里调用lv_init()，然后创建一个label控件，lv_label_set_text(label, "Hello")，在while(1)循环里调用lv_timer_handler()。能显示出文字，就说明LVGL移植成功了。注意这里的显示流程：lv_timer_handler()会遍历所有需要刷新的脏区域对象，调用你注册的disp_flush回调，把裁剪区域内的像素数据通过SPI写入屏幕控制器。一支笔一帧一帧地从内存写到屏幕，这个模型理解清楚了，后续性能优化就有方向了。
4. SquareLine_Studio UI设计实战：从空白画布到可用界面
4.1 创建工程时的关键选择：芯片类型、分辨率、色彩模式与LVGL版本
SquareLine_Studio的工程创建向导里有一大堆预设模板，有给桌面PC用的、有给树莓派用的，也有给ESP32、STM32这些MCU用的。我的经验是不要被这些模板迷惑，直接选择“Custom”或者“Empty”模板，然后手动设置屏幕参数。
屏幕分辨率设置为128x160。需要特别注意的是，SquareLine_Studio里的宽高是按像素来算的，和写驱动时使用相同的坐标体系，横屏为160x128，竖屏为128x160，选错会导致后续导出的代码在运行时位置偏移。
色彩模式选RGB565，16位。如果界面里有半透明效果、圆角阴影，SquareLine_Studio在生成代码时会用ARGB8888的alpha通道去混合。RGB565模式可以正常显示，但阴影和抗锯齿效果会有色阶断层。这不是bug，是色深硬件限制，属于正常现象。
LVGL版本选择8.3.x。这是目前稳定性和工具兼容性的最佳平衡点。如果选了9.x版本，生成的代码结构完全不同，你的工程也要跟着升到LVGL 9，很多老驱动代码需要适配。除非你从一开始就打算用9，否则别给自己找额外版本迁移的麻烦。
创建工程的空间布局可以按自己的习惯来——面板放在右侧、预览窗口全屏、Layer列表显示全部控件。这个工具拖拽起来手感与QT Designer这类同类工具有些接近，但功能上要轻量得多。
4.2 界面布局设计：给控件咬合成一套层次清晰的画面
一个经典的SPI TFT UI界面，建议从最简单的“主页 + 若干功能页”模式开始。主页放一个设备名称、一个状态指示器、两个按钮，分别进入设置页和数据显示页。设置页放几个滑块和开关。数据显示页放一个带数值标注的动态图表。
在SquareLine_Studio里实现这个结构，核心操作如下：在Canvas区域里建立两个Screen，分别命名为Screen_Main和Screen_Setting。Screen的右侧有个Hierarchy面板，每个控件作为对象的子节点挂上去。主页Screen先Add一个“Container”作为背景底色容器，再把Label、Button等放进去。注意不要在Screen上直接堆控件，加一层Container便于统一管理整体背景和布局偏移。
按钮的点击反馈可以绑定一个简单事件。在右侧Event栏选择“Clicked”事件，然后点击“Add a new event”按钮，编辑器中会打开一个代码编辑窗口。这里不需要写Python或JS，SquareLine_Studio用的是C代码片段，生成的代码会放在ui_events.c文件里。用户在编辑器里写的回调代码会被原样生成到事件函数中。如果你只写一句_ui_screen_change(&ui_Screen_Setting, &scr_setting_del, scr_setting_init, 0, 0);，就会生成一个从主页跳转到设置页的切换逻辑。
一个设计细节不要忽略：不同屏幕切换时的动画时间。SquareLine_Studio的屏幕切换事件里有一个动画时长参数，系统默认为300毫秒。这个参数如果设置到500毫秒以上，在F103上运行时帧率不稳，切换动画会有明显卡顿。建议调到100到150毫秒之间，或者直接设为0禁用切换动画，给人一种“瞬间切换、反应迅速”的感觉，比强行跑慢动画体验更好。
4.3 资源管理：图片、字体、图标，一个都不能用默认值
SquareLine_Studio的资源处理是新手最容易走偏的地方。项目里插了一张背景图，导出C代码时它会把图片像素数据直接转成一个巨大的C数组并嵌入到ui_xxx_images.c文件里。对于128x160的小屏，一张全屏背景图RGB565格式，原始数据大概是40KB多一点，存进F103C8T6的64KB Flash里问题不大。但如果你放了3张全屏背景、又加了一堆按钮的交替按下状态图，Flash很容易就爆了。
解决办法有两个。一是用微控制器端有损压缩格式，把图片在SquareLine_Studio里转换为LVGL支持的压缩格式；二是把图片放到外部SPI Flash里，运行时按需读取。F103C8T6这个平台，最简单的是方案一。SquareLine_Studio的图片导入界面有Format选项，选“RGB565A8”或者“RGB565”并配合“Compressed”选项，可以大幅压缩图片体积，代价是加载时需要解压缩，CPU占用会高一些。但静态页面和仅启动时显示一次的Logo图，用这个方案毫无压力。
字体同理。SquareLine_Studio默认会用系统字体来呈现中文，但它在生成C代码时只会把界面中实际出现的文字打包进字库。如果你在程序中用代码动态设置了一段没有在UI编辑器里出现过的中文文本，这块内容在真机上会显示为空白或乱码，这就让人抓狂了。解决方法是把可能用到的汉字全部在工具里以“添加到字库”的方式选中。或者在导入字体时用一个覆盖所有常用字的完整字库文件，导出后嵌进工程，增大Flash占用但省心。我的建议是动态文字尽量用英文或数字，界面标题等静态文字全部在编辑器里写好。
另一个很实用的功能是“Symbols字体”，可以插入一些图标符号，比如音量、齿轮、WiFi图标，这些矩形符号自带，无需你额外准备图标图片。使用它可以让界面看起来更有设计感，又不必为每个图标单独准备素材。
4.4 导出代码：文件结构、参数确认，和生成环境的耦合关系
点击Export后，SquareLine_Studio会输出一个含有ui/的目录，里面的核心文件包括：
ui.c：汇总初始化入口，包含ui_init()函数，调用所有Screen的init函数。ui_helpers.c：辅助函数，比如屏幕切换和进度条更新。ui_events.c：事件回调函数，所有你在编辑器里绑定的C代码都在这里。ui_<screen_name>.c：每个Screen的创建函数，里面是控件树和样式设置代码。ui_<screen_name>.h：对应的头文件。- 若干
images、fonts资源文件。
这一步有两个核心参数要确认车轮：第一个，项目设置里的“LVGL version”是否与MCU工程一致，8.3对应8.3，搞错直接编译报错；第二个，生成器使用的包含路径，SquareLine_Studio默认用#include "lvgl.h"和#include "ui.h"，因此你的工程里lvgl.h的路径必须能被找到。如果没有配置好Include Path，编译时会出现“lvgl.h file not found”错误。
导出后在MCU工程里需要手动做的事：把ui.c、ui_helpers.c、ui_events.c以及所有屏幕的c文件添加到Keil或CMake编译列表，确保头文件路径包含在编译器的搜索目录里。然后在主程序里调用ui_init()，并在lv_timer_handler()的循环中加入持续刷新逻辑。从这一刻起，你这块SPI TFT彩屏就已经跑上了SquareLine_Studio设计的UI界面。
5. 底层驱动对接的深度剖析：为什么你的UI会卡，为什么屏幕会花
5.1 画面刷新机制：LVGL脏矩形、像素格式转换、SPI DMA传输如何配合
LVGL不会每帧全屏重绘，它只把有变化的区域标脏，然后逐区域调用flush回调。假设你现在点击了一个按钮，这个按钮的图形区域会被切成一个个脏矩形，LVGL把这个矩形内的像素数据通过flush回调传给底层。因此，你的驱动层设计得越好，实际刷新的数据量就越小，这也是UI流畅度差异的主要来源。
在disp_flush回调函数里做了这么几件事：第一，取出area参数中的x1、y1、x2、y2，计算宽度和高度，把color_p（LVGL传入的像素指针）按RGB565排列好。第二，设置DC引脚为命令模式，发送“设置窗口”指令，告诉屏幕控制器一个坐标范围。第三，设置DC引脚为数据模式，用SPI DMA把(width * height * 2)字节的数据一次性发给屏幕。数据量取决于脏矩形的大小。如果你点击一个大按钮，窗口尺寸可能是60x40像素，也就是4800字节，这个量在DMA的帮助下用不到1毫秒就能发完，实际瓶颈反而在于ST7735S内部接收和自刷新GRM显存的时间。
特别要提一下像素格式。ST7735S的显存格式是RGB565，LVGL在你的工程里配置了16位色深，所以颜色数据可以直接透传，不需要转换。如果你用的是18位色深甚至24位，就必须要做格式转换，而这个转换需要在CPU上逐像素进行，性能开销很大。这就是为什么在STM32F103这类MCU上一定要设定LVGL颜色深度为16的原因。
5.2 DMA中断与半传输中断的实际价值：如何避免画面撕裂
如果只用普通的DMA发送，不打开DMA发送完成中断，也可以正常工作。但打开DMA传输完成中断有两个好处。首先，可以在中断里把CS拉高，结束一次传输，这样片选时序比较干净；其次，可以在中断里做一个标志位，告诉上层驱动“上一次传输已经完成，可以发送下一帧数据了”。
对于120x160分辨率的静态UI，DMA发送40KB数据大约需要3到4毫秒，这个数字不算大，即使不用双缓冲也能维持基本流畅。但如果屏幕分辨率是240x320，一帧数据是150KB，DMA发送大约需要20毫秒，这时就需要考虑双缓冲或者局部刷新策略了。
双缓冲的机制是：申请两帧的内存区，LVGL画到buffer0的同时，DMA从buffer1搬运到屏幕，两个缓冲区交替使用。对F103C8T6来说，内存只有20KB，两帧150KB根本不现实。所以这个方案在F103上通常不可行，更合理的方案是让LVGL的缓冲区与DMA缓冲区共用同一块内存，实在不行就牺牲一点帧率，保持单缓冲+整屏刷新，然后尽量缩小脏矩形面积来弥补。
如果你的硬件换成了F407、H743或者ESP32-S3这类内存与总线速度更强的MCU，双缓冲同时开启来达到60fps的刷新率才是合适的。这里想强调的是：不要盲目拼性能，要在搞清楚硬件的边界条件之后，再去匹配刷新方案。
5.3 常见底层异常：花屏、乱码、闪烁、颜色错乱的逐一排查流程
花屏这个现象，通常的根因就是SPI时序参数错误。CPOL、CPHA设置有误、时钟极性不匹配，屏幕控制器在错误的时钟沿取走数据，就会出现“屏幕上随机出现彩色噪点”，基本没有规律。排查方案：先把SPI时钟降到1Mbps，如果花屏现象消失或改善，说明高频时序余量不足，试着调整CPOL/CPHA再做压力测试。降到1Mbps后画面基本能出，但速度很慢——这种情况下再去调整时钟极性和相位，等每一参数都稳定后，再逐步调高时钟。
乱码的另一大根因是DC引脚的控制时序错误。ST7735S判断当前传输的是命令还是数据，完全看DC引脚的电平。如果在发送命令字节时DC没有及时置低，或者在数据段被置高，屏幕就会接收到“位移”的命令码，直接显示成一堆乱码或者出现屏幕偏移。排查方法：用逻辑分析仪抓取发送首个初始化命令时的DC和MOSI波形，确认在DC拉低期间MOSI线上是0x01之类的命令字。
屏幕闪烁或者颜色错乱，则要怀疑背光控制与刷新节奏是否同步。如果背光在DMA传输过程中切换了亮度，屏幕上肉眼可见的频闪会非常明显。解决方案是给LCD背光控制加一个PWM低通滤波电容，或者将背光控制函数与屏刷新任务放到同一个临界区。
还有一个小概率事件，DMA的Memory to Peripheral配置里如果外设地址写错了，把SPI1_DR地址传成了SPI1_SR地址，那么每次DMA写入的都是状态寄存器，屏幕自然纹丝不动。这种问题逻辑分析仪也不好查，重点检查DMA初始化结构体里的参数是否填对。
6. UI运行性能优化：让F103这块小屏也能跑出接近流畅的体验
6.1 帧率瓶颈分析：你的时间到底浪费在哪里
SPI TFT屏的刷新流程可以拆成四个环节：LVGL绘制渲染、DMA搬运像素到SPI、ST7735S控制器接收数据更新内部显存、屏幕实际显示。数据发到ST7735S后，屏幕控制器需要将数据写入内部GRAM地址，这部分延迟通常表现为数据线转低时出现的写显存周期，如果屏控制器较慢，还需要等待内部忙标志恢复。
如果运行中感觉界面卡顿，先分清是“绘制慢”还是“传输慢”。绘制慢的表现是点击一个按钮要过一两百毫秒才有反馈，这个时间大部分花在LVGL内部对控件树的样式计算上。传输慢的表现则是界面数据变化后，屏幕画面从下往上刷出去，有明显的“扫描线”进度。绘制慢需要对LVGL渲染配置下手；传输慢要检查SPI分频和DMA配置。
在实际的F103 128x160屏幕上，最容易出现的问题是：整个UI页面滑动时，LVGL把整个页面大小都设成了脏区域，于是每次滑动都触发全屏刷新。这一个160KB全屏数据由SPI发送，耗时大约40ms，滑动时每一帧都要重新刷全屏，帧率自然掉到20fps以下。优化方向是合理使用LVGL的滚动机制，让列表控件滚动时只刷新列表区域，而不是整个页面。
6.2 LVGL和驱动参数的一整套调优清单，照着改就行
以下这个清单适用于LVGL 8.3及STM32F103，其他平台可对照调整：
- 显示缓冲区大小：
lv_disp_draw_buf_init()的buf大小至少设置为屏幕单行像素的两倍。128宽的单行数据是256字节，推荐设为128 * 10 * 2 = 2560字节，能明显改善连续滚动时的撕裂感。 - 脏矩形处理开关：LVGL默认开启脏区域收集，这个不要关。也就是
LV_DISP_DEF_REFR_PERIOD默认16毫秒，这个周期接近60fps的刷新节奏，如果界面复杂可以适度调大到33毫秒，让CPU有更多喘息时间。 - DMA初始化：SPI1_TX，DMA方向MemoryToPeripheral，优先级High，Burst模式可不开启（F103不支持burst）。
- SPI时钟：从4Mbps起步，测试稳定后逐步提高到12Mbps，不要死磕最高频率，实测大多数ST7735S在16MHz以上就不稳定了。
- 图片与字体资源：优先使用RGB565和内置压缩，避免运行时反复解码浪费时间。
- 动画时长：SquareLine_Studio里所有动态效果时长控制在150毫秒以内，模式用EaseOut，避免线性动画感觉拖沓。
LV_USE_PERF_MONITOR：在lv_conf.h里打开这个宏，屏幕上会显示当前FPS和CPU占用率。优化前后对比一下数值，比人眼判断准得多。
这套配置做完之后，UI流畅度的提升肉眼可见：按钮反馈从模糊的“等半秒”变成“按下立刻响”，滚动列表从一卡一卡变成基本跟随手指。
6.3 进阶：如何让F103在有限RAM下再挤出性能
F103C8T6只有20KB RAM，LVGL内存池16KB后，留给其他模块的已经不多。但仍有一个值得优化的方向：局部缓冲策略。LVGL有两种刷新模式，一种是全屏缓冲，需要至少150KB内存，F103直接排除；另一种是“逐行刷新”，只开一整行缓冲，但行数过少时SPI传输次数更多。折中方案是申请一个128x10行的缓冲，即2.5KB内存，刷新性能介于逐行和全屏之间，且不鼓励真机撕裂。
在CubeMX或者代码里把DMA的SPI输入缓冲固定为上述缓冲区地址，点击UI时可以先快速把缓冲区的数据发出去，再让LVGL填充下一块区域，连续滚动时的显示效果会比小缓冲明显顺很多。说句实话，这个方案是F103上“花小钱办大事”的关键，强烈建议试试。
7. 常见问题排查与避坑记录：开发现场遇到的那些“诡异”问题
7.1 SPI通信不生效，或者屏幕全黑怎么排
这个问题占了所有新手的80%。首先是供电问题。ST7735S工作需要3.3V供电，一些屏幕模块板兼容5V电源输入，但如果你直接接到5V电源去供电，逻辑电平会不匹配，SPI数据线上的波形可能识别不了。确定供电正常后，检查SPI模式的时钟极性和相位设置，将SCLK空闲电平设置为低、在第一个时钟沿采集数据，这是ST7735S的标准模式。如果你不确定，把SPI的mode从Mode 0切到Mode 3分别烧写看效果，有且仅有这两种模式才是这个屏能接受的。
接着检查CS和DC引脚的初始化状态。上电后CS不能浮空，不然SPI总线上的杂散信号可能把屏幕状态机带飞。建议在驱动初始化代码最开始就把CS指定为输出高、DC指定为输出低，RESET先拉低再拉高。调到这里屏幕大概率能亮起来了。如果还不行，用示波器或逻辑分析仪量一下RESET波形，有些模块板的RC复位时间过长，初始化时序到达时芯片还处于复位状态，也会全黑。
7.2 SquareLine_Studio导出代码编译报错：版本不匹配的类型错误
我遇到过很多次，“ui_helpers.c”里用到的_ui_screen_change函数编译不过，报undefined reference。原因通常是工程里的LVGL是8.2或9.x，而SquareLine_Studio生成代码默认基于8.3。不同的LVGL小版本在函数签名上有时会微调，但更大的问题是重命名。如果用9.x的LVGL，_ui_screen_change函数直接不存在，因为9里用的是lv_screen_load。
解决方案要么是升级或降级LVGL版本到8.3，跟SquareLine_Studio保持一致，要么修改生成的代码来适配旧版本。适配工作比较多，所以建议一开始就用8.3。
另外的常见报错是缺少头文件，“ui_events.h”找不到。SquareLine_Studio生成的头文件引用路径是#include "ui_helpers.h"、#include "ui_events.h"，如果你的编译器包含路径没有指向ui目录，这些找不到就会报错。在Keil里把ui/目录加进C/C++ Include Paths，就不会有这个问题。
7.3 DMA搬运与LVGL刷新冲突导致花屏的幕后真相
这种问题最阴险：界面平时正常，但UI操作稍频繁一些就开始花屏，屏幕上随机出现横条或色块。根因在于DMA和设备寄存器之间的预备时序未同步：当LVGL的flush回调被调用时，上一帧的DMA传输可能还没完成，驱动函数没等DMA Done标志位就重设了SPI的地址和数据长度，DMA数据错位，打到屏幕的像素数据就乱了。
正确做法是在disp_flush回调里等待DMA传输完成，再去开启下一批传输。最简单的是用一个全局标志位：DMA传输完成中断里置这个标志，flush里先while循环等标志，等到了再清标志继续。关键点是确保LVGL画新一帧时不会踩到DMA正在发送的数据。缓冲区设计时，除了LVGL缓冲，还需要一块专门给DMA发送的队列缓冲。如果直接共用缓冲区，LVGL前脚画好、DMA后脚还没发完就开始覆盖，花屏就会频繁出现。
7.4 触摸屏的接入与校准：让你的UI界面变得“可交互”
很多SPI TFT模块板带触摸屏（一般是XPT2046），接口走SPI或单独的模拟引脚。接入触摸后，UI的按钮才可以真正被点击。LVGL里接入触摸屏的方式也很简单：注册一个输入设备，在读取函数里返回触摸坐标。
XPT2046的数据读取需要模拟SPI或者另一路SPI，但这部分代码比较成熟，移植难度不大。需要注意触摸校准。128x160这种小屏通常需要在出厂时配置几个校准点，如果触摸坐标和显示坐标有偏差，可以写一个简单的三点校准算法，在lv_indev_drv的read_cb里把原始ADC值换算成屏幕坐标。还有一种特殊情况，触摸屏的AD值跟我们平时理解的方向相反，读取出的坐标会左右上下翻转，运算里加上取反或坐标变换就行。
从小白到能独立调试，触摸接入本身并不是UI开发的重点，但它会显著提升你完成这个项目的成就感——当你用手指在屏幕上滑动手势时，那种“这屏幕活了”的感觉，对学习动力有很大帮助。
8. 写在最后的一点延伸经验
SquareLine_Studio加SPI TFT这组方案，经过我多次在不同芯片上折腾，有一个感受值得拿出来分享：它极大的缩短了从“想法”到“可演示原型”的距离。以往在MCU上搭UI界面，视觉上的反复试错是最耗时的，很多时间其实花在了界面的位置微调和颜色搭配上。现在用可视化工具在PC上几秒改完、重新导出、替换文件，编译下载，预计10分钟内就能看到新效果，速度完全提升一个量级。
我也建议下一步往这几个方向扩展：一是试着跑一个动态图表组件，看看在48MHz主频下用LVGL的chart控件能刷到多少帧；二是在工程里加一个外部SPI Flash，把动画帧和图片资源放到Flash里学着运行时按需加载，解锁更多UI表现力；三是从ST7735S迁移到ST7789或者ILI9341这类分辨率更高、驱动方式相似的屏，你会发现自己有了举一反三的能力。
整个过程中我最想强调的一点：不要被“可视化工具”四个字迷惑，底层原理才是你的底气。SquareLine_Studio生成的是LVGL代码，LVGL又依赖良好的底层驱动才能把每一帧像素准确地刷到SPI TFT上。链路里任何一个环节薄弱，最终体验都会露馅。把这条链路里的每个“为什么”都搞明白，你在嵌入式UI开发这一块，就算是真正站住脚了。
