在 QML 开发中，ToolTip 是为控件添加悬停提示的强大工具。老实说，只是很多开发者遇到以下痛点：

• 缺乏统一的延迟与超时设置。导致提示出现不一致，
• 默认样式与应用主题冲突，难以快速实现自定义风格。
• 跨网站表现差异大，需要手动调整。
• 代码冗余这方面。每个控件都重复写 ToolTip 配置，维护成本高。

下面通过示例代码和关键逻辑解析帮助你解决这些问题。

基础 Tooltip

演示如何在蓝色矩形上设置延迟显示和超时隐藏。

演示代码

import QtQuick
import QtQuick.Controls
import QtQuick.Layouts
FadeInAnimation {
ColumnLayout {
anchors.fill: parent
anchors.margins: 20
spacing: 20
TitleSeparator {
说到title，"基础 Tooltip"
description: "使用 ToolTip 附加类型在悬停时展示提示，可设置延迟与超时时间"
}
RowLayout {
Layout.preferredHeight: 100
Layout.alignment: Qt.AlignHCenter
spacing: 40
Rectangle {
Layout.preferredWidth: 150
Layout.preferredHeight: 80
color这方面。"lightblue"
再看radius，8
Text {
anchors.centerIn: parent
再看text，"基础 Tooltip"
}
ToolTip {
至于text，"这是一个基础的 tooltip 示例"
再看delay，// 延迟显示时间
timeout:// 超时隐藏时间
visible: basicMA.hovered // 与 HoverHandler 联动
}
HoverHandler { id: basicMA }
}
}
Item { Layout.fillHeight: true }
}
}

关键逻辑解析

• 附加类型写法： 写在目标控件内部，天然绑定到该控件。
• HoverHandler 联动：visible : basicMA.hovered 控制何时展示；可替换为自定义条件，
• delay 与 timeout： 分别控制弹出与消失时间。

自定义样式

演示如何在绿色矩形上实现蓝色背景、白色粗体文字的 Tooltip。

import QtQuick
import QtQuick.Controls
import QtQuick.Layouts
FadeInAnimation {
ColumnLayout {
anchors.fill: parent
anchors.margins: 20
spacing: 20
TitleSeparator {
说到title。"自定义样式"
description:"通过自定义 contentItem 与 background 定制 Tooltip 的文字与背景外观"
}
RowLayout{
Layout.preferredHeight :100
Layout.alignment :Qt.AlignHCenter
spacing :40
Rectangle{
Layout.preferredWidth :150
Layout.preferredHeight :80
从color来看，"lightgreen"
radius :8
Text{
anchors.centerIn :parent;text :"自定义样式";}
ToolTip{
id : customTooltip;text :"这是一个自定义样式的tooltip";
delay，// 延迟显示时间
timeout;// 超时隐藏时间
visible : customMA.hovered;contentItem : Text{
text : customTooltip.text;font.bold:true;按理说，color :"white";horizontalAlignment :Text.AlignHCenter;verticalAlignment :Text.AlignVCenter;}
background : Rectangle{
再看color，"#2196F3";radius，border.color:"#1976D2";border.width;}
}
HoverHandler{ id :customMA}
}
}
Item{Layout.fillHeight:true}
}
}

• contentItem：

运行验证步骤

1. 在 Qt Creator 打开项目根目录下的/qml_tooltip/CMakeLists.txt
2. 按 Ctrl+R 或点击 “运行” 按钮启动 Demo。
3. Suspend 在两块矩形上观察延迟与样式效果是否符合预期。

& 重用方向建议

• TinyTooltip.qml： 把 ToolTip 封装成通用组件并提供属性如delay。timeout,meStyle等供外部配置。
• MausArea 替代 HoverHandler： 如果需要点击触发或支持移动端，可用 MouseArea 并监听 mouseEntered / mouseExited 信号。
• Theming 支持： 结合 QML 的 StyleSheet 或 Theme 对象。将颜色方案统一管理，保证跨网站一致性。
• A11y 考虑： 为每个 Tooltip 添加 role=“tooltip” 并使用 Accessible 属性，让屏幕阅读器能够正确读取提示内容。

已验证环境这方面，

• - Qt版本：Qt 5.15 / 6.5 - 操作程序：Windows 10 / macOS 12 / Linux
• - GitHub仓库：QML-Minimal-Demos/qml_tooltip
.