🎮 在线体验:本章控件的渲染效果可在 控件在线演示页 实时交互——GT-HMI Engine 以 WebAssembly 在浏览器内渲染,调整右侧参数即可实时查看控件效果,与真机渲染一致。
4.1 条形码控件
在创建的屏幕控件中添加一个条形码控件并设置控件属性。
API 参考:
| 函数 | 说明 | 默认值 |
|---|---|---|
gt_barcode_create(parent) | 创建条形码控件 | — |
gt_barcode_set_type(barcode, family) | 设置条码类型(由 Designer 导出,见 barcode_type_te) | GT_FAMILY_BARCODE_TYPE_EAN_13 |
gt_barcode_set_code_text(barcode, "code") | 设置条码编码内容 | "1234567890128" |
gt_barcode_set_mode_w(barcode, value) | 设置条码模块宽度(像素) | 2 |
gt_barcode_set_mode_h(barcode, value) | 设置条码模块高度(像素) | 64 |
gt_barcode_set_hri_type(barcode, family) | 设置条码底部 HRI 字幕类型 | GT_FAMILY_BARCODE_HRI_TYPE_DOWN |
gt_barcode_set_upc_e_sys_code(barcode, value) | 设置 UPC-E 系统码位 | 0 |
/** barcode1 */
// 在 screen_home 屏幕控件中创建一个条形码控件
barcode1 = gt_barcode_create(screen_home);
// 设置控件坐标
gt_obj_set_pos(barcode1, 300, 100);
// 设置控件尺寸
gt_obj_set_size(barcode1, 138, 80);
// 设置条形码类型为 EAN-13
gt_barcode_set_type(barcode1, GT_FAMILY_BARCODE_TYPE_EAN_13);
// 设置条形码模块宽度为 2 个像素
gt_barcode_set_mode_w(barcode1, 2);
// 设置条形码模块高度为 64 个像素
gt_barcode_set_mode_h(barcode1, 64);
// 设置条形码内容
gt_barcode_set_code_text(barcode1, "1234567890128");
运行后的条形码控件效果见下方在线演示(可直接交互):
4.2 二维码控件
在创建的屏幕控件中添加一个二维码控件并设置控件属性。
API 参考:
| 函数 | 说明 | 默认值 |
|---|---|---|
gt_qrcode_create(parent) | 创建二维码控件 | — |
gt_qrcode_set_version(qr_code, version) | 设置二维码版本:GT_FAMILY_QRCODE_VERSION_3 ~ 17 | GT_FAMILY_QRCODE_VERSION_10 |
gt_qrcode_set_str(qr_code, "str") | 设置二维码内容 | "https://www.hmi.gaotongfont.cn/" |
gt_qrcode_set_background(qr_code, color) | 设置背景颜色 | gt_color_white() |
gt_qrcode_set_forecolor(qr_code, color) | 设置前景颜色 | gt_color_black() |
/** qrcode1 */
// 在 screen_home 屏幕控件中创建一个二维码控件
qrcode1 = gt_qrcode_create(screen_home);
// 设置控件坐标
gt_obj_set_pos(qrcode1, 468, 356);
// 设置控件尺寸
gt_obj_set_size(qrcode1, 37, 37);
// 设置二维码版本
gt_qrcode_set_version(qrcode1, GT_FAMILY_QRCODE_VERSION_8);
// 设置二维码背景色
gt_qrcode_set_background(qrcode1, gt_color_hex(0xFFFFFF));
// 设置二维码前景色
gt_qrcode_set_forecolor(qrcode1, gt_color_hex(0x000000));
// 设置二维码内容
gt_qrcode_set_str(qrcode1, "https://www.hmi.gaotongfont.cn/");
运行后的二维码控件效果见下方在线演示(可直接交互):
能力与限制(GT-HMI-Engine v1.4.16+ 实测口径):
| 能力 | 状态 | 说明 |
|---|---|---|
| 二维码生成与显示 | ✅ 支持 | 版本 3~17、内容、前景/背景色可配 |
| 自适应尺寸 | ✅ 支持 | 未显式设置尺寸时按内容自然生长 |
gt_obj_set_size 缩小 | ✅ 已修复 | v1.4.15 及之前区域只增不减,eea5a0a9 起仅在未设尺寸时生长,显式 set_size 后不再回弹 |
| 首帧渲染 | ⚠️ 受限 | 自适应生长路径下首帧脏区在生长前计算,首帧可能近空白;需二次 invalid 或延迟一帧刷新 |
| 小区域裁剪 | ⚠️ 受限 | set_size 小于二维码自然宽度时,模块宽度计算可能无符号回绕,且绘制不按控件区域裁剪,QR 会按自然宽画出区域外;建议设置不小于自然尺寸的区域 |
若需精确控制二维码显示位置与大小,建议先通过自然尺寸查询或在线演示确认实际渲染尺寸,再设置控件区域。
4.3 滑窗控件
在创建的屏幕控件中添加一个滑窗控件并设置控件属性。
API 参考:
| 函数 | 说明 | 默认值 |
|---|---|---|
gt_view_pager_create(parent) | 创建滑窗控件 | — |
gt_view_pager_set_fragment_count(obj, count) | 设置总页数 | — |
gt_view_pager_add_fragment(obj) | 添加一个空白页,返回页索引 | — |
gt_view_pager_fragment_add_widget(vp, idx, child) | 将子控件添加到指定页(idx 从 0 开始) | — |
gt_view_pager_scroll_to_fragment(obj, index) | 滚动到指定页 | — |
gt_view_pager_set_scroll_effect(obj, effect) | 滚动效果:DEFAULT(默认)/ STATIC / NO_FINGER_FOLLOW | DEFAULT |
gt_view_pager_get_cur_page(obj) | 获取当前页索引 | — |
gt_view_pager_get_widget_belong_fragment(vp, child) | 获取子控件所属页索引,-1=未找到 | — |
gt_view_pager_set_glass(obj, enabled) | 背景玻璃效果 | false |
gt_view_pager_set_glass_color(obj, color) | 玻璃效果颜色 | — |
gt_view_pager_set_window_size(obj, w, h) | 设置可视窗口尺寸(创建后、添加页之前调用) | 与父容器一致 |
gt_view_pager_set_direction(obj, dir) | 滚动方向:GT_VIEW_PAGER_DIR_HORIZONTAL(默认) / VERTICAL | HORIZONTAL |
gt_view_pager_set_tip_bar_pos(obj, pos) | 指示条位置:DEFAULT / OPPOSITE | DEFAULT |
// 在 screen_home 屏幕控件中创建一个滑窗控件
viewPager1 = gt_view_pager_create(screen_home);
// 设置滑窗控件的位置 (0, 0)
gt_obj_set_pos(viewPager1, 0, 0);
// 设置滑窗控件的尺寸(宽度 480,高度 320 默认为屏幕尺寸)
gt_obj_set_size(viewPager1, 480, 320);
// 设置滑窗控件的透明度
gt_obj_set_opa(viewPager1, GT_OPA_0);
// 设置滑窗控件的页数
gt_view_pager_set_fragment_count(viewPager1, 2);
// 设置滑窗控件背景的玻璃效果
gt_view_pager_set_glass(viewPager1, 0);
与之对应的在其他控件设置所属的滑窗,以添加控件到滑窗内部。
// 为滑窗控件的第一页(从 0 开始)添加图片控件 1
gt_view_pager_fragment_add_widget(viewPager1, 0, img1);
// 为滑窗控件的第二页添加图片控件 4
gt_view_pager_fragment_add_widget(viewPager1, 1, img4);
运行后的滑窗结果见下方在线演示(可直接交互):
4.4 直线控件
在创建的屏幕控件中添加一个直线控件并设置控件属性。
API 参考:
| 函数 | 说明 | 默认值 |
|---|---|---|
gt_line_create(parent) | 创建直线控件 | — |
gt_line_set_color(line, color) | 设置线条颜色 | — |
gt_line_set_start_point(line, xs, ys) | 设置起点坐标(屏幕绝对坐标) | — |
gt_line_set_end_point(line, xe, ye) | 设置终点坐标(屏幕绝对坐标) | — |
gt_line_set_hor_line(line, length) | 设为水平线(长度=length),以 gt_obj_set_pos() 设定的控件位置为起点 | — |
gt_line_set_ver_line(line, length) | 设为垂直线(长度=length),以 gt_obj_set_pos() 设定的控件位置为起点 | — |
gt_line_set_line_width(line, line_width) | 设置线宽(像素) | — |
gt_line_set_brush_type(line, type) | 端点样式:GT_BRUSH_TYPE_ROUND(圆形)或 GT_BRUSH_TYPE_RECT(方形) | ROUND |
gt_line_get_start_point(line, ret_p) | 获取起点坐标 | — |
gt_line_get_end_point(line, ret_p) | 获取终点坐标 | — |
坐标语义:
gt_line_set_start_point()/gt_line_set_end_point()的坐标为屏幕绝对坐标,直接对应线段在屏幕上的绘制位置,不随gt_obj_set_pos()设定的控件位置叠加偏移(设置端点后,控件区域会自动调整为包住整条线段)。若只需水平线或垂直线,用gt_line_set_hor_line()/gt_line_set_ver_line()更方便——它们以gt_obj_set_pos()设定的控件位置为起点、按给定长度生成端点。
/** line1 */
// 在 screen_home 屏幕控件中创建一个直线控件
line1 = gt_line_create(screen_home);
// 设置控件坐标
gt_obj_set_pos(line1, 50, 50);
// 设置水平线长度为 200 像素
gt_line_set_hor_line(line1, 200);
// 设置线宽为 3 像素
gt_line_set_line_width(line1, 3);
// 设置线条颜色为红色
gt_line_set_color(line1, gt_color_hex(0xFF0000));
// 设置端点样式为圆形
gt_line_set_brush_type(line1, GT_BRUSH_TYPE_ROUND);
4.5 表格控件
表格控件支持多行多列表格显示。需先添加表头(确定列数),再添加内容,最后调用 gt_table_refresh()。
API 参考:
| 函数 | 说明 | 默认值 |
|---|---|---|
gt_table_create(parent) | 创建表格控件 | — |
gt_table_add_header_text_by_len(table, "text", len, align) | 添加表头单元格(确定列数)。align 推荐 GT_ALIGN_LEFT_MID / CENTER_MID / RIGHT_MID | — |
gt_table_add_content_text_by_len(table, "text", len) | 添加内容单元格(自动换行填充,逐列添加) | — |
gt_table_refresh(table) | 必须调用。添加完表头和内容后计算每列的最大宽高 | — |
gt_table_set_font_color(table, color) | 设置字体颜色 | — |
gt_table_set_font_size(table, size) | 设置字体大小(pt) | — |
gt_table_set_font_gray(table, gray) | 设置字体灰度:1 / 2 / 4 | — |
gt_table_set_font_scale_size(table, scale_size) | 软件缩放目标尺寸(0=不缩放) | 0 |
gt_table_set_font_family(table, family) | 设置字体系列 | — |
gt_table_set_font_cjk(table, cjk) | 设置 CJK 字体变体 | — |
gt_table_set_font_thick_en(table, thick) | 设置英文字体粗细 | — |
gt_table_set_font_thick_cn(table, thick) | 设置中文字体粗细 | — |
gt_table_set_font_encoding(table, encoding) | 设置文本编码:见 枚举速查表 gt_encoding_et | — |
gt_table_set_font_style(table, font_style) | 设置字体风格:见 枚举速查表 gt_font_style_et | NORMAL |
gt_table_set_header_bold(table, is_bold) | 表头加粗 | false |
gt_table_set_font_info(table, font_info) | 批量设置字体信息(gt_font_info_st 结构体) | — |
/** table1 */
// 在 screen_home 屏幕控件中创建一个表格控件
table1 = gt_table_create(screen_home);
// 设置控件坐标和尺寸
gt_obj_set_pos(table1, 10, 10);
gt_obj_set_size(table1, 460, 300);
// 设置字体大小
gt_table_set_font_size(table1, 16);
// 表头加粗
gt_table_set_header_bold(table1, true);
// 添加表头(3 列)
gt_table_add_header_text_by_len(table1, "序号", strlen("序号"), GT_ALIGN_CENTER_MID);
gt_table_add_header_text_by_len(table1, "名称", strlen("名称"), GT_ALIGN_LEFT_MID);
gt_table_add_header_text_by_len(table1, "数值", strlen("数值"), GT_ALIGN_RIGHT_MID);
// 添加内容
gt_table_add_content_text_by_len(table1, "1", strlen("1"));
gt_table_add_content_text_by_len(table1, "温度", strlen("温度"));
gt_table_add_content_text_by_len(table1, "25.6°C", strlen("25.6°C"));
gt_table_add_content_text_by_len(table1, "2", strlen("2"));
gt_table_add_content_text_by_len(table1, "湿度", strlen("湿度"));
gt_table_add_content_text_by_len(table1, "68%", strlen("68%"));
// 必须调用 refresh 使表格生效
gt_table_refresh(table1);
运行后的表格控件效果见下方在线演示(可直接交互):
在线交互演示见本页控件演示区"表格 gt_table"卡片(表头对齐 / 追加内容可实时调整,无需重新编译)。
能力与限制(GT-HMI-Engine v1.4.16+ 实测口径):
| 能力 | 状态 | 说明 |
|---|---|---|
| 多行多列表格 | ✅ 支持 | 表头确定列数,内容逐列添加 |
| 表头 / 内容字体配置 | ✅ 支持 | 字号、颜色、灰度、字库、对齐方式等 |
| 列间竖线 | ✅ 已修复 | v1.4.15 及之前列间无竖线(M-2),00eb4703 起列间竖线连续 |
| 数字列显示 | ✅ 已修复 | 历史版本存在数字列随机截断问题,v1.4.16 复测已正常 |
| 表格后段落 | ✅ 已修复 | 历史版本存在表格后段落重叠问题,现已正常排在表下 |
| 超高内容 | ⚠️ 受限 | 内容超出控件设定高度时直接裁剪,无滚动条/滚动能力;需根据内容量预留足够控件高度,或分页显示 |
表格内容量较大时,建议先通过
gt_table_refresh()后的实际渲染高度评估是否超出控件区域,必要时拆分为多页或减小字号/行距。

