截止2025年12月29日，平台支持的串口控制指令有：
| 编号 | 指令名 | 参数及结构 | 用法示例 | 说明 |
|---|---|---|---|---|
| 1 | page | [页面名/ID, 动画类型]\页面名字符串或ID数字，动画类型0\~5 |
{ "page": ["main", 1] }\{ "page": [0, 2] } |
动画类型：0无、1淡入、2左、3右、4上、5下 |
| 2 | rest | 整数（延时毫秒） |
{ "rest": 1000 } |
延时后重启 |
| 3 | dim | 整数/字符串/变量（0\~100） |
{ "dim": 80 }\{ "dim": "$brightness" } |
设置屏幕亮度，支持全局变量 |
| 4 | vol | 整数/字符串/变量（0\~100） |
{ "vol": 50 }\{ "vol": "$vol" } |
设置音量，内部映射0\~60 |
| 5 | baud | 整数（波特率） |
{ "baud": 115200 } | 设置串口波特率 |
| 6 | wifi_scan | on_success、on_error（回调对象） | { "wifi_scan": { "on_success": {...} } } | 扫描WiFi，回调为JSON对象或数组 |
| 7 | wifi | prop（ssid、pwd、force），on_success、on_error、on_disconnect_error（回调） |
{ "wifi": { "prop": { "ssid": "xxx", "pwd": "yyy" } } } |
force为1强制重连，支持变量，回调为JSON对象 |
| 8 | wifi_disconnect | on_success、on_error（回调对象） | { "wifi_disconnect": { "on_success": {...} } } | 断开WiFi，回调 |
| 9 | gpio | pin（字符串/变量），level（0/1） |
{ "gpio": { "pin": "2", "level": 1 } } |
控制GPIO高低电平 |
| 10 | gui | do（"start"/"stop"） |
{ "gui": { "do": "stop" } } |
控制LVGL刷新 |
| 11 | vplay | do（'r'播放/' '暂停/'q'停止），url（文件名），x，y，on_success，on_error |
{ "vplay": { "do": "r", "url": "video.avi", "x":0, "y":0 } } |
视频播放，支持回调 |
| 12 | aplay | do（'r'播放/' '暂停/'q'停止），url（文件名），vol，on_success，on_error |
{ "aplay": { "do": "r", "url": "music.mp3", "vol":30 } } |
音频播放，支持回调 |
| 13 | http | prop（url、sval），on_success、on_error（回调对象） |
{ "http": { "prop": { "url": "...", "sval": "$result" } }} |
HTTP请求，结果存入变量 |
| 14 | timer | name（定时器名），en（0暂停/1恢复） |
{ "timer": { "name": "tmr1", "en": 1 } } | 控制定时器 |
| 15 | log | en（0关闭/1开启） |
{ "log": { "en": 1 } } |
控制日志输出 |
| 16 | gval | name（变量名），val（赋值），add（拼接），addm（加法），subm（减法），cut（截取），等 |
{ "gval": { "name": "$score", "val": "100" } } |
全局变量操作，详见下方说明 |
| 17 | gval_save | key（NVS键），val（变量名） | { "gval_save": { "key": "score", "val": "$score" } } |
保存全局变量到NVS |
| 18 | gval_load | key（NVS键），val（变量名） | { "gval_load": { "key": "score", "val": "$score" } } |
从NVS加载全局变量 |
| 19 | gval_save_clear | true或1 |
{ "gval_save_clear": true } |
清除所有NVS全局变量 |
| 20 | jval | src（JSON变量），path（数组），dst（目标变量） | { "jval": { "src": "\$json", "path": ["data", "0", "name"], "dst": "\$name" }} | 按路径取JSON值存入变量 |
| 21 | jval_join | src（JSON变量），path（数组），keys（数组），dst，sep，line | { "jval_join": { ... } } |
拼接JSON数组多字段 |
| 22 | if | if1，if2，op（eq/ne/gt/lt/ge/le），true，false |
{ "if": { "if1": "$a", "if2": "b", "op": "eq", "true": {...} }} |
条件判断，分支为对象/数组/字符串 |
| 23 | case | value，cases（数组，每项含eq/default和do） |
{ "case": { ... } } |
多分支条件 |
| 24 | for | var（变量名），from，to，step，body |
{ "for": { "var": "$i", "from": "1", "to": "10", "step": "1", "body": {...} }} |
循环体 |
| 25 | create_btn | txt，color，x，y，event（对象，含type/action） |
{ "create_btn": { "txt": "OK", "color": "#FF0000", "x":10, "y":20 } } |
动态创建按钮，支持事件绑定 |
| 26 | fullscreen | color（背景色） | { "fullscreen": { "color": "#000000" } } |
创建全屏面板 |
| 27 | create_msgbox | txt，title，btns（逗号分隔），timeout，autoclose，btn_callbacks（数组） | { "create_msgbox": { ... } } |
创建消息框，支持按钮和回调 |
| 28 | call | 字符串（函数名） |
{ "call": "myfunc" } |
调用已注册C函数 |
| 29 | test | vis（0/1），txt | { "test": { "vis": 1, "txt": "hello" } } |
显示/隐藏测试面板 |
| 30 | gval_save_clear | true或1 |
{ "gval_save_clear": true } |
清除所有NVS全局变量 |
| 31 | pwm | io，duty，freq，res | { "pwm": { "io":2, "duty":128, "freq":1000, "res":8 } } |
设置PWM输出 |
| 32 | adc | io，dst | { "adc": { "io":1, "dst":"$adcVal" } } |
读取ADC值到变量 |
1. page（页面切换）
作用：切换到指定页面，可选动画效果，支持页面名或页面ID。
参数列表：
| 参数名 | 含义 | 示例值 | 是否可省略 | 说明 |
|---|---|---|---|---|
| 0 | 页面名/ID | "main"、0 | 否 | 字符串为页面名，数字为ID |
| 1 | 动画类型 | 0、1、2、3 | 是 | 0无动画，1淡入，2左，3右等 |
用法示例：
{ "page": ["main", 1] } { "page": [0, 2] }
2. rest（延时重启）
作用：延时指定毫秒后重启设备。
参数列表：
| 参数名 | 含义 | 示例值 | 是否可省略 | 说明 |
|---|---|---|---|---|
| rest | 延时(ms) | 1000 | 否 | 必须为整数 |
用法示例：
{ "rest": 1000 }
3. dim（屏幕亮度）
作用：设置屏幕背光亮度，支持变量。
参数列表：
| 参数名 | 含义 | 示例值 | 是否可省略 | 说明 |
|---|---|---|---|---|
| dim | 亮度0\~100 | 80、"\$b" | 否 | 超出范围自动裁剪 |
用法示例：
{ "dim": 80 } { "dim": "$brightness" }
4. vol（音量设置）
作用：设置音频输出音量，支持变量。
参数列表：
| 参数名 | 含义 | 示例值 | 是否可省略 | 说明 |
|---|---|---|---|---|
| vol | 音量0\~100 | 50、"\$v" | 否 | 内部映射到0\~60 |
用法示例：
{ "vol": 50 } { "vol": "$vol" }
5. baud（串口波特率）
作用：设置串口波特率，立即生效。
参数列表：
| 参数名 | 含义 | 示例值 | 是否可省略 | 说明 |
|---|---|---|---|---|
| baud | 波特率 | 115200 | 否 | 必须为整数 |
用法示例：
{ "baud": 115200 }
6. wifi_scan（WiFi扫描）
作用：扫描WiFi，结果通过回调返回。
参数列表：
| 参数名 | 含义 | 示例值 | 是否可省略 | 说明 |
|---|---|---|---|---|
| on_success | 成功回调 | {...} | 是 | JSON对象 |
| on_error | 失败回调 | {...} | 是 | JSON对象 |
用法示例：
{ "wifi_scan": { "on_success": { ... }, "on_error": { ... } } }
7. wifi（WiFi连接）
作用：连接指定WiFi，支持回调和强制重连。
参数列表：
| 参数名 | 含义 | 示例值 | 是否可省略 | 说明 |
|---|---|---|---|---|
| prop.ssid | WiFi名称 | "mywifi" | 否 | 支持变量 |
| prop.pwd | WiFi密码 | "12345678" | 否 | 支持变量 |
| prop.force | 强制重连 | 1 | 是 | 0/1，默认0 |
| on_success | 成功回调 | {...} | 是 | JSON对象 |
| on_error | 失败回调 | {...} | 是 | JSON对象 |
| on_disconnect_error | 断线回调 | {...} | 是 | JSON对象 |
用法示例：
{ "wifi": { "prop": { "ssid": "mywifi", "pwd": "12345678" }, "on_success": { ... } } }
8. wifi_disconnect（WiFi断开）
作用：断开WiFi连接，支持回调。
参数列表：
| 参数名 | 含义 | 示例值 | 是否可省略 | 说明 |
|---|---|---|---|---|
| on_success | 成功回调 | {...} | 是 | JSON对象 |
| on_error | 失败回调 | {...} | 是 | JSON对象 |
用法示例：
{ "wifi_disconnect": { "on_success": { ... } } }
9. gpio（GPIO控制）
作用：设置GPIO引脚高低电平。
参数列表：
| 参数名 | 含义 | 示例值 | 是否可省略 | 说明 |
|---|---|---|---|---|
| pin | 引脚号 | "2" | 否 | 字符串/变量 |
| level | 电平 | 0/1 | 否 | 0低，1高 |
用法示例：
{ "gpio": { "pin": "2", "level": 1 } }
10. gui（LVGL刷新控制）
作用：启用或禁用LVGL屏幕刷新。
参数列表：
| 参数名 | 含义 | 示例值 | 是否可省略 | 说明 |
|---|---|---|---|---|
| do | 操作 | "start"/"stop" | 否 | 启用/禁用 |
用法示例：
{ "gui": { "do": "stop" } } { "gui": { "do": "start" } }
11. vplay（视频播放）
作用：控制视频播放、暂停、停止，支持回调。
参数列表：
| 参数名 | 含义 | 示例值 | 是否可省略 | 说明 |
|---|---|---|---|---|
| do | 操作 | "r"/" "/"q" | 否 | r播放，空格暂停/继续，q停止 |
| url | 文件名 | "video.avi" | 否(r时) | 视频文件名 |
| x | 播放x坐标 | 0 | 是 | 默认0 |
| y | 播放y坐标 | 0 | 是 | 默认0 |
| on_success | 成功回调 | {...} | 是 | JSON对象 |
| on_error | 失败回调 | {...} | 是 | JSON对象 |
用法示例：
{ "vplay": { "do": "r", "url": "video.avi", "x": 0, "y": 0 } }
12. aplay（音频播放）
作用：控制音频播放、暂停、停止，支持回调。
参数列表：
| 参数名 | 含义 | 示例值 | 是否可省略 | 说明 |
|---|---|---|---|---|
| do | 操作 | "r"/" "/"q" | 否 | r播放，空格暂停/继续，q停止 |
| url | 文件名 | "music.mp3" | 否(r时) | 音频文件名 |
| vol | 音量 | 30 | 是 | 0\~100 |
| on_success | 成功回调 | {...} | 是 | JSON对象 |
| on_error | 失败回调 | {...} | 是 | JSON对象 |
用法示例：
{ "aplay": { "do": "r", "url": "music.mp3", "vol": 30 } }
13. http（HTTP请求）
作用：发起HTTP请求，结果存入变量，支持回调。
参数列表：
| 参数名 | 含义 | 示例值 | 是否可省略 | 说明 |
|---|---|---|---|---|
| prop.url | 请求URL | "http\://..." | 否 | 支持变量 |
| prop.sval | 结果变量名 | "\$result" | 否 | |
| on_success | 成功回调 | {...} | 是 | JSON对象 |
| on_error | 失败回调 | {...} | 是 | JSON对象 |
用法示例：
{ "http": { "prop": { "url": "http://api", "sval": "$result" }, "on_success": { ... } } }
14. timer（定时器控制）
作用：暂停或恢复指定定时器。
参数列表：
| 参数名 | 含义 | 示例值 | 是否可省略 | 说明 |
|---|---|---|---|---|
| name | 定时器名 | "tmr1" | 否 | 字符串/变量 |
| en | 使能 | 0/1 | 否 | 0暂停，1恢复 |
用法示例：
{ "timer": { "name": "tmr1", "en": 1 } }
15. log（日志开关）
作用：打开或关闭日志输出。
参数列表：
| 参数名 | 含义 | 示例值 | 是否可省略 | 说明 |
|---|---|---|---|---|
| en | 使能 | 0/1 | 否 | 0关闭，1开启 |
用法示例：
{ "log": { "en": 1 } }
16. gval（全局变量操作）
作用：全局变量赋值、加减、拼接、分割、截取、四舍五入等。
参数列表（常用）：
| 参数名 | 含义 | 示例值 | 是否可省略 | 说明 |
|---|---|---|---|---|
| name | 变量名 | "\$score" | 否 | 必须 |
| val | 赋值 | "100" | 选填 | 字符串/变量 |
| add | 拼接 | "abc" | 选填 | 字符串/变量 |
| addm | 数值加法 | "1" | 选填 | 字符串/变量 |
| subm | 数值减法 | "1" | 选填 | 字符串/变量 |
| cut | 截取 | [1,3] | 选填 | 数组 |
| dst | 目标变量名 | "\$out" | 选填 | 字符串/变量 |
| sep | 分隔符 | "," | 选填 | 字符串 |
| idx | 分割下标 | 2 | 选填 | 数字/变量 |
| round | 四舍五入 | true | 选填 | 布尔 |
| d | 保留位数 | 2 | 选填 | 数字 |
| op | 操作类型 | "add"/"sub" | 选填 | 新写法 |
用法示例：
{ "gval": { "name": "$score", "val": "100" } } { "gval": { "name": "$score", "addm": "1" } } { "gval": { "name": "$str", "add": "abc" } } { "gval": { "name": "$str", "cut": [1,3], "dst": "$out" } } { "gval": { "name": "$str", "sep": ",", "idx": 2, "dst": "$out" } } { "gval": { "name": "$num", "round": true, "d": 2, "dst": "$out" } }
17. gval_save（全局变量保存到NVS）
作用：保存全局变量到NVS（掉电不丢失）。
参数列表：
| 参数名 | 含义 | 示例值 | 是否可省略 | 说明 |
|---|---|---|---|---|
| key | NVS键名 | "score" | 否 | 字符串/变量 |
| val | 变量名 | "\$score" | 否 | 字符串/变量 |
用法示例：
{ "gval_save": { "key": "score", "val": "$score" } }
18. gval_load（NVS加载全局变量）
作用：从NVS加载全局变量到内存。
参数列表：
| 参数名 | 含义 | 示例值 | 是否可省略 | 说明 |
|---|---|---|---|---|
| key | NVS键名 | "score" | 否 | 字符串/变量 |
| val | 变量名 | "\$score" | 否 | 字符串/变量 |
用法示例：
{ "gval_load": { "key": "score", "val": "$score" } }
19. gval_save_clear（清空NVS全局变量）
作用：清除所有NVS保存的全局变量。
参数列表：
| 参数名 | 含义 | 示例值 | 是否可省略 | 说明 |
|---|---|---|---|---|
| gval_save_clear | 清空标志 | true/1 | 否 | 必须为true或1 |
用法示例：
{ "gval_save_clear": true }
20. jval（JSON变量取值）
作用：按路径从JSON变量中取值，存入目标变量。
参数列表：
| 参数名 | 含义 | 示例值 | 是否可省略 | 说明 |
|---|---|---|---|---|
| src | 源变量名 | "\$json" | 否 | 字符串/变量 |
| path | 路径数组 | ["data", "0", "name"] | 否 | 数组 |
| dst | 目标变量名 | "\$name" | 否 | 字符串/变量 |
用法示例：
{ "jval": { "src": "$json", "path": ["data", "0", "name"], "dst": "$name" } }
21. jval_join（JSON数组拼接）
作用：拼接JSON数组的多个字段，结果存入目标变量。
参数列表：
| 参数名 | 含义 | 示例值 | 是否可省略 | 说明 |
|---|---|---|---|---|
| src | 源变量名 | "\$json" | 否 | 字符串/变量 |
| path | 路径数组 | ["data"] | 否 | 数组 |
| keys | 字段名数组 | ["name", "score"] | 否 | 数组 |
| dst | 目标变量名 | "\$out" | 否 | 字符串/变量 |
| sep | 字段分隔符 | ", " | 是 | 默认", " |
| line | 行分隔符 | "\n" | 是 | 默认"\n" |
用法示例：
{ "jval_join": { "src": "$json", "path": ["data"], "keys": ["name", "score"], "dst": "$out" } }
22. if（条件判断）
作用：条件判断，支持多种比较，分支内容可为任意指令。
参数列表：
| 参数名 | 含义 | 示例值 | 是否可省略 | 说明 |
|---|---|---|---|---|
| if1 | 左值 | "\$score" | 否 | 字符串/变量 |
| if2 | 右值 | "100" | 否 | 字符串/变量 |
| op | 操作符 | "eq"/"gt" | 是 | 默认"eq" |
| true | 成立分支 | {...} | 否 | 任意指令 |
| false | 不成立分支 | {...} | 否 | 任意指令 |
用法示例：
{ "if": { "if1": "$score", "if2": "100", "op": "ge", "true": { ... }, "false": { ... } } }
23. case（多分支条件）
作用：多分支条件判断，支持default分支。
参数列表：
| 参数名 | 含义 | 示例值 | 是否可省略 | 说明 |
|---|---|---|---|---|
| value | 比较值 | "\$state" | 否 | 字符串/变量 |
| cases | 分支数组 | [{...}, ...] | 否 | 每项含eq/do或default/do |
用法示例：
{ "case": { "value": "$state", "cases": [ { "eq": "ok", "do": {...} }, { "default": true, "do": {...} } ] } }
24. for（循环体）
作用：按指定范围和步长循环执行body内容。
参数列表：
| 参数名 | 含义 | 示例值 | 是否可省略 | 说明 |
|---|---|---|---|---|
| var | 循环变量名 | "\$i" | 否 | 字符串/变量 |
| from | 起始值 | "1" | 否 | 字符串/变量 |
| to | 结束值 | "10" | 否 | 字符串/变量 |
| step | 步长 | "1" | 是 | 默认1 |
| body | 循环体 | {...} | 否 | 任意指令 |
用法示例：
{ "for": { "var": "$i", "from": "1", "to": "10", "step": "1", "body": { ... } } }
25. create_btn（动态按钮创建）
作用：动态创建按钮，支持事件绑定。
参数列表：
| 参数名 | 含义 | 示例值 | 是否可省略 | 说明 |
|---|---|---|---|---|
| txt | 按钮文本 | "OK" | 否 | 字符串/变量 |
| color | 文本颜色 | "#FF0000" | 是 | 默认白色 |
| x | x坐标 | 10 | 是 | 默认0 |
| y | y坐标 | 20 | 是 | 默认0 |
| event | 事件对象 | {...} | 是 | type/action |
用法示例：
{ "create_btn": { "txt": "OK", "color": "#FF0000", "x": 10, "y": 20 } }
26. fullscreen（全屏面板）
作用：创建全屏面板，覆盖所有内容。
参数列表：
| 参数名 | 含义 | 示例值 | 是否可省略 | 说明 |
|---|---|---|---|---|
| color | 背景色 | "#000000" | 是 | 默认黑色 |
用法示例：
{ "fullscreen": { "color": "#000000" } }
27. create_msgbox（消息框）
作用：创建消息框，支持多按钮、超时关闭、按钮回调。
参数列表：
| 参数名 | 含义 | 示例值 | 是否可省略 | 说明 |
|---|---|---|---|---|
| txt | 主文本 | "Hello" | 否 | 字符串/变量 |
| title | 标题 | "提示" | 是 | 字符串/变量 |
| btns | 按钮文本 | "OK,Cancel" | 是 | 逗号分隔 |
| timeout | 自动关闭时间 | 3000 | 是 | 毫秒 |
| autoclose | 自动关闭 | 1 | 是 | 0/1 |
| btn_callbacks | 按钮回调 | [{...}, ...] | 是 | 数组 |
用法示例：
{ "create_msgbox": { "txt": "Hello", "btns": "OK,Cancel", "timeout": 3000 } }
28. call（注册函数调用）
作用：调用已注册的C函数。
参数列表：
| 参数名 | 含义 | 示例值 | 是否可省略 | 说明 |
|---|---|---|---|---|
| call | 函数名 | "myfunc" | 否 | 字符串 |
用法示例：
{ "call": "myfunc" }
29. test（测试面板）
作用：显示或隐藏测试面板，可自定义文本。
参数列表：
| 参数名 | 含义 | 示例值 | 是否可省略 | 说明 |
|---|---|---|---|---|
| vis | 显示/隐藏 | 1/0 | 否 | 1显示，0隐藏 |
| txt | 显示文本 | "hello" | 是 | 字符串/变量 |
用法示例：
{ "test": { "vis": 1, "txt": "hello" } }
30. pwm（PWM输出）
作用：设置指定引脚的PWM输出。
参数列表：
| 参数名 | 含义 | 示例值 | 是否可省略 | 说明 |
|---|---|---|---|---|
| io | 引脚号 | 2 | 否 | 整数/变量 |
| duty | 占空比 | 128 | 否 | 整数/变量 |
| freq | 频率 | 1000 | 否 | 整数/变量 |
| res | 分辨率 | 8 | 否 | 整数/变量 |
用法示例：
{ "pwm": { "io": 2, "duty": 128, "freq": 1000, "res": 8 } }
31. adc（ADC读取）
作用：读取指定引脚的ADC值，存入变量。
参数列表：
| 参数名 | 含义 | 示例值 | 是否可省略 | 说明 |
|---|---|---|---|---|
| io | ADC引脚号 | 1 | 否 | 整数/变量 |
| dst | 目标变量名 | "\$adcVal" | 否 | 字符串/变量 |
用法示例：
{ "adc": { "io": 1, "dst": "$adcVal" } }
32. gval_save_clear（清空NVS全局变量）
作用：清除所有NVS保存的全局变量（与第19条一致，兼容多写法）。
参数列表：
| 参数名 | 含义 | 示例值 | 是否可省略 | 说明 |
|---|---|---|---|---|
| gval_save_clear | 清空标志 | true/1 | 否 | 必须为true或1 |
用法示例：
{ "gval_save_clear": true }
通用说明：
所有参数均支持全局变量（以
$开头）。回调参数内容为JSON对象或数组，支持嵌套指令。
GUI设置指令是指通过JSON格式的命令，对界面上的控件（如按钮、标签、滑块等）进行属性设置和外观调整的操作方式。这类指令通常用于动态修改界面元素的文本、颜色、位置、大小、可见性等属性，实现界面内容的实时更新和交互。
使用GUI设置指令时，开发者只需在JSON对象中指定目标控件的标识（如id或name），并在prop字段中列出需要设置的属性及其对应的值。属性值既可以是直接的数字或字符串，也可以引用全局变量（以$$开头），从而实现数据与界面的联动。
例如，要设置一个按钮的文本和颜色，可以发送如下指令：
{
"id": "btn1",
"prop": {
"txt": "确定",
"color": "#FF0000"
}
}
如果要让文本内容动态跟随全局变量的变化，可以这样写：
{
"id": "btn1",
"prop": {
"txt": "$g1"
}
}
GUI设置指令支持同时设置多个属性，未指定的属性保持原值不变。控件类型不同，支持的属性也有所区别，常见的如文本、颜色、坐标、宽高、可见性、圆角、字体等。部分控件还支持特有属性，如图片控件的图片索引、滑块的当前值等。
通过这种方式，开发者可以灵活地在运行时调整界面，实现丰富的交互和动态效果，无需重新编译或重启设备。GUI设置指令是物联网、嵌入式等场景下实现低耦合、高灵活性界面控制的重要手段。
LVGL控件属性设置
一、通用属性（大多数控件均支持）
| 属性名 | 说明 | 值类型 | 是否支持全局变量 | 是否可缺省 | 用法示例 |
|---|---|---|---|---|---|
| txt | 文本内容 | 字符串 | 支持 | 可缺省 | "txt": "hello" 或 "txt": "$g1" |
| color | 文本颜色 | 颜色字符串 | 支持 | 可缺省 | "color": "#FF0000" 或 "color": "$g2" |
| bgcolor | 背景色 | 颜色字符串 | 支持 | 可缺省 | "bgcolor": "#00FF00" |
| bgopa | 背景透明度 | 数字(0\~255) | 支持 | 可缺省 | "bgopa": 128 |
| opa | 透明度 | 数字(0\~255) | 支持 | 可缺省 | "opa": 200 |
| xcen | 文本对齐 | 数字(0左/1中/2右) | 支持 | 可缺省 | "xcen": 1 |
| x | X坐标 | 数字 | 支持 | 可缺省 | "x": 10 |
| y | Y坐标 | 数字 | 支持 | 可缺省 | "y": 20 |
| w | 宽度 | 数字 | 支持 | 可缺省 | "w": 100 |
| h | 高度 | 数字 | 支持 | 可缺省 | "h": 40 |
| vis | 显示/隐藏 | 数字(0/1) | 支持 | 可缺省 | "vis": 1 |
| rad | 圆角半径 | 数字 | 支持 | 可缺省 | "rad": 8 |
| font | 字体索引 | 数字 | 支持 | 可缺省 | "font": 0 |
注意事项：
所有属性均可用全局变量（如
"$g1"），会自动读取变量内容。未设置的属性保持原值不变。
颜色字符串需为
#RRGGBB格式或全局变量。字体索引需在已加载字体范围内。
二、按钮（lv_btn_class）
支持属性：txt, color, opa, font, xcen, x, y, w, h, vis, rad
说明：
txt、color、opa、font实际设置到按钮内的 label 子控件。其它属性设置到按钮本体。
用法示例：
{ "prop": { "txt": "确定", "color": "#FF0000", "font": 1, "x": 50, "y": 100, "w": 120, "h": 40, "vis": 1 } }
注意事项：
按钮文本需通过 label 子控件设置。
字体索引超出范围无效。
三、标签（lv_label_class）
支持属性：txt, color, opa, font, xcen, x, y, w, h, vis, rad
说明：直接设置文本和样式。
用法示例：
{ "prop": { "txt": "$g1", "color": "#0000FF", "font": 2, "xcen": 1 } }
注意事项：
文本内容可为普通字符串或全局变量。
颜色和字体需在有效范围内。
四、下拉框（lv_dropdown_class）
支持属性：txt, val, color, x, y, w, h, vis, rad
说明：
txt：设置选项内容（多行字符串，每行一个选项）。val：设置当前选中项索引（从0开始）。
用法示例：
{ "prop": { "txt": "选项1\n选项2\n选项3", "val": 1 } }
注意事项：
txt内容每行一个选项，\n分隔。val超出选项数时无效。
五、复选框（lv_checkbox_class）
支持属性：txt, val, color, x, y, w, h, vis, rad
说明：
txt：复选框文本。val：0未选中，1选中。
用法示例：
{ "prop": { "txt": "同意协议", "val": 1 } }
注意事项：
val仅支持0/1。
六、开关（lv_switch_class）
支持属性：color, val, x, y, w, h, vis, rad
说明：
color：选中时指示颜色。val：0关闭，1打开。
用法示例：
{ "prop": { "color": "#00FF00", "val": 1 } }
注意事项：
仅支持设置选中时颜色。
七、滑块（lv_slider_class）
支持属性：color, val, x, y, w, h, vis, rad
说明：
color：指示条颜色。val：当前值。
用法示例：
{ "prop": { "color": "#FF8800", "val": 50 } }
注意事项：
val需在滑块范围内。
八、进度条（lv_bar_class）
支持属性：val, x, y, w, h, vis, rad
说明：
val：当前进度值。
用法示例：
{ "prop": { "val": 75 } }
注意事项：
val需在进度条范围内。
九、弧形（lv_arc_class）
支持属性：color, bgcolor, w, h, val, x, y, vis, rad
说明：
color：指示弧颜色。bgcolor：背景弧颜色。w：弧宽。h：弧半径（自动*2为直径）。val：当前值。
用法示例：
{ "prop": { "color": "#FF0000", "bgcolor": "#CCCCCC", "w": 10, "h": 60, "val": 30 } }
注意事项：
h为半径，实际控件大小为h*2。
十、图片（lv_img_class）
支持属性：pic, x, y, w, h, vis, rad
说明：
pic：图片索引（数字或全局变量）。
用法示例：
{ "prop": { "pic": 2 } }
注意事项：
图片索引需在已加载图片范围内。
十一、图片按钮（lv_imgbtn_class）
支持属性：pic, pic2, x, y, w, h, vis, rad
说明：
pic：未按下图片索引。pic2：按下图片索引。
用法示例：
{ "prop": { "pic": 1, "pic2": 2 } }
注意事项：
索引超出范围无效。
十二、文本框（lv_textarea_class）
支持属性：txt, color, x, y, w, h, vis, rad
说明：
txt：文本内容。
用法示例：
{ "prop": { "txt": "请输入内容" } }
注意事项：
文本内容可为全局变量。
十三、二维码（lv_qrcode_class）
支持属性：txt, x, y, w, h, vis, rad
说明：
txt：二维码内容。
用法示例：
{ "prop": { "txt": "https://www.example.com" } }
注意事项：
内容过长可能导致二维码无法显示。
属性值来源说明
普通值：直接写数字或字符串，如
"txt": "hello"，"color": "#FF0000"。全局变量：以
$$开头，如"txt": "$g1"，会自动读取全局变量内容。类型自动识别：支持数字、字符串、颜色字符串，自动转换。
参数缺省说明
所有属性均为可选，未设置则保持控件原有属性不变。
某些控件如图片、按钮等，部分属性（如
pic）未设置时不改变图片。
设置方法
通过 JSON 指令
"prop"字段设置属性，例如：{ "id": "btn1", "prop": { "txt": "$g1", "color": "#00FF00", "x": 10, "y": 20 } }
支持同时设置多个属性，支持全局变量动态赋值。
支持通过
"get"字段获取属性值到全局变量。
注意事项
全局变量：属性值为全局变量时，需确保变量已被赋值，否则控件属性可能为空或为0。
颜色格式：颜色字符串必须为
#RRGGBB格式，或全局变量内容为此格式。字体索引：需在已加载字体数组范围内，否则设置无效。
图片索引：需在图片数组范围内，否则设置无效。
属性未设置：未设置的属性保持原值不变，不会被清空或重置。
类型自动识别：支持数字、字符串、全局变量，自动转换为目标类型。
控件类型判断：属性设置时会自动判断控件类型，调用对应 LVGL API。
属性获取指令用于读取指定LVGL控件的属性值，并将结果写入全局变量。它支持所有属性设置指令能操作的属性类型，包括文本、颜色、坐标、尺寸、可见性、圆角、字体、选中状态、图片索引等。获取到的属性值会自动转换为字符串格式，便于后续在其它指令或界面中使用。
使用方法如下：在JSON对象的 get 字段中，指定需要获取的属性及目标全局变量名。例如：
{
"id": "btn1",
"get": {
"txt": "$g1",
"color": "$g2",
"x": "$g3"
}
}
上述指令会将按钮 btn1 的文本内容写入 $g1，文本颜色写入 $g2，X坐标写入 $g3。所有属性均支持写入全局变量（变量名以 $$ 开头），数值类型会自动转为字符串。
属性获取支持的类型包括：
文本内容（txt）
文本颜色（color）
背景色（bgcolor）
背景透明度（bgopa）
透明度（opa）
文本对齐（xcen）
坐标（x, y）
尺寸（w, h）
可见性（vis）
圆角半径（rad）
字体索引（font）
控件值（val，如选中项、滑块值、进度条值等）
图片索引（pic, pic2）
注意事项：
目标变量必须为全局变量（以$开头）。
获取到的值均为字符串格式，便于在其它指令中引用。
支持所有控件类型，属性获取会自动适配控件类型和属性。
未指定的属性不会被获取。
若控件类型或属性不支持，目标变量内容可能为空或为默认值。
通过属性获取指令，可以实现界面与数据的双向绑定，便于动态交互和数据流转。
以下为属性获取指令（get）API文档，结合实际代码实现，详细介绍每类LVGL控件可获取的属性、返回值类型、目标变量要求、用法、注意事项及扩展说明。内容涵盖控件类型、属性支持、数据流转、典型场景、错误处理等，适合开发者查阅和深入理解。
属性获取指令（get）API文档
一、属性获取指令的作用与基本用法
属性获取指令用于读取指定LVGL控件的属性值，并将结果写入全局变量。这使得界面状态可以被脚本、流程或其它指令动态感知，实现数据与界面的双向绑定、状态同步和复杂交互逻辑。
属性获取指令的典型JSON格式如下：
{
"id": "btn1",
"get": {
"txt": "$g1",
"color": "$g2",
"x": "$g3"
}
}
上述指令会将按钮 btn1 的文本内容写入全局变量 $g1，文本颜色写入 $g2，X坐标写入 $g3。所有获取到的值均为字符串格式，便于后续在其它指令或界面中使用。
目标变量必须为全局变量（以
$$开头）。支持同时获取多个属性，每个属性单独指定目标变量。
支持所有设置指令支持的属性类型，包括文本、颜色、坐标、尺寸、可见性、圆角、字体、选中状态、图片索引等。
二、各类控件可获取的属性及返回值类型
1. 通用属性（大多数控件均支持）
| 属性名 | 说明 | 返回值类型 | 备注/说明 |
|---|---|---|---|
| txt | 文本内容 | 字符串 | 按钮、标签、下拉框、复选框、文本框、二维码等均支持 |
| color | 文本颜色 | #RRGGBB字符串 | 统一为6位16进制 |
| bgcolor | 背景色 | #RRGGBB字符串 | |
| bgopa | 背景透明度 | 字符串数字 | 0\~255 |
| opa | 透明度 | 字符串数字 | 0\~255 |
| xcen | 文本对齐 | 字符串数字 | 0左/1中/2右 |
| x | X坐标 | 字符串数字 | |
| y | Y坐标 | 字符串数字 | |
| w | 宽度 | 字符串数字 | |
| h | 高度 | 字符串数字 | |
| vis | 可见性 | 字符串数字 | 0隐藏/1显示 |
| rad | 圆角半径 | 字符串数字 | |
| font | 字体索引 | 字符串数字 |
2. 特定控件属性
| 控件类型 | 可获取属性（属性名） | 说明/返回值类型（均为字符串） |
|---|---|---|
| 按钮（lv_btn） | txt, color, opa, font, xcen, x, y, w, h, vis, rad | txt为按钮内label文本 |
| 标签（lv_label） | txt, color, opa, font, xcen, x, y, w, h, vis, rad | 文本、颜色等 |
| 下拉框（lv_dropdown） | txt, val, color, x, y, w, h, vis, rad | txt为当前选中项文本，val为选中项索引 |
| 复选框（lv_checkbox） | txt, val, color, x, y, w, h, vis, rad | val为选中状态（0/1） |
| 开关（lv_switch） | val, color, x, y, w, h, vis, rad | val为开关状态（0/1） |
| 滑块（lv_slider） | val, color, x, y, w, h, vis, rad | val为当前值 |
| 进度条（lv_bar） | val, x, y, w, h, vis, rad | val为当前进度值 |
| 弧形（lv_arc） | val, color, bgcolor, w, h, x, y, vis, rad | val为当前值，color为指示弧色，bgcolor为背景弧色 |
| 图片（lv_img） | pic, x, y, w, h, vis, rad | pic为图片索引（如有实现） |
| 图片按钮（lv_imgbtn） | pic, pic2, x, y, w, h, vis, rad | pic/pic2为图片索引（如有实现） |
| 文本框（lv_textarea） | txt, color, x, y, w, h, vis, rad | txt为内容 |
| 二维码（lv_qrcode） | txt, x, y, w, h, vis, rad | txt为二维码内容 |
三、返回值类型与格式
所有获取到的值均为字符串，即使原本为数字（如坐标、宽高、索引等），也会自动转为字符串写入全局变量。
颜色值统一为
#RRGGBB格式字符串。状态、索引等数值均为字符串数字（如
"1"、"0"、"42"）。文本内容为UTF-8字符串，支持中英文及特殊字符。
四、目标变量要求
必须为全局变量，变量名以
$$开头，如$g1、$slider_val。变量类型自动匹配，无需手动指定类型，系统自动根据变量名查找对应变量池（普通/大容量/超大容量）。
变量内容超长时自动截断到最大长度（普通256字节，大容量1024字节，超大4095字节）。
五、典型用法举例
1. 获取标签文本和颜色
{
"id": "label1",
"get": {
"txt": "$g1",
"color": "$g2"
}
}
作用：将
label1的文本内容写入$g1，文本颜色写入$g2。
2. 获取滑块当前值
{
"id": "slider1",
"get": {
"val": "$slider_val"
}
}
作用：将滑块
slider1的当前值写入$slider_val。
3. 获取复选框选中状态和文本
{
"id": "cb1",
"get": {
"val": "$cb_state",
"txt": "$cb_text"
}
}
作用：将复选框
cb1的选中状态写入$cb_state，文本内容写入$cb_text。
4. 获取图片控件的图片索引
{
"id": "img1",
"get": {
"pic": "$img_idx"
}
}
作用：将图片控件
img1的图片索引写入$img_idx（如有实现）。
六、注意事项与错误处理
目标变量必须为全局变量，否则不会写入。
属性名必须为字符串，如
"txt": "$g1"。未实现的属性或控件类型，目标变量内容可能为空或为默认值。
获取到的值为控件当前状态，如文本内容、选中状态、坐标等。
部分控件的图片索引等特殊属性，需根据实际实现支持。
获取属性不会影响控件本身状态，仅做数据读取。
支持一次获取多个属性，每个属性单独指定目标全局变量。
属性获取指令可与属性设置指令配合使用，实现界面与数据的双向绑定和动态交互。
如目标变量超长，内容会被自动截断，请根据实际需求选择合适变量池。
属性获取时会自动判断控件类型，调用对应 LVGL API，如类型不匹配则返回空或默认值。
七、扩展说明与高级用法
1. 动态数据流转
通过属性获取指令，可以将界面控件的状态实时同步到全局变量，再通过其它指令（如gval、if、case等）进行逻辑判断、流程控制或界面反馈，实现复杂的交互和自动化。
2. 与属性设置指令联动
属性获取与设置指令可配合使用，实现“读-改-写”闭环。例如，先读取滑块值到变量，再根据变量调整其它控件属性，实现联动效果。
3. 支持流程控制与条件判断
获取到的属性值可用于if、case、for等流程控制指令，实现条件分支、循环等高级逻辑。例如，根据按钮文本内容决定后续操作。
4. 支持全局变量引用
属性获取结果可作为其它指令的输入，实现数据在指令间流转。例如，获取文本框内容后用于HTTP请求参数、页面跳转、消息框显示等。
5. 错误处理与调试
若属性名或目标变量名错误，日志会有详细提示。
若控件类型不支持某属性，目标变量内容为空或为默认值。
可通过日志输出（如
log_fmt）辅助调试和问题定位。
八、常见问题解答
Q1：为什么获取到的值是字符串？
A1：为便于变量统一管理和跨指令流转，所有属性值均以字符串形式写入全局变量。需要数值时可用atoi、atof等转换。
Q2：如何获取图片控件的图片索引？
A2：如有实现图片索引的获取方法，可通过pic属性获取，否则返回默认值。
Q3：能否一次获取多个属性？
A3：支持。get字段可同时指定多个属性，每个属性单独指定目标变量。
Q4：获取属性会影响控件状态吗？ A4：不会。属性获取仅做数据读取，不会修改控件本身状态。
Q5：目标变量内容超长会怎样？ A5：内容会被自动截断到变量池最大长度，建议根据实际需求选择合适变量池（普通/大容量/超大容量）。