菜单

STTQRCode使用手册

下载

STTQRCode.h 使用手册

STTQRCode 封装 LVGL 二维码对象，可显示文本或任意字节序列。虽然头文件包含 STTCanvas.h，但类本身继承 STTWidget。

1. 必须先初始化

构造函数只初始化类型和内部指针，并不创建底层二维码 object。必须先调用一次 setMainArg：

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

using namespace stt;

STTQRCode* qr = new STTQRCode(getRuntime(), parent, "qrOrder");
qr->setMainArg(
    20, 20, 180, 180,
    0xffffff,
    0x000000,
    "ORDER:20261020-001"
);

在 setMainArg 之前调用 update、setSize 或析构一个未完成初始化的对象，都可能访问空 object。创建后应立即完成 setMainArg。

2. setMainArg 行为

cpp 复制代码 
void setMainArg(
    int x = 0, int y = 0, int w = 100, int h = 100,
    int background = 0xffffff,
    int foreground = 0x000000,
    const char* data = "www.simtutai.com"
);

第一次调用时：

  • 实际二维码边长使用 max(w, h)，小于等于 0 时使用 100。
  • 创建底层对象、设置颜色和位置。
  • 使用 strlen(data) 更新二维码，所以 data 必须是非空、以零结尾的字符串。

后续再次调用 setMainArg 只执行 setSize(w, h)，不会更新位置、颜色或 data。这是当前实现的重要差异，不应把第二次调用当作完整重新配置。

3. 更新内容

字符串重载：

cpp 复制代码 
uint8_t rc = qr->update("https://example.com/order/001");

字节重载：

cpp 复制代码 
const char payload[] = {'A', 'B', '\0', 'C'};
uint8_t rc = qr->update(payload, sizeof(payload));

签名：

cpp 复制代码 
uint8_t update(const void* data, int data_len);
uint8_t update(const string& data);

返回值直接来自 lv_qrcode_update。头文件写“1 成功、0 失败”，但 LVGL 版本的 lv_res_t 枚举语义可能相反或不同，应以本工程所用 LVGL 定义为准，不要硬编码 rc==1。至少可在真机上用已知短文本验证。

void* 重载还会把 data 当 C 字符串保存到内部 string，因此即便 data_len 支持二进制，中间零字节后的缓存内容会截断；控件改变尺寸后重绘只会使用截断后的缓存。需要二进制二维码时，尺寸变更后应再次传完整数据。

4. 尺寸接口

cpp 复制代码 
qr->setSize(220, 220);

setSize 会重新分配 1 bit canvas 缓冲区并用缓存内容重绘。二维码通常应保持正方形。

当前实现：

cpp 复制代码 
qr->setWidth(200);  // 空操作
qr->setHeight(200); // 空操作

setWidth 和 setHeight 的底层调用已被注释，虽然返回 this，但不会改变尺寸。必须使用 setSize。

缓冲区 realloc 没有显式检查失败；避免频繁以大尺寸反复缩放。

5. 变量绑定

cpp 复制代码 
Ivariable code = getRuntime()->getIVarMgr()->get("OrderQRCode");
if (code != nullptr) {
    qr->bindData(code);
}

onDataChanged 直接用 data->toStr() 更新二维码。变量文本过长可能因当前尺寸和二维码容量不足而更新失败。

6. 完整示例

cpp 复制代码 
STTQRCode* qr = new STTQRCode(getRuntime(), panel, "qrTrace");
qr->setMainArg(32, 32, 200, 200, 0xffffff, 0x111111, "INIT");

string trace = "TRACE|SN=ABCD1234|DATE=20261020";
uint8_t status = qr->update(trace);

// 需要调整时使用 setSize，不使用 setWidth/setHeight
qr->setSize(240, 240);

7. 注意事项

  • 构造后必须先调用 setMainArg。
  • data 指针不能为 nullptr，C 字符串必须以零结尾。
  • setWidth/setHeight 当前无效。
  • 第二次 setMainArg 不会更新颜色、位置和内容。
  • update 返回值应按当前 LVGL 的 lv_res_t 定义解释。
  • 控件内容越长，所需二维码版本越高；尺寸太小会影响生成或扫描。
  • onDataChanged 属于框架回调，一般不直接调用。
最近修改: 2026-10-21Powered by