Qt for HarmonyOS 跑马灯标签组件开发实战

原创 于 2025-11-13 11:15:10 发布 · 786 阅读 · 20 ·
CC 4.0 BY-SA版权
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
文章标签：

#qt #harmonyos

目录

  1. 项目概述
  2. 技术栈选择
  3. 组件设计
  4. 核心功能实现
  5. 开发要点与技巧
  6. 使用示例
  7. 总结与展望

项目概述

在这里插入图片描述
项目地址：https://gitcode.com/szkygc/HarmonyOs_PC-PGC/tree/main/marqueeLabel

项目背景

在HarmonyOS应用开发中，跑马灯（Marquee）是一种常见的UI组件，用于在有限的空间内展示较长的文本内容。当文本长度超过容器宽度时，通过滚动动画让用户能够完整阅读所有内容。本项目基于Qt/QML框架，开发了一个高性能、可定制的跑马灯标签组件，为HarmonyOS应用提供流畅的文本滚动展示方案。

组件特性

本项目实现的跑马灯标签组件具有以下特性：

  • ✅ 平滑滚动动画：从右向左的连续滚动效果，支持自定义滚动速度和更新间隔
  • ✅ 智能文本处理：自动计算文本宽度，支持动态文本更新
  • ✅ 高度可定制：支持自定义文本颜色、字体大小、字体族等样式属性
  • ✅ 响应式设计：自动适配容器尺寸变化，支持不同屏幕尺寸
  • ✅ 性能优化：使用Timer精确控制动画帧率，避免不必要的重绘
  • ✅ 生命周期管理：正确处理组件可见性和尺寸变化，确保动画流畅

技术栈选择

前端框架：Qt/QML

选择理由：

  1. 声明式UI：QML的声明式语法使得UI开发更加直观和高效
  2. 性能优势：Qt的渲染引擎基于OpenGL ES，动画性能优异
  3. Timer机制：内置的Timer组件提供精确的时间控制，适合实现滚动动画
  4. TextMetrics API：提供文本宽度计算功能，无需手动测量

核心技术点

  • QtQuick 2.15：UI框架
  • Timer：定时器，控制滚动动画的更新频率
  • TextMetrics：文本度量，计算文本实际宽度
  • Property Binding：属性绑定，实现响应式更新

组件设计

整体架构

跑马灯组件采用简洁的架构设计：

Item (root)
├── TextMetrics - 文本宽度计算
├── Timer - 滚动动画控制
└── Text - 文本显示

属性接口

组件提供了丰富的可配置属性：

property string text: ""              // 显示的文本内容
property color textColor: "#01EEC3"   // 文本颜色
property int fontSize: 14              // 字体大小
property string fontFamily: "Microsoft YaHei"  // 字体族
property int scrollSpeed: 1            // 每次移动的像素数
property int scrollInterval: 10        // 更新间隔（毫秒）

内部属性

组件内部维护以下状态属性：

property string displayText: text      // 当前显示的文本
property real textX: width            // 文本的X坐标位置
property real textWidth: 0            // 文本的实际宽度

核心功能实现

1. 文本宽度计算

功能特点：

  • 使用 TextMetrics组件自动计算文本的实际渲染宽度
  • 支持动态文本更新，自动重新计算宽度
  • 处理文本为空的情况，避免异常

实现原理：

// 文本度量，用于计算文本宽度
TextMetrics {
    id: textMetrics
    font.family: root.fontFamily
    font.pixelSize: root.fontSize
    text: root.displayText
}

// 当文本改变时，重置位置并重新计算宽度
onTextChanged: {
    if (text === "") {
        textX = root.width
        textWidth = 0
    } else {
        // 延迟计算文本宽度，等待 TextMetrics 更新
        Qt.callLater(function() {
            if (textMetrics.width > 0) {
                textWidth = textMetrics.width
                textX = root.width
            }
        })
    }
}

关键技术点：

  • TextMetrics会根据字体属性自动计算文本宽度
  • 使用 Qt.callLater确保在TextMetrics更新后再获取宽度
  • 文本为空时重置状态，避免显示异常

2. 滚动动画控制

功能特点：

  • 使用Timer实现精确的滚动控制
  • 支持自定义滚动速度和更新间隔
  • 自动循环滚动，文本滚出后重新开始

实现原理：

