QML ToolTip 组件：图标、多行文本与阴影

ToolTip 的 contentItem 可以塞入完整布局。这篇文章做一个带图标、多行文本和阴影的富文本提示。

富文本 Tooltip

悬停在粉色矩形上，显示带图标、多行文本和阴影的 Tooltip。

演示代码

import QtQuick
import QtQuick.Controls
import QtQuick.Layouts
import Qt5Compat.GraphicalEffects

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

        TitleSeparator {
            title: "富文本 Tooltip"
            description: "在 contentItem 中使用布局、图标与多行文本，并为背景添加阴影效果"
        }

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

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

                Text {
                    anchors.centerIn: parent
                    text: "富文本 Tooltip"
                }

                ToolTip {
                    id: richTooltip
                    delay: 500
                    timeout: 5000
                    visible: richMA.hovered

                    contentItem: ColumnLayout {
                        Text {
                            text: "富文本提示"
                            font.bold: true
                            color: "#E91E63"
                        }
                        Image {
                            Layout.preferredWidth: 32
                            Layout.preferredHeight: 32
                            source: "qrc:/qt/qml/qml_tooltip/images/info.svg"
                        }
                        Text {
                            text: "包含图标和多行文本的tooltip"
                            color: "#333333"
                        }
                    }

                    background: Rectangle {
                        color: "#FFFFFF"
                        radius: 8
                        border.color: "#E0E0E0"
                        border.width: 1

                        layer.enabled: true
                        layer.effect: DropShadow {
                            transparentBorder: true
                            horizontalOffset: 2
                            verticalOffset: 2
                            radius: 8.0
                            samples: 17
                            color: "#80000000"
                        }
                    }
                }

                HoverHandler {
                    id: richMA
                }
            }
        }

        Item { Layout.fillHeight: true }
    }
}

关键逻辑解析

• contentItem 用 ColumnLayout 组合标题、图标和说明文字。
• Image 的 source 使用 qrc:/ 资源路径，图片需提前加入资源文件。
• 背景通过 layer.enabled + DropShadow 实现阴影，需要导入 Qt5Compat.GraphicalEffects。
• transparentBorder: true 避免阴影被裁切。

适用场景：复杂信息提示、带图标的操作说明、卡片式浮层。

运行验证

1. Qt Creator 打开 qml_tooltip/CMakeLists.txt；
2. 按 Ctrl+R 运行；
3. 悬停在粉色矩形上，观察富文本、图标和阴影效果。

扩展复用方向

• 在 contentItem 里加 Slider 或 Button，做成可交互的浮层。
• 封装成 InfoTooltip 组件，传入标题、图标、说明文字即可复用。

---

已验证环境：

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