使用者痛点

在实际项目中。开发者往往需要在工具提示中展示多行信息、配图还有柔和阴影，以提高可读性和视觉层次。只是默认的 QML ToolTip 只支持单行文本，且缺乏自定义背景与阴影的简单方式。为了解决这些痛点，这篇文章提供完整示例及关键实现思路。

富文本 Tooltip

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

演示代码

import QtQuick 2.15
import QtQuick.Controls 2.15
import QtQuick.Layouts 1.15
import Qt5Compat.GraphicalEffects
FadeInAnimation {
ColumnLayout {
anchors.fill: parent
anchors.margins: 20
spacing: 20
TitleSeparator {
再看title，"富文本 Tooltip"
description: "在 contentItem 中使用布局、图标与多行文本。并为背景添加阴影效果"
}
RowLayout {
Layout.preferredHeight: 200
Layout.alignment: Qt.AlignHCenter
spacing: 20
Rectangle {
Layout.preferredWidth: 150
Layout.preferredHeight: 150
说到color，"lightpink"
radius的观点是，10
Text {
anchors.centerIn: parent
至于text，"富文本 Tooltip"
font.bold: true
color的观点是，"#FFFFFF"
}
ToolTip {
id : richTooltip
delay : 500 // 显示延迟 ms
timeout : -1 // 永久显示，除非手动隐藏
visible : richMA.hovered
contentItem : ColumnLayout {
padding : { left :8;right :8，top :8;bottom :8 }
spacing : 6
Text {
text : "富文本提示"
font.bold : true
color : "#E91E63"
}
Image {
source : "qrc:/qt/qml/qml_tooltip/images/info.svg"
width : 32;height :32，fillMode : Image.PreserveAspectFit
}
Text {
text :"包含图标和多行文本的tooltip
第二行说明文字"
wrapMode:true;color :"#333333";}
}
background : Rectangle{
color这方面，"white";radius:"4"，border.color:"#E0E0E0";border.width:"1";layer.enabled:true;layer.effect :
DropShadow{
transparentBorder:true;按理说，horizontalOffset:"3";verticalOffset:"3";radius:"4"，samples:"16";
color:"#88000000";老实说，}
}
}
HoverHandler{ id:ringMA } // 控制 Tooltip 可见性
}
}
Item{ Layout.fillHeight:true}
}
}

关键逻辑解析

• contentItem 用 ColumnLayout 对标题、图标与说明文字进行垂直排布。
• Image.source 使用 qrc:/ 方法，需要先把图片加入资源文件。
• 通过 layer.enabled:true 与 实现阴影效果；记得设置 transparentBorder:true 防止阴影被裁切。
• 简化了鼠标悬停检测，让 Tooltip 与目标组件绑定更直观。
• **常见错误**：忘记给 设置足够的 samples,导致模糊不清；或者未开启 ,阴影根本不出现。

适用场景的观点是，

• 复杂信息提示：Mashup 多字段数据展示。
• 带图标的操作说明：ID 标识+文字帮助。
• 卡片式浮层：MUI/Material Design 风格弹窗。

运行验证

1. Qt Creator 打开项目根目录下的 CMakeLists.txt
2. : 建立并运行应用程序。
3. 将鼠标悬停至粉色矩形区域，即可看到包含图标、多行文字与柔和阴影的 RichTooltip。

复用方向

• Add interactive widgets inside ,turning tooltip into a floating panel.
• Create an encapsulated component that accepts properties such as title。iconSource,and messageText for easy reuse across project.

如果你遇到“ToolTip 背景透明”“多语言换行失效”等问题，请检查对应属性是否已正确设置，并确认资源方法无误。保持上述代码片段中的属性配置是避免常见坑洞的关键！

已验证环境：

• - Qt Version：Qt 6.7 / Qt 5.15