SquareLine基本使用
215.3.14 SquareLine基本使用
本节只讲 SquareLine Studio 的安装、建工程、摆放控件、修改属性与 Play mode 预览，尚未讲 UI 代码导出和 STM32 工程调用，因此本节不补源码；代码导出与
ui_init()的调用属于下一课。
一、LVGL是什么
LVGL（Light and Versatile Graphics Library）是面向嵌入式设备的图形界面库。把它简单理解为“应用层与 LCD 驱动之间的中间件”有助于入门，但更准确地说，它是一套完整的 GUI 引擎：负责控件、对象树、布局、样式、动画、事件、输入处理和软件渲染。
在本课程工程中，各层的大致关系如下：
main.c / 业务逻辑 → SquareLine 生成的 UI 代码与 LVGL API → LVGL 渲染 → 显示接口 → LCD 驱动 → HAL 库 → SPI/GPIO → LCD
触摸数据走相反方向进入应用：
触摸芯片 → 触摸驱动 → LVGL 输入设备接口 → LVGL 事件 → 应用回调函数
- 应用层：决定界面显示什么，以及按键、滑块等控件被操作后执行什么业务。
- LVGL：管理控件状态，把界面绘制到显存缓冲区，并通过已注册的显示刷新回调把像素交给底层驱动。
- 显示与输入移植层：把 LVGL 与具体 LCD、触摸芯片连接起来。LVGL 本身不知道当前硬件使用 SPI、并口还是其他总线。
- 底层驱动与 HAL：真正操作 SPI、GPIO 等外设。本课程的 LCD 驱动最终使用 STM32 HAL 的 SPI 接口发送数据。
不使用 LVGL，也可以直接调用 LCD 驱动显示文字和图片；使用 LVGL 的主要价值不是“屏幕才能显示”，而是获得统一的控件、样式、布局、事件和输入系统，从而更容易制作和维护复杂界面。
SquareLine Studio 与 LVGL 不是同一个东西：
| 项目 | 作用 | 是否在单片机上运行 |
|---|---|---|
| LVGL | GUI 运行库，负责对象管理、事件和渲染 | 是 |
| SquareLine Studio | PC 端可视化界面设计与代码生成工具 | 否 |
| LCD/触摸驱动 | 连接 LVGL 与具体硬件 | 是 |
SquareLine Studio 可以把画布上的 Screen、Button、Label、Arc 等控件转换成相应的 LVGL 创建与属性设置代码，但它不会自动完成以下工作：
- 不会替代 LCD 和触摸驱动；
- 不会自动完成 MCU 时钟、GPIO、SPI、定时基准等初始化；
- 不会自动实现按键控制 LED 等业务逻辑；
- 生成的代码仍需导出、加入编译并在已有 LVGL 工程中初始化。
因此，“在 SquareLine 中画完就能直接在单片机显示”并不严谨。正确流程是：先完成 LVGL 与硬件的移植，再设计并导出 UI，最后把生成代码集成到单片机工程中。
1.1 软件的安装
本课视频和配套工程使用的是 SquareLine Studio 1.5.0。配套工程元数据还表明，该工程面向 LVGL 8.3.11。不同版本的启动器、许可和菜单文字可能变化，操作时应优先依据实际界面，不能把本课截图机械套用到所有版本。
视频中的安装流程如下：
- 在课程网盘的“3.1 专题/软件工具”中找到 SquareLine Studio 安装包；原笔记中的
scroll line是语音识别错误。 - 双击 Windows 安装程序，在安装界面点击
Install。 - 遇到 Windows 权限确认或联网提示时，先阅读提示内容，再按需选择“是”。
- 安装结束后，从桌面图标或开始菜单启动 SquareLine Studio。
当前仓库快照中没有附带 SquareLine Studio 安装程序。如需重新下载，应从 SquareLine Studio 官方下载页 获取安装包，不要使用来源不明的第三方安装文件。外网下载或联网激活受阻时，按本项目约定使用本地代理 127.0.0.1:1080；代理协议应与本机代理软件实际提供的协议一致。
首次启动或激活许可证需要联网。课程版本的许可窗口同时提供 CONTINUE WITH TRIAL 和 LOG IN：仅试用软件时可以继续试用；需要绑定已购买许可证时再登录。官方文档也说明试用模式不要求先注册账号。
安装或启动异常时，先完整阅读错误信息。尤其要区分以下问题：
- 安装程序没有权限；
- 网络、代理或防火墙阻止激活；
- 显卡/OpenGL 环境不满足要求；
- 项目版本与软件版本不兼容；
- 项目路径不存在、不可写或包含异常字符。
1.1.1 注册账号
视频中演示的入口需要纠正：
- 未登录时，许可窗口底部是
LOG IN，不是LOGOUT。 - 点击
LOG IN后进入登录页；没有账号时，再点击SIGN UP打开注册页面。 - 启动器右上角出现
LOGOUT，说明当前已经登录；点击它执行的是退出登录，并不是注册。
注册时通常需要填写姓名、邮箱和符合规则的密码，并确认必选的服务条款。课程所说的“所有开关都勾上”并不严谨：应只勾选必需条款，营销邮件等可选项按个人意愿选择。
课程画面中展示了共享账号信息，但学习笔记不应记录、传播或继续使用他人的账号和密码。应使用自己的账号，并为密码管理器生成的独立密码开启妥善保管。
需要注意：
- 试用模式与登录许可证是两条不同路径；只体验软件时不一定要注册。
- 购买许可证后，才需要登录并把许可证与当前计算机配对。
- 版本升级后许可界面可能变化，应以对应版本的官方文档为准。
- 如果只是离线打开已经激活的软件，通常不需要每次都联网；首次激活、许可证配对或在线更新仍可能需要网络。
1.1.2 软件的使用
SquareLine Studio 的基本工作方式是：在 PC 上新建项目，把控件放到 Screen 上，通过 Inspector 修改属性和样式，再用 Play mode 检查交互，最后导出 UI 文件。导出与嵌入式工程集成在下一课讲解。
课程使用英文界面。遇到不认识的选项时，可以使用截图翻译，但翻译结果只能用于辅助定位；Border、Outline、Align、State 等术语在 LVGL 中有明确含义，不能只按日常中文含义猜测。
1.1.2.1 工程的创建
一、按课程版本创建工程
- 启动 SquareLine Studio，在 Launcher 中选择
Create。Open用于打开已有工程，不能用来新建工程。 - 顶部选择 LVGL 主版本
8.3。 - 选择
Desktop分类下的 Eclipse with SDL for development on PC 模板，板级模板版本为v1.0.2。原笔记中的Adips是对Eclipse的误识别。 - 把项目命名为
19sql_test.spj，并先创建独立目录19sql_test，再把项目保存到该目录中。不要直接把项目文件散落在uint3code根目录。 - 按下表设置项目参数，然后点击
CREATE。
| 参数 | 本课设置 | 含义 |
|---|---|---|
| Resolution | 480 × 320 | 宽度为 480 像素，高度为 320 像素 |
| Rotation | 0 degree | 不在 SquareLine 工程中旋转画布 |
| Offset | 0, 0 | 不设置显示有效区偏移 |
| Shape | Rectangle | 矩形屏幕 |
| Color depth | 16 bit swap | 16 位 RGB565，并启用高低字节交换 |
| LVGL version | 8.3.11 | 与本课程移植的 LVGL 版本一致 |
| Theme | Light | 使用浅色默认主题 |
| Multilanguage | Disable | 本示例不启用多语言功能 |
配套 19sql_test 工程可核对出以下信息：SquareLine Studio 版本为 1.5.0、画布为 480×320、模板为 Eclipse with SDL for development on PC、LVGL 为 8.3.11、颜色深度为 16 位。这些都与视频设置一致。
二、为什么这三个参数必须一致
- 480×320 的顺序不能反：前者是宽，后者是高。写成 320×480 会把横屏工程变成竖屏坐标系，控件位置和触摸坐标都可能错位。
- 选择 16 bit swap：本课程 LVGL 配置为 16 位颜色，并启用了 RGB565 的两字节交换；SquareLine 生成的 UI 文件也会检查这两项配置。若 SquareLine 与固件配置不一致，可能编译报错，图片资源也可能出现颜色异常。
- 选择 LVGL 8.3.11：生成代码所使用的 API 必须与工程中的 LVGL 库匹配。不要因为启动器出现更高版本就随意切换，否则控件 API、生成文件结构或配置项可能不同。
Eclipse with SDL for development on PC 是一个 PC 端模板名称，并不表示 STM32 会运行 Eclipse。SDL 用于在 PC 上构建模拟器；本课程本节只是借该模板建立可视化 UI 工程，尚未构建 SDL 模拟器，也不需要为了本节单独安装 Eclipse。
三、编辑器各区域
| 区域 | 课程中的作用 |
|---|---|
| Screens | 管理当前项目中的屏幕 |
| Widgets | 提供 Arc、Button、Label、Checkbox、Keyboard、Slider 等控件 |
| Hierarchy | 以层级列表显示当前 Screen 及其全部子控件 |
| 中央画布 | 预览 480×320 屏幕并摆放控件 |
| Inspector | 修改选中控件的名称、位置、大小、样式、状态和事件 |
| Assets / Console | 管理图片、字体资源并查看工具输出信息 |
视频先把 Arc、Button 和 Label 从左侧 Widgets 面板拖到中央画布：
Arc是圆弧控件，可以显示或调整一定范围内的值；Button是按钮控件，按下时会产生状态和事件；Label用于显示文字，选中后可在 Inspector 的Text属性中修改内容。
课程口语中的“插件”“空间”均应理解为“控件（Widget）”。中央白色区域不是实际 LCD，而是与目标分辨率一致的设计画布。
四、名称、坐标、大小与对齐
选中 Button 后，Inspector 中最常用的是以下属性：
| 属性 | 作用 | 本课示例 |
|---|---|---|
| Name | 控件名称，并参与生成 C 变量名 | 视频输入 111 后显示为 Button111 |
| X / Y | 相对所选对齐锚点的偏移 | 0 / 0 |
| Width / Height | 控件宽度和高度 | 200 / 80 像素 |
| Align | 控件相对父对象的对齐锚点 | CENTER |
原笔记中的 Central 应为 CENTER，top made 应为 TOP MID。常见选项包括 TOP LEFT、TOP MID、TOP RIGHT 和 CENTER。
坐标不是永远相对于画布左上角。先选择 Align，再用 X/Y 表示相对该锚点的偏移：
CENTER且 X=0、Y=0：控件中心与父对象中心重合；- X 增大：向右偏移；X 减小：向左偏移；
- Y 增大：向下偏移；Y 减小：向上偏移；
- 如果控件还有父控件，位置和对齐以父控件为参照，不一定以整个 Screen 为参照。
控件名称会影响导出的变量名，因此应使用能表达用途的名称，例如 BtnConfirm、LabelTemperature，不要长期保留 Button1 或无意义的数字。名称还必须能转换为合法的 C 标识符，不能以数字或特殊字符开头；课程输入 111 后工具显示为 Button111，正是为了形成有效名称。
五、Style Settings 样式设置
在 Inspector 的 STYLE SETTINGS 中，可以为控件不同的部件和状态设置样式。课程对 Button 的 STYLE (MAIN) 做了以下演示：
- 展开
Background，勾选要覆盖的属性，然后修改背景颜色； - 启用
Gradient direction，选择水平或垂直渐变； - 展开
Outline，修改轮廓颜色与宽度； - 画布会立即显示修改结果。
SquareLine 属性前的复选框表示“为当前部件和状态显式设置该属性”。没有勾选时，控件通常继续使用主题或继承的默认样式。
课程中按钮从红色渐变到黑色，是因为只启用了渐变方向，而渐变终点颜色仍是默认值。要得到可控效果，应同时设置背景起始颜色、渐变颜色以及方向：
HOR：从左到右；VER：从上到下；- 未启用渐变方向时，只使用普通背景色。
Border 与 Outline 不是同一个属性：
Border是对象边框；Outline绘制在对象外侧，可以设置颜色、宽度和与对象的间距；- 视频中的绿色外圈实际是
Outline，配套生成代码记录的轮廓宽度为 6 像素。原笔记把它笼统称为“边框轮廓”不够准确。
同一区域还可设置 Background image、Shadow、圆角半径、透明度等。修改样式前应先确认当前编辑的是哪个 Part 和哪个 State，否则可能只改变按钮按下态而不是默认态，或只改变滑块旋钮而不是滑轨。
六、课程演示的其他控件
Keyboard：屏幕键盘。可以在画布上调整位置和大小；若要真正向文本框输入内容，还需要把它关联到Textarea。本课工程未关联目标文本框，因此这里只能预览按键状态。Calendar：日历控件。视频把它拖入后又删除，用于演示控件管理。Checkbox：复选框。选中后可通过Title属性把文字改为stm32、lvgl等内容。Slider：滑块。默认可在最小值和最大值之间拖动，后续还可通过事件读取或设置其数值。Label：只显示普通文本时优先使用 Label，不必把其他复杂控件当作文字使用。
删除控件时，在 Hierarchy 中选中目标控件，打开右侧的上下文菜单并选择 Delete。删除前先看清层级关系：删除父控件时，其子控件也可能一起被移除。
七、Play mode 交互预览
点击编辑区右上角的三角形 PLAY 按钮后，界面提示 Play mode active，此时可用鼠标模拟触摸操作：
- 按钮可显示按下、释放状态；
- Checkbox 可以勾选或取消；
- Arc 和 Slider 可以拖动；
- Keyboard 的按键可以被点击。
Play mode 是 SquareLine 编辑器内部的交互预览，不等于 STM32 仿真，也不等于硬件验证。它不能证明以下内容已经正确：
- LCD 显示驱动与触摸驱动；
- MCU RAM、Flash 和栈空间是否足够；
- SPI 刷新速度与实际帧率；
- 触摸坐标方向和校准参数；
- 生成代码能否在 Keil 工程中成功编译；
- 业务事件能否正确控制 LED、传感器等外设。
真正的验证仍需在下一步导出 UI 代码、加入 STM32 工程、调用初始化函数并烧录到开发板后完成。
八、本节完成标准与常见错误
完成本节后，应得到一个可重新打开的 19sql_test SquareLine 工程，并能在 480×320 画布上编辑控件、样式和预览交互。本节不要求导出 UI，也不要求改动 STM32 源码。
| 常见错误 | 后果或判断方法 |
|---|---|
把项目直接保存到 uint3code 根目录 | .spj、备份和资源文件散落，后续难以管理 |
| 把分辨率写成 320×480 | 横竖屏坐标系错误，控件布局与触摸位置不一致 |
选择 16 bit 而不是 16 bit swap | 与课程固件颜色配置不匹配，可能编译报错或显示颜色异常 |
| 选择与工程不同的 LVGL 版本 | 生成 API 和现有库不兼容 |
把 LOGOUT 当成注册入口 | 实际会退出已经登录的账号 |
| 只设置渐变方向，不设置渐变终点颜色 | 可能出现预期外的黑色渐变 |
| 把 Play mode 当成 MCU 仿真 | 无法发现真实硬件、内存、驱动和性能问题 |
| 使用无意义或非法的控件名称 | 导出后难以定位变量，甚至无法形成合法 C 标识符 |
官方资料核对：