菜单

STTSpinner使用手册

下载

STTSpinner.h 使用手册

STTSpinner 是持续旋转的圆弧加载/转速指示控件，可固定速度旋转，也可按绑定变量映射转速和方向。

1. 创建

cpp 复制代码 
#include "widgets/STTSpinner.h"

using namespace stt;

STTSpinner* spinner = new STTSpinner(getRuntime(), parent, "spinnerMotor");
spinner->setMainArg(
    20, 20, 100, 100,
    2000, // 每圈毫秒
    60,   // 指示弧角度
    true  // 顺时针
);

2. 样式

cpp 复制代码 
spinner->setMainStyle(16, 0xdddddd, nullptr);
spinner->setIndicStyle(16, 0x1687d9, nullptr);

setMainStyle 配置背景圆环，背景本身会设为透明；setIndicStyle 配置旋转圆弧并强制圆头。img 是 LVGL 图片源指针，必须保持有效。

3. 动画控制

cpp 复制代码 
void setAnim(
    int angle = 60,
    int time = 2000,
    bool clockwise = true,
    int repeat = -1,
    int startangle = 0
);
cpp 复制代码 
spinner->setAnim(90, 1200, true, -1, 0);

参数：

参数 说明
angle 指示弧长度，建议 1..360
time 转一圈耗时，毫秒
clockwise true 顺时针，false 逆时针
repeat -1 无限，0 不重复，大于 0 为重复次数
startangle 起始角，用于停止后继续

setAnim 会先删除该 object 上匹配的动画，再分别启动终点角和起点角两个动画。time、angle 没有范围校验，不要传 0、负数或极端值。

停止和恢复：

cpp 复制代码 
int angle = spinner->getCurrentAngle();
spinner->stopAnim();

// 使用停止角继续，减少跳回 0 的视觉突变
spinner->setAnim(60, 2000, true, -1, angle);

GetAnim 返回内部 lv_anim_t 指针，仅用于即时检查，不应缓存或释放；setAnim/stopAnim 后原指针可能失效。

4. setValue 的含义

cpp 复制代码 
void setValue(int time);

与多数控件不同，STTSpinner 的 value 是“每圈耗时毫秒”，不是速度或业务数值：

cpp 复制代码 
spinner->setValue(1000); // 约 1 秒一圈

setValue 会按当前弧长和方向重建无限动画。

5. 变量到转速的映射

cpp 复制代码 
void setRanges(int minv, int maxv, int mins, int maxs);

minv/maxv 是变量范围，mins/maxs 是对应速度，单位为圈/10 秒。

cpp 复制代码 
spinner->setRanges(-100, 100, -20, 20);
Ivariable speed = getRuntime()->getIVarMgr()->get("MotorSpeed");
if (speed != nullptr) {
    spinner->bindData(speed);
}

映射公式：

text 复制代码 
curS = (value - minV) / (maxV - minV) × (maxS - minS) + minS
每圈耗时(ms) = 10000 / curS

负 curS 表示逆时针，正值顺时针，0 会用 2147483647 ms 模拟近似停止。

实现细节：

  • 内部用整数并放大 1000 计算，存在截断。
  • value 不会被限制到 minV..maxV，超范围会外推速度。
  • onDataChanged 先调用一次 setValue(value)，随后又按映射结果 setAnim，第一次重建动画是冗余动作。
  • minV==maxV 时使用 minS 和 maxS 的平均速度。

6. API 汇总

方法 作用
setMainArg 位置、尺寸并启动动画
setMainStyle 背景圆环样式
setIndicStyle 指示圆弧样式
setAnim 设置弧长、圈时、方向和重复
stopAnim 停止并记录当前角
GetAnim 获取临时内部动画指针
getCurrentAngle 运行时读 current_value，停止后读缓存角
setValue 把输入当每圈毫秒重启动画
setRanges 设置变量值到转速的映射
onDataChanged 应用绑定变量

7. 注意事项

  • time 必须为正数。
  • 高速时 time 过小可能造成高刷新负载。
  • 速度为 0 时并不删除动画，而是设置极长周期；要真正停止请调用 stopAnim。
  • GetAnim 返回非拥有指针，禁止 delete。
  • 变量映射前先调用 setRanges。
  • UI/动画方法应在 LVGL 线程执行。
  • onDataChanged 是框架回调。
上一个
STTSlider使用手册
下一个
STTSwitch使用手册
最近修改: 2026-10-21Powered by