QML ToolTip 组件：延迟提示与自定义外观

ToolTip 是 QML 里给控件加悬停提示的附加类型。这篇文章讲基础用法和自定义样式。

• 基础 Tooltip --- 延迟、超时与悬停触发
• 自定义样式 --- 用 contentItem 和 background 改外观

基础 Tooltip

悬停在蓝色矩形上，500ms 后弹出提示，5s 后自动消失。

演示代码

import QtQuick
import QtQuick.Controls
import QtQuick.Layouts

FadeInAnimation {
    ColumnLayout {
        anchors.fill: parent
        anchors.margins: 20
        spacing: 15

        TitleSeparator {
            title: "基础 Tooltip"
            description: "使用 ToolTip 附加类型在悬停时展示提示，可设置延迟与超时时间"
        }

        RowLayout {
            Layout.preferredHeight: 120
            Layout.alignment: Qt.AlignHCenter
            spacing: 20

            Rectangle {
                Layout.preferredWidth: 120
                Layout.preferredHeight: 40
                color: "lightblue"
                radius: 4

                Text {
                    anchors.centerIn: parent
                    text: "基础 Tooltip"
                }

                ToolTip {
                    text: "这是一个基础的tooltip示例"
                    delay: 500
                    timeout: 5000
                    visible: basicMA.hovered
                }

                HoverHandler {
                    id: basicMA
                }
            }
        }

        Item { Layout.fillHeight: true }
    }
}

关键逻辑解析

• ToolTip 作为附加类型直接写在目标控件内部。
• visible: basicMA.hovered 绑定到 HoverHandler 的 hovered 属性，控制显示时机。
• delay: 500 表示悬停 500ms 后才显示；timeout: 5000 表示显示 5s 后自动隐藏。

适用场景：按钮提示、图标说明、表单字段解释。

自定义样式

悬停在绿色矩形上，显示蓝色背景、白色粗体文字的 Tooltip。

演示代码

import QtQuick
import QtQuick.Controls
import QtQuick.Layouts

FadeInAnimation {
    ColumnLayout {
        anchors.fill: parent
        anchors.margins: 20
        spacing: 15

        TitleSeparator {
            title: "自定义样式"
            description: "通过自定义 contentItem 与 background 定制 Tooltip 的文字与背景外观"
        }

        RowLayout {
            Layout.preferredHeight: 120
            Layout.alignment: Qt.AlignHCenter
            spacing: 20

            Rectangle {
                Layout.preferredWidth: 120
                Layout.preferredHeight: 40
                color: "lightgreen"
                radius: 4

                Text {
                    anchors.centerIn: parent
                    text: "自定义样式"
                }

                ToolTip {
                    id: customTooltip
                    text: "这是一个自定义样式的tooltip"
                    delay: 500
                    timeout: 5000
                    visible: customMA.hovered

                    contentItem: Text {
                        text: customTooltip.text
                        font.bold: true
                        color: "white"
                    }

                    background: Rectangle {
                        color: "#2196F3"
                        radius: 6
                        border.color: "#1976D2"
                        border.width: 1
                    }
                }

                HoverHandler {
                    id: customMA
                }
            }
        }

        Item { Layout.fillHeight: true }
    }
}

关键逻辑解析

• contentItem 替换 Tooltip 的文本区域，可以改字体、颜色、对齐方式。
• background 替换 Tooltip 的背景，支持圆角、边框、渐变色。
• 文字内容仍通过 text 属性设置，contentItem 里引用 customTooltip.text。

适用场景：统一 UI 风格、深色模式提示、品牌色提示框。

运行验证

1. Qt Creator 打开 qml_tooltip/CMakeLists.txt；
2. 按 Ctrl+R 运行；
3. 分别悬停在两个矩形上，观察延迟、样式变化。

扩展复用方向

• 把 ToolTip 封装成独立组件，统一项目内的提示风格。
• 用 MouseArea 代替 HoverHandler，支持点击触发提示。

---

已验证环境：

• Qt 版本：Qt 6.8.2、Qt 6.11.1
• 操作系统：Windows 11
• GitHub：QML-Minimal-Demos/qml_tooltip