// 定时器用于滚动
Timer {
    id: scrollTimer
    interval: root.scrollInterval  // 更新间隔（默认10毫秒）
    running: root.visible && root.text !== ""
    repeat: true
  
    onTriggered: {
        // 计算文本宽度（如果还未计算）
        if (textWidth === 0 && textMetrics.width > 0) {
            textWidth = textMetrics.width
            textX = root.width
        }
    
        // 更新位置：每次向左移动 scrollSpeed 像素
        textX -= scrollSpeed
    
        // 如果文本完全滚出左侧，重置到右侧
        if (textX <= -textWidth) {
            textX = root.width
        }
    }
}

关键技术点：

  • Timer的 interval属性控制更新频率，值越小动画越流畅
  • scrollSpeed控制每次移动的像素数，值越大滚动越快
  • 当文本完全滚出左侧（textX <= -textWidth）时，重置到右侧开始新一轮滚动
  • Timer只在组件可见且有文本时运行，节省资源

3. 文本位置管理

功能特点：

  • 文本从右侧（容器宽度位置）开始滚动
  • 支持动态调整，响应容器尺寸变化
  • 正确处理组件可见性变化

实现原理：

// 文本位置
property real textX: width  // 初始位置在容器右侧

// 绘制文本
Text {
    id: textItem
    x: root.textX
    y: (parent.height - height) / 2  // 垂直居中
    text: root.displayText
    font.family: root.fontFamily
    font.pixelSize: root.fontSize
    color: root.textColor
    verticalAlignment: Text.AlignVCenter
}

// 当组件宽度改变时，重新初始化位置
onWidthChanged: {
    if (visible && text !== "") {
        textX = root.width
        if (textMetrics.width > 0) {
            textWidth = textMetrics.width
        }
    }
}

// 当组件可见性改变时，重置位置
onVisibleChanged: {
    if (visible && text !== "") {
        textX = root.width
        if (textMetrics.width > 0) {
            textWidth = textMetrics.width
        }
    }
}

关键技术点：

  • 文本初始位置设置为 width，即容器右侧
  • 垂直居中通过 (parent.height - height) / 2实现
  • 响应 widthChanged和 visibleChanged信号，确保状态正确

4. 裁剪区域控制

功能特点：

  • 使用 clip: true限制文本显示区域
  • 防止文本溢出容器边界
  • 提升视觉效果

实现原理：

Item {
    id: root
    clip: true  // 裁剪超出容器的内容
  
    // ... 其他代码
}

关键技术点：

  • clip属性确保文本只在容器范围内可见
  • 当文本滚动到容器外时自动隐藏，不会影响其他UI元素

开发要点与技巧

1. 文本宽度计算的时机

文本宽度的计算需要在TextMetrics更新后进行，使用 Qt.callLater确保时序正确：

onTextChanged: {
    Qt.callLater(function() {
        if (textMetrics.width > 0) {
            textWidth = textMetrics.width
            textX = root.width
        }
    })
}

原因：

  • TextMetrics的更新是异步的，需要等待QML引擎完成布局计算
  • Qt.callLater将回调推迟到下一个事件循环，确保TextMetrics已更新

2. Timer的性能优化

Timer的 interval和 scrollSpeed需要平衡：

property int scrollSpeed: 1      // 每次移动1像素
property int scrollInterval: 10   // 每10毫秒更新一次

性能考虑：

  • interval太小（如1ms）会导致频繁更新，消耗CPU资源
  • interval太大（如100ms）会导致动画不流畅
  • 推荐值：10-20ms，既能保证流畅度，又不会过度消耗资源

滚动速度计算：

  • 实际滚动速度 = scrollSpeed / scrollInterval * 1000 像素/秒
  • 例如：scrollSpeed=1, scrollInterval=10 → 100像素/秒

3. 生命周期管理

正确处理组件的生命周期，避免资源浪费：

Timer {
    running: root.visible && root.text !== ""  // 只在可见且有文本时运行
    // ...
}

onVisibleChanged: {
    if (visible && text !== "") {
        // 重新初始化位置
        textX = root.width
        if (textMetrics.width > 0) {
            textWidth = textMetrics.width
        }
    }
}

最佳实践：

  • Timer只在组件可见且有内容时运行
  • 组件隐藏时停止Timer，节省资源
  • 组件重新显示时重置位置，确保动画正确

4. 响应式设计

组件需要响应容器尺寸变化：

onWidthChanged: {
    if (visible && text !== "") {
        textX = root.width  // 重新定位到右侧
        if (textMetrics.width > 0) {
            textWidth = textMetrics.width
        }
    }
}

应用场景：

  • 屏幕旋转时容器宽度变化
  • 窗口大小调整
  • 响应式布局中的尺寸变化

5. 文本更新处理

