菜单

STTLabel使用手册

下载

STTLabel.h 使用手册

STTLabel 提供文本、多语言、数值/货币/日期格式化和报警条显示；STTMultiLabel 在其基础上增加按状态切换文字、颜色和闪烁。

1. 普通标签

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

using namespace stt;

STTLabel* label = new STTLabel(getRuntime(), parent, "lblValue");
label->setMainArg(20, 20, 220, 40, "设备状态", 2, 0, 10);
label->setFonts(0x222222, 18, "", 0);
label->setMainStyle(4, 0xffffff, 0xffffff, 0, 0, 0, 0);
label->setFormatText(2, 1, 20);
label->setText("运行");

实现差异：setMainArg 当前只使用位置、尺寸、txt 和 align；longmode 与 speed 参数未应用。要设置长文本模式和滚动速度，必须再调用 setFormatText。

setPos 在 widget pool 模式下转换绝对坐标并输出日志。

2. 文本与多语言

cpp 复制代码 
label->setText("_L(\"运行\")");
string rendered = label->getText();
string sourceTag = label->getTag();
  • getText 返回 LVGL 当前显示文本。
  • getTag 返回 setText/setMainArg 保存的原始标签。
  • 文本格式模式下 setText 会通过 LanguageManager::getTag 翻译。
  • 构造时连接系统 Language 变量，语言变化时重新 setText(tag)。

setRecolor(true) 启用 LVGL recolor 标记，例如：

cpp 复制代码 
label->setRecolor(true);
label->setText("#ff0000 警告# 正常文本");

setSymbol 将标签切换到图标格式：

cpp 复制代码 
label->setSymbol(ICON::AUDIO, 24);

进入图标格式后，setText/setValue 会直接返回，不能再覆盖图标；当前没有公开接口退出 fmtType=6，通常应新建普通标签。

3. 长文本与居中

cpp 复制代码 
label->setLongMode(3);
int mode = label->getLongMode();
label->middle();
int16_t height = label->getTextHeight();

模式：

值 含义
0 自动换行
1 超出显示省略号
2 往返滚动
3 循环滚动
4 裁剪

middle 通过计算文字高度后设置 top padding 实现垂直居中。应在尺寸、字体和文本确定后调用。setText/setValue 已会调用 middle。

4. 数值格式

cpp 复制代码 
label->setFormatNumerical(
    2, true, 1,
    0.001, 0.0,
    4, false,
    "", " kPa"
);
label->setText("123456");

显示计算：

text 复制代码 
显示值 = 原值 × factor + offset

fmttype：

值 格式
1 普通数字
4 百分比，额外乘 100；suffix 为空时自动加 %
5 科学计数

intnum/intbl 被内部复用为整数位长度和补零开关。解析失败时普通数值/货币会显示格式化的 0，而不是原字符串。

5. 货币与日期

cpp 复制代码 
label->setFormatCurrency(2, true, "¥");
label->setText("12345.6");

日期：

cpp 复制代码 
label->setFormatDate("-", ":", true, true, true,
                     true, true, true, true);
label->setText("1792454400");

值小于等于 315360000 秒时被当作持续时间/倒计时，大于该值才按 Unix 时间戳日期格式处理。这与头文件“必须是 10 位时间戳”的描述相比更宽。

中文年月日/时分秒可把 deli1/deli2 设为 "中文"。

6. 变量绑定

cpp 复制代码 
label->setFormatNumerical(1, false, 1, 1.0, 0.0);
label->bindData(getRuntime()->getIVarMgr()->get("Pressure"));

setValue(IVariable*) 按当前 fmtType 格式化。onDataChanged 遇到 TTableView 时进入报警条模式，否则调用 setValue。

7. 报警条

cpp 复制代码 
label->setWarningArg(3);
label->setEventFlags(
    (1 << 1) | // 名称
    (1 << 4) | // 时间
    (1 << 6)   // 说明
);
label->setDataSourceOfEvent(0, 15);

单类别重载：

cpp 复制代码 
label->setDataSourceOfEvent(catalog, level);

类别范围重载：

cpp 复制代码 
label->setDataSourceOfEvent(cata1, cata2, levelMask);

levelMask 使用 1/2/4/8。内部总是绑定今天、最多 255 行的当前报警视图。setWarningArg 控制最终显示最新 n 条。持续字段非空的已处理记录被跳过。

setEventFlags 位：

位 内容
0 事件 ID
1 名称
2 累计次数
3 累计时长
4 时间
5 用户
6 说明
7 持续时长

实际 TTableView 列顺序必须与这些位一致。

8. STTMultiLabel

cpp 复制代码 
STTMultiLabel* status =
    new STTMultiLabel(getRuntime(), parent, 0, "lblStatus");
status->setMainArg(20, 80, 160, 40);

status->setStateTitle(
    "0",
    "停止",
    R"({"fc":"0x666666","bc":"0xeeeeee","ef":"0"})"
);
status->setStateTitle(
    "1",
    "运行",
    R"({"fc":"0xffffff","bc":"0x18a765","ef":"1","ft":"1"})"
);
status->bindData(getRuntime()->getIVarMgr()->get("RunState"));

style JSON：

键 说明
fc 字体颜色
bc 背景色
ef 1 启用闪烁
ft 闪烁档位 0、1、2
et 被解析但当前未使用

setStateTitle 使用 map::insert，相同 state 再次设置不会覆盖已有项。state 为空会忽略。状态支持与按钮相同的条件匹配。

未匹配状态时标签隐藏；相同值重复到达时直接返回。onLanguageChanged 当前为空，多状态 title 不会自动随语言切换。

实现风险：多状态标签刷新可见性时会把 m_helpers 中每个项都强转为 WidgetVisibleHelper，而未检查 helper 类型；同时配置动画、权限等其他 helper 时可能发生无效转换。

9. 注意事项

  • setMainArg 的 longmode/speed 当前无效，使用 setFormatText。
  • setSymbol 后不能通过公开方法恢复普通文本格式。
  • 日期值小于约 10 年秒数时按持续时间处理。
  • 报警绑定依赖 EventMgr 的线程和数据库约束。
  • STTMultiLabel 重复 state 不覆盖，语言回调为空。
  • 多状态标签尽量不要叠加非可见性 helper。
  • Runtime 的 Language 变量和字体管理器必须存在。
最近修改: 2026-10-21Powered by