菜单

STTImage使用手册

下载

STTImage.h 使用手册

STTImage 封装 LVGL Image，支持文件图片、偏移、旋转、缩放、状态图片、变量驱动和缓存失效。

1. 创建与图片源

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

using namespace stt;

STTImage* image = new STTImage(getRuntime(), parent, "imgStatus");
image->setMainArg(20, 20, 128, 128, "res/pump_off.png");

setMainArg 会设置位置、尺寸、可点击标志、图片源，并把背景设为透明。头文件提示不同显示尺寸不要复用同一个图片文件，应按资源生成规则为不同尺寸准备文件。

cpp 复制代码 
image->setSrc("res/pump_on.png");
const void* src = image->getSrc();

setSrc 优化了相同文件路径重复刷新：当前源已是相同文件时直接返回，避免重复磁盘读取和图片解码。空字符串会清除当前图片。

2. 偏移

cpp 复制代码 
image->setOffsetX(12)->setOffsetY(8);

int x = image->getOffsetX();
int y = image->getOffsetY();

偏移使用 LVGL 图片环绕规则，超出边界的部分从另一端继续绘制，适合滚动纹理。

3. 旋转与中心点

cpp 复制代码 
image->setPivot(64, 64);
image->setAngle(45.0f);
image->rotate(15.0f); // 当前 45 度基础上再转 15 度

float angle = image->getAngle();
LvPoint pivot = image->getPivot();

内部以 0.1 度单位存储，setAngle 将浮点乘 10 后转为整数。接口自身不把角度限制在 0..360，连续 rotate 的最终归一化由 LVGL 处理。

4. 缩放

cpp 复制代码 
image->setZoom(1.5f);
float zoom = image->getZoom();

setZoom 使用 factor = zoom × 256。头文件给出范围 1/256..256，但当前实现没有校验。

已知误差：getZoom 使用底层值除以 250.0，而不是 256.0。因此 setZoom(1.0) 后可能读到约 1.024。不要用 getZoom 做精确等值判断；需要精确业务值时由调用方自行保存。

5. 状态图片

cpp 复制代码 
image->addStateImg("0", "res/pump_off.png");
image->addStateImg("1", "res/pump_on.png");
image->setState("1");

addStateImg 只登记映射，并把 curState 改为该 state，不会立即显示图片。调用 setState 或 refresh 后才会解析并显示。

状态键还支持含问号的表达式模板。实现会把键中的 ? 替换为当前 state，再交给 Util::simpleCalc：

cpp 复制代码 
image->addStateImg("? > 80", "res/high.png");
image->addStateImg("? <= 80", "res/normal.png");
image->setState("95");

匹配按 std::map 的键排序顺序遍历，不是 addStateImg 的插入顺序。多个条件同时成立时使用第一个排序命中的键。未匹配任何状态时清空图片。

状态文本来自外部变量时会进入简单表达式字符串，必须只使用受信的数字/表达式格式。

6. 变量绑定与刷新

cpp 复制代码 
Ivariable state = getRuntime()->getIVarMgr()->get("PumpState");
if (state != nullptr) {
    image->bindData(state);
}

onDataChanged 用变量 toStr() 调用 setState。refresh 会先按绑定变量或 curState 刷新图片，再刷新动画、显隐、闪烁、权限和使能 helper。

7. 图片缓存

cpp 复制代码 
STTImage::cacheInvalidateSrc((void*)"res/pump_on.png");
STTImage::cacheInvalidateSrc(nullptr); // 清空全部 LVGL 图片缓存

仅当同一路径的文件内容已经被替换、确实需要重新解码时调用。传 nullptr 清空全部缓存可能导致下一次页面显示集中发生磁盘 I/O，不要在普通 refresh 中调用。

8. API 汇总

类别 方法
初始化 setMainArg
图片源 setSrc、getSrc、cacheInvalidateSrc
状态 addStateImg、setState
偏移 setOffsetX/Y、getOffsetX/Y
变换 setAngle、rotate、getAngle、setPivot、getPivot、setZoom、getZoom
刷新 refresh、onDataChanged

9. 注意事项

  • 图片文件路径和资源必须在显示期间有效。
  • 条件状态按键排序匹配，避免条件重叠。
  • addStateImg 不会立即显示。
  • getZoom 存在 250/256 的实现误差。
  • 清空全局图片缓存代价较高。
  • 大图旋转和缩放会增加 CPU 与内存带宽开销。
  • UI 方法在 LVGL 线程调用。
最近修改: 2026-10-21Powered by