动态更新文本时需要重置滚动状态：

onTextChanged: {
    if (text === "") {
        // 文本为空时重置
        textX = root.width
        textWidth = 0
    } else {
        // 延迟计算新文本宽度
        Qt.callLater(function() {
            if (textMetrics.width > 0) {
                textWidth = textMetrics.width
                textX = root.width  // 从右侧重新开始
            }
        })
    }
}

关键点：

  • 文本更新时重新计算宽度
  • 重置位置到右侧，开始新的滚动
  • 处理空文本情况，避免显示异常

使用示例

基本使用

import QtQuick 2.15
import QtQuick.Controls 2.15

Rectangle {
    width: 400
    height: 60
    color: "#1E1E20"
    radius: 30
  
    MarqueeLabel {
        anchors.fill: parent
        anchors.margins: 20
        text: "花开一千年，花落一千年，花叶生生相错，世世永不相见。彼岸花开开彼岸，奈何桥前可奈何"
        textColor: "#01EEC3"
        fontSize: 14
        fontFamily: "Microsoft YaHei"
        scrollSpeed: 1
        scrollInterval: 10
    }
}

自定义样式

MarqueeLabel {
    width: 300
    height: 50
    text: "这是一段很长的文本，会自动滚动显示"
    textColor: "#FF6B6B"        // 自定义文本颜色
    fontSize: 16                 // 自定义字体大小
    fontFamily: "Arial"          // 自定义字体
    scrollSpeed: 2               // 加快滚动速度
    scrollInterval: 15           // 调整更新间隔
}

动态更新文本

Item {
    property string currentText: "初始文本"
  
    MarqueeLabel {
        id: marquee
        width: 400
        height: 60
        text: currentText
        textColor: "#01EEC3"
    }
  
    Button {
        anchors.bottom: parent.bottom
        text: "更新文本"
        onClicked: {
            currentText = "这是更新后的文本内容，会自动重新开始滚动"
        }
    }
}

响应式布局

ApplicationWindow {
    width: Screen.width > 1000 ? 1600 : 800
    height: Screen.height > 1000 ? 2560 : 741
  
    readonly property real scaleFactor: width > 1000 ? 2.0 : 1.0
  
    Rectangle {
        anchors.fill: parent
        anchors.margins: 20 * scaleFactor
    
        MarqueeLabel {
            anchors.fill: parent
            text: "响应式设计的跑马灯组件"
            fontSize: 14 * scaleFactor
            scrollSpeed: 1 * scaleFactor
        }
    }
}

完整示例：带输入功能的跑马灯

import QtQuick 2.15
import QtQuick.Controls 2.15
import QtQuick.Layouts 1.15

ApplicationWindow {
    width: 800
    height: 600
    visible: true
  
    ColumnLayout {
        anchors.fill: parent
        anchors.margins: 20
        spacing: 20
    
        // 跑马灯容器
        Rectangle {
            Layout.fillWidth: true
            Layout.preferredHeight: 60
            color: "#1E1E20"
            radius: 30
        
            MarqueeLabel {
                id: marqueeLabel
                anchors.fill: parent
                anchors.margins: 20
                text: "花开一千年，花落一千年，花叶生生相错，世世永不相见"
                textColor: "#01EEC3"
                fontSize: 14
                scrollSpeed: 1
                scrollInterval: 10
            }
        }
    
        // 输入区域
        Rectangle {
            Layout.fillWidth: true
            Layout.preferredHeight: 180
            color: "#ffffff"
            radius: 12
        
            ColumnLayout {
                anchors.fill: parent
                anchors.margins: 20
                spacing: 15
            
                Text {
                    text: "自定义跑马灯文字："
                    font.pixelSize: 16
                }
            
                TextField {
                    id: textInput
                    Layout.fillWidth: true
                    Layout.preferredHeight: 45
                    placeholderText: "请输入要显示的文字..."
                }
            
                Button {
                    Layout.fillWidth: true
                    Layout.preferredHeight: 45
                    text: "更新跑马灯文字"
                    onClicked: {
                        if (textInput.text.trim() !== "") {
                            marqueeLabel.text = textInput.text.trim()
                        }
                    }
                }
            }
        }
    }
}

总结与展望

技术总结

本项目成功实现了一个高性能、可定制的跑马灯标签组件，展示了Qt/QML在HarmonyOS平台上的强大能力：

  1. Timer机制：使用Timer实现精确的滚动控制，性能优异
  2. TextMetrics API：利用TextMetrics自动计算文本宽度，简化实现
  3. 响应式设计：正确处理尺寸和可见性变化，适配不同场景
  4. 生命周期管理：合理控制Timer运行时机，节省资源
  5. 组件化设计：提供丰富的可配置属性，便于复用和扩展

性能优化建议

  1. 合理设置Timer间隔：推荐10-20ms，平衡流畅度和性能
  2. 使用clip属性：限制绘制区域，提升渲染性能
  3. 条件运行Timer：只在组件可见且有内容时运行
  4. 避免频繁文本更新：批量更新文本，减少重新计算次数

扩展方向

  1. 滚动方向扩展：支持从左向右、上下滚动等方向
  2. 动画效果：添加淡入淡出、弹性动画等效果
  3. 多文本支持：支持多条文本循环显示
  4. 暂停/继续功能：添加暂停和继续滚动的控制接口
  5. 触摸交互：支持触摸暂停、滑动控制速度等交互
  6. 文本样式：支持富文本、渐变文字等高级样式

最佳实践

  1. 统一接口设计：使用标准的属性命名，便于理解和使用
  2. 性能考虑：合理设置Timer参数，避免过度消耗资源
  3. 响应式设计：确保组件在不同尺寸下都能正确显示
  4. 错误处理：处理空文本、尺寸异常等边界情况
  5. 代码注释：为关键逻辑添加注释，便于维护

适用场景

跑马灯组件适用于以下场景：

  • 通知栏：显示重要通知或公告
  • 状态栏：展示系统状态信息
  • 广告横幅：循环展示广告内容
  • 新闻滚动：显示新闻标题或摘要
  • 歌词显示：音乐播放器中的歌词滚动
  • 股票行情：实时滚动显示股票信息

相关资源

  • Qt官方文档：https://doc.qt.io/qt-5/qtquick-index.html
  • QML Timer文档：https://doc.qt.io/qt-5/qml-qtquick-timer.html
  • QML TextMetrics文档：https://doc.qt.io/qt-5/qml-qtquick-textmetrics.html
  • HarmonyOS开发文档：https://developer.harmonyos.com/
hahjee
关注
Qt6 for Android（HarmonyOS）真机调试
青春不老，奋斗不止！
09-12 3182
Qt6 在 Android（HarmonyOS）中的真机调试，基本步骤以及注意事项
Qt项目开发实例 （含源码）
热门推荐
啊渊的专栏
11-29 14万+
qt教程、qt项目、qt下载、qt项目实战、qt多线程。本文通过分析demo源码，QT实战的方式进行学习，学习路线是以实战为目录，全面的使用自己的学习知识，文章中编写一系列的学习游戏demo，与大家一起分享。
QT- label实现滚动字幕 (跑马灯)效果 -像素级
corefunction的博客
07-09 9263
网上资料比较多，但是csdn没有，而且也缺乏比较清晰的教程，于是打算写下这篇博客，和大家一起学习QT
QT 实现跑马灯
u012342051的专栏
05-06 2875
背景 应项目需求，需要实现一个体现系统运行状态的类似跑马灯效果一样的控件，跑马灯还是本科电子工艺实习期间焊接电路板的时候接触过，初听要用qt实现这个效果，还觉得挺有意思的。开始是调研，理解了一篇博客分享的点阵LED，开始着手实现，最终实现了一个动态的显示状态的小控件。现分享一个实现该控件的一个简要思路。单个LED的设计完全是借鉴过来的，实现跑马灯的效果，主要的工作体现在灯的放置上，也算是存在一个小小的算法设计，虽然这是一个小功能，但是实现之后还是挺有成就感的，特分享出来，供他人做自定义控件...
DevEco Studio中使用Qt，编写HarmonyOS程序
joyopirate的博客
07-28 9000
最近需要尝试把之前在Windwos下用Qt实现的程序移植到鸿蒙（HarmonyOS）系统上。我使用的DevEco版本是5.03.501找了一下资料，官方（也可能是社区）人员已经做过了Qt的移植。下载了后，按照他们的操作手册来操作就可以了。
Qt for OpenHarmony 编译鸿蒙调用的动态库
最新发布
luoyayun361的专栏
06-23 3376
本文介绍了在Windows环境下使用Qt Creator和Harmony NDK编译生成适用于OpenHarmony的动态库(.so)的完整流程。主要内容包括：1) 资源准备，包括下载Qt for OpenHarmony SDK、DevEco Studio开发环境和Qt安装；2) 详细的环境配置步骤，覆盖Qt版本、编译器、构建套件和环境变量设置；3) 实际编译过程，展示了如何创建Qt项目并选择OHOS Clang套件进行编译。该方案实现了Qt与OpenHarmony的集成开发，为跨平台应用迁移提供了高效工具
从零构建HarmonyOs开发环境
华为开发者联盟
09-19 8457
从零构建HarmonyOs开发环境 序 鸿蒙开发环境主要是两点： 1、需要一个linux环境：用来拉取代码、修改提交、以及编译构建 2、需要一个Windows环境：用来运行鸿蒙的IDE(DevCo)，它用来编辑代码，烧写调试 所以笔者建议的方式是，在Windows上虚拟一个linux。 本文将介绍如何基于Windows10主机，通过VirtualBox虚拟一个Linux系统（ubuntu）：   Win10上运行IDE，虚拟机运行Ubuntu，Win10通过ssh连接虚拟机获得shell端口；  &
Qt （高仿Visio）流程图组件开发，源码分享
11-21
内容概要：Qt6.4/c++开发，仿visio实现基本流程图功能，可拖动创建图元，图元之间连线，图元编辑，磁吸线，图元类型可扩建等等。代码功能完备，编写规范，注释清晰。 适用人群：适合有流程图功能开发需求的初学者。 ...
使用C++和QT开发应用程序入门以及开发实例分享
dvlinker的技术专栏
11-07 7565
本文详细介绍了使用C++和QT开发应用程序入门，并分享了一个开发实例。
QT QWidget - 跑马灯
听我一言的博客
12-17 577
关于前面画了个圆，怎么样也得跑个灯, 只是基于布局创建LED Widget而非 QTableView/QTableWidget;
Qt 实现的跑马灯效果
06-18
基于Qt的跑马灯效果，支持配置文件读取。tcp 设置字体、颜色，大小，内容功能
Qt 实现跑马灯效果
qthello
06-18 4170
参考某大神博客，针对自己的需求，实现了跑马灯效果。 效果如下： 思路： 1，启动定时器 进行刷新 my_timer_id_ = startTimer(10, Qt::PreciseTimer); 2，每触发一次定时器，偏移量增加固定大小。void Ticker::leftScrollTimerEvent(QTimerEvent *ev) offset_ ++； ...
Qt For OpenHarmony
OpenHarmony_dev的博客
09-15 3058
基于 Qt 跨平台特性及 Qt For OpenHarmony 的适配，能够促进 OpenHarmony 跨平台应用迁移及应用开发，对 OpenHarmony 技术生态有一定的积极作用，期待大家一块参与到 Qt 适配 OpenHarmony 的相关工作中来。点击关注了解更多OpenHarmony TSC技术干货内容。
Qt实现歌词播放流光跑马灯特效
qq_36651243的博客
03-25 1464
Qt实现歌词播放流光跑马灯特效
关于跨平台应用开发工具
数字人生
11-28 3926
【代码】关于跨平台应用开发工具。
最后的挣扎 - Qt For Android on HuaWei Mate 60Pro (v4.0.0)
听我一言的博客
03-17 1691
Qt for android On Huawei Mate60 Pro(HarmonyOS 4.0.0)
Qt工作笔记-跑马灯效果
IT1995的博客
07-25 5753
逻辑： 使用静态变量确定位置； 利用QString中mid这函数的性质： 程序运行截图如下：   代码如下： widget.h #ifndef WIDGET_H #define WIDGET_H #include &lt;QWidget&gt; class QTimer; namespace Ui { class Widget; } class Widget : publ...
Qt实现轮播图(走马灯)，类似element ui的走马灯
Sakeyuan的博客
08-26 948
整体使用了一个QStackedWidget堆栈窗口，堆栈窗口里面储存QLabel，用QLabel负责显示图片，并使用一个QTimer来自动播放，其实就是时间到了触发信号，然后槽函数负责切换QStackedWidget的index。两侧按钮覆盖层是淡蓝色的，使用resizeEvent重新绘制界面，覆盖窗口大小。使用方式：在主窗口添加一个Widget提升为MyCarousel类就可以了。按钮布局我这里使用的是用两个透明的Widget来布局的。下面按钮则需要根据按钮大小和按钮数量设置绘制的位置。
Qt嵌入式开发实战：构建智能交通灯系统
标题中提到的“Qt嵌入式系统开发与应用实训--交通灯系统”涉及的知识点十分丰富，接下来我会逐项详细说明。 首先，Qt是一个跨平台的C++图形用户界面应用程序框架，它广泛用于开发具有复杂用户界面的应用程序。在...
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值