3. 第一个TouchGFX工程：从空白到点亮屏幕

好，咱们正式开始动手了。这一章的目标很明确——用TouchGFX Designer创建一个空白工程，生成代码，编译，最后下载到开发板上跑起来。说白了，就是走通整个工具链，让你心里有个底。

我记得我第一次用TouchGFX的时候，光是在“生成代码”这一步就卡了半小时。后来发现是路径里有中文……嗯，这种坑咱们今天一并填上。

3.1 准备工作：确认你的环境

在点开TouchGFX Designer之前，先花两分钟确认三件事：

• TouchGFX Designer已安装 —— 版本4.18以上最好，界面和操作逻辑基本一致。
• STM32CubeMX已安装 —— TouchGFX依赖它生成底层HAL代码。
• 编译器已就绪 —— 我用的是STM32CubeIDE，你也可以用Keil或IAR，但后续步骤会以CubeIDE为例。

3.2 创建空白工程：三步走

打开TouchGFX Designer，你会看到一个欢迎界面。别慌，跟着我来：

1. 点击“Create New” —— 在左上角或者中间的大按钮。
2. 选择模板 —— 选“Empty Application”。这就是空白工程，没有任何预置的控件或页面。
3. 配置工程参数 —— 弹出一个对话框，需要填几个关键项：

填好后点“Create”。等几秒钟，工程就建好了。你会看到Designer界面左侧多了一个“Screen1”的页面缩略图——这就是你的第一个屏幕。

3.3 认识TouchGFX Designer界面

工程创建后，你会看到这样一个布局。我简单拆解一下：

• 左侧面板 —— 页面/容器树。显示当前工程的所有Screen和Container。
• 中间画布 —— 所见即所得的UI编辑区。你可以拖拽控件上去。
• 右侧属性面板 —— 选中某个控件后，这里显示它的所有属性（位置、大小、颜色等）。
• 底部输出窗口 —— 编译和生成代码时的日志。

对于空白工程，画布上只有一个空白的Screen1。别急着加控件——咱们先走通编译下载流程，确保工具链没问题。

3.4 生成代码：一键搞定

在Designer的工具栏上，有一个“Generate Code”按钮（齿轮图标）。点它。

你会看到底部输出窗口开始滚动日志。生成过程大概10-30秒，取决于电脑性能。完成后，日志末尾会出现“Code generation finished successfully”字样。

这时候，去你的工程目录看一眼：

D:/TouchGFX_Projects/MyFirstTouchGFX/
├── MyFirstTouchGFX/          # TouchGFX Designer生成的UI代码
├── STM32CubeMX/              # CubeMX生成的HAL配置
├── TouchGFX/                 # 核心库和资源
├── project.mk                # 编译脚本
└── .project                  # IDE工程文件

嗯，结构很清晰。TouchGFX Designer只负责生成UI相关的代码，底层的硬件初始化、时钟配置、LCD驱动这些，它交给CubeMX去处理。

3.5 编译工程：从代码到二进制

生成完代码，接下来要编译。我用STM32CubeIDE演示，其他IDE流程类似。

1. 打开STM32CubeIDE —— 选择工作空间为工程目录的上一级（比如 D:/TouchGFX_Projects）。
2. 导入工程 —— File → Import → Existing Projects into Workspace，选中 MyFirstTouchGFX 文件夹。
3. 编译 —— 右键工程名 → Build Project。或者直接点工具栏的锤子图标。

第一次编译会慢一些，因为要编译TouchGFX核心库。我的经验是，大概2-5分钟。如果编译成功，控制台会输出：

Finished building: MyFirstTouchGFX.elf

如果报错，八成是路径问题或者CubeMX配置没同步。别急，看错误日志——TouchGFX的编译错误通常很直白，比如“找不到头文件”或者“未定义的引用”。

3.6 下载到开发板：点亮屏幕

编译通过后，生成的是 .elf 或 .hex 文件。接下来把它烧录到开发板。

1. 连接开发板 —— 用USB线连到电脑。确保驱动装好了（ST-Link驱动）。
2. 配置调试器 —— 在CubeIDE里，右键工程 → Debug As → STM32 Cortex-M C/C++ Application。
3. 下载并运行 —— IDE会自动识别调试器，下载代码，然后复位运行。

如果一切顺利，你会看到开发板的屏幕亮起来——虽然是个空白屏幕，但背光亮了，说明LCD驱动正常，TouchGFX框架已经跑起来了。

3.7 本章核心流程总结

来，我把这一章的核心逻辑画成一张图，方便你记忆：

这张图把咱们今天做的事串起来了。从创建工程到下载运行，一共四步。每一步都有对应的工具和产出物。

3.8 常见问题与避坑

最后，我把我在项目中遇到过的几个典型问题列出来，你碰到了可以直接查：