TouchGFX 滚轮式菜单快速开发：MenuContainer 容器应用实操指南

在嵌入式 GUI 开发中，流畅的滚轮式菜单是提升产品交互体验的关键功能。ST 提供的 MenuContainer 自定义容器（适配 STM32N6570-DK 开发板），可快速实现炫酷的滚轮选择界面，支持图标切换、动画过渡与界面跳转，开发者无需从零搭建，仅需导入容器、替换素材并配置交互即可完成开发。本文详解容器导入、素材适配、交互配置的完整流程，适用于 TouchGFX 基于 STM32 的嵌入式项目。

资料获取：TouchGFX中滚轮式菜单选择界面容器的应用介绍

1. 核心优势与环境准备

1.1 容器核心价值

• 开箱即用：提供完整的滚轮动画、菜单布局与交互逻辑，无需手动编写复杂动画代码；
• 高度可定制：支持替换图标、文字、字体与动画素材，适配不同产品风格；
• 轻量高效：基于 TouchGFX 容器机制，资源占用低，运行流畅，适配 STM32 中高端 MCU；
• 快速集成：支持导入任意 TouchGFX 工程，无需修改底层框架。

1.2 软硬件与工具环境

• 硬件：STM32N6570-DK 开发板（或其他 TouchGFX 支持的 STM32 MCU 开发板）；
• 软件：TouchGFX Designer 4.25.0（需匹配容器兼容版本）；
• 资源包：MenuContainer.tpkg（滚轮菜单容器包）、字体文件、动画图片集（launch_demo_0001.png~launch_demo_0022.png）。

2. 容器导入与素材适配

2.1 导入 MenuContainer 容器

（1）工程准备

（2）导入容器包

1. 操作路径：点击菜单栏「Edit → Import → Custom Container」；
2. 选择文件：选中MenuContainer.tpkg，点击「导入」；
3. 注意事项：导入后工程会自动添加容器相关的代码文件（MenuContainer.cpp/MenuContainer.hpp）与布局配置。

2.2 素材补全与字体配置

（1）解决字体缺失问题

• 导入容器后会弹出字体缺失提示，需将配套字体文件复制到工程目录assetsfonts下；
• 关闭 TouchGFX Designer 并重新打开，工程会自动识别新添加的字体；
• 配置字体：在「Typographies」中，为MainSelectedSubDemo和MainLaunchIcon指定导入的字体（或自定义选择其他字体）。

（2）补全动画图片

• 容器默认仅导入动画的首张和末张图片，需将完整动画集（launch_demo_0001.png至launch_demo_0022.png）复制到assetsimagesMainlaunch-animation文件夹；
• 验证：在 TouchGFX Designer 的「Images」中查看，确保 22 张动画图片全部加载成功，无缺失或损坏。

3. 交互配置：实现菜单与界面切换

3.1 新建目标界面

• Screen1：作为主菜单界面，用于放置 MenuContainer 容器；
• Screen2：作为目标界面，用于演示菜单选择后的跳转效果。

3.2 添加容器到主界面

1. 在 Screen1 的「Containers」面板中，找到MenuContainer并拖拽到界面画布中，调整位置至合适区域；
2. 关键说明：MenuContainer 容器默认配置中，goToMenu动作会跳转回 Screen1，若主菜单界面名称不是 Screen1，需在容器属性中修改对应配置。

3.3 配置界面跳转动作

（1）添加自定义 Action

1. 选中 Screen1 中的 MenuContainer 容器，进入「Actions」选项卡；
2. 点击「Add Action」，创建新动作goToScreen2（用于触发跳转到 Screen2）。

（2）绑定交互逻辑

1. 进入容器的「Interactions」选项卡，添加交互规则：
   • 触发条件：goToScreen2动作被调用；
   • 执行操作：「Change Screen」→ 选择「Screen2」，设置过渡动画（可选）。

（3）修改代码关联菜单选项

void MenuContainer::changeScreenTo(uint8_t selectedDemoIndex) {
    switch (selectedDemoIndex) {
        case 0:
            goToMenu(); // 跳转回主菜单（Screen1）
            break;
        case 1:
            goToScreen2(); // 选中AI DEMO（索引1），跳转至Screen2
            break;
        case 2:
            goToMenu();
            break;
        case 3:
            goToMenu();
            break;
        case 4:
            goToMenu();
            break;
        case 5:
            goToMenu();
            break;
        case 6:
            goToMenu();
            break;
        default:
            break;
    }
}

• 说明：selectedDemoIndex对应滚轮菜单中各个图标的索引（从 0 开始），可根据实际菜单顺序调整跳转逻辑。

4. 仿真与调试

4.1 模拟运行验证

1. 点击 TouchGFX Designer 的「Simulate」按钮，启动仿真；
2. 操作测试：
   • 滚轮滚动：菜单图标应流畅切换，选中项高亮显示；
   • 点击选中：点击 AI DEMO 图标，应触发goToScreen2动作，成功跳转到 Screen2；
   • 动画效果：验证 launch-animation 动画是否完整播放，无卡顿或丢帧。

4.2 实际硬件调试

1. 将工程编译生成固件，烧录到 STM32N6570-DK 开发板；
2. 硬件测试：确认滚轮菜单交互、界面跳转与动画效果均正常，无响应延迟或显示异常。

5. 自定义扩展：替换素材与风格

5.1 替换菜单图标

• 准备自定义图标图片（建议与原图标尺寸一致）；
• 替换路径：assets/images/Main/下对应的图标文件，保持文件名不变；
• 刷新工程：TouchGFX Designer 会自动更新容器中的图标显示。

5.2 修改菜单文字

• 在MenuContainer.cpp中找到文字配置代码，替换为自定义菜单名称（如 “设置”“数据查看” 等）；
• 调整字体大小：在「Typographies」中修改对应字体的尺寸，适配界面布局。

5.3 调整动画效果

• 替换动画图片集：将自定义动画图片按 “xxx_0001.png~xxx_00xx.png” 命名，替换launch-animation文件夹下的原文件；
• 调整动画速度：在容器代码中修改动画播放帧率（需熟悉 TouchGFX 动画 API）。

6. 注意事项

1. 字体配置：导入字体后必须重启 TouchGFX Designer，否则字体无法识别；
2. 界面名称：主菜单界面必须命名为 Screen1，或修改容器中goToMenu动作的目标界面，否则跳转失效；
3. 素材路径：动画图片必须放在assets/images/Main/launch-animation目录下，路径错误会导致动画无法播放；
4. 索引匹配：selectedDemoIndex需与菜单图标的实际顺序一致，否则点击逻辑错乱；
5. 版本兼容：TouchGFX Designer 版本需为 4.25.0 或兼容版本，低版本可能导致容器导入失败。