如何在PyQt5中捕获QListWidget鼠标悬停事件以显示工具提示

要实现PyQt5中QListWidget列表项鼠标悬停（无需选中）时显示工具提示，有两种简单实用的方式，你可以根据需求选择：

方法1：直接为每个列表项设置静态工具提示 #

这是最直接的方案，适合工具提示内容固定的场景。在添加列表项时，直接调用QListWidgetItem的setToolTip()方法即可：

import sys
from PyQt5.QtWidgets import (QApplication, QWidget, QListWidget, QVBoxLayout, QListWidgetItem)

class HoverTooltipDemo(QWidget):
    def __init__(self):
        super().__init__()
        self.init_ui()

    def init_ui(self):
        layout = QVBoxLayout()
        self.list_widget = QListWidget()
        
        # 添加列表项并设置悬停工具提示
        for idx in range(5):
            item_text = f"列表项 {idx+1}"
            item = QListWidgetItem(item_text)
            # 为当前项设置悬停时显示的工具提示
            item.setToolTip(f"这是「{item_text}」的详细说明")
            self.list_widget.addItem(item)
        
        layout.addWidget(self.list_widget)
        self.setLayout(layout)
        self.setWindowTitle("QListWidget悬停提示")
        self.resize(350, 250)

if __name__ == "__main__":
    app = QApplication(sys.argv)
    window = HoverTooltipDemo()
    window.show()
    sys.exit(app.exec_())

运行代码后，鼠标悬停在任意列表项上就会弹出你设置的提示，无需选中项就能触发。

方法2：通过itemEntered信号动态生成工具提示 #

如果你的工具提示内容需要动态生成（比如根据项的实时状态、从外部数据源获取内容），可以利用QListWidget的itemEntered信号——这个信号会在鼠标进入某个列表项时自动触发，我们可以在对应的槽函数里动态生成提示内容：

import sys
from PyQt5.QtWidgets import (QApplication, QWidget, QListWidget, QVBoxLayout)

class DynamicHoverTooltipDemo(QWidget):
    def __init__(self):
        super().__init__()
        self.init_ui()

    def init_ui(self):
        layout = QVBoxLayout()
        self.list_widget = QListWidget()
        
        # 添加测试列表项
        for idx in range(5):
            self.list_widget.addItem(f"动态内容项 {idx+1}")
        
        # 连接itemEntered信号到自定义槽函数
        self.list_widget.itemEntered.connect(self.show_dynamic_tooltip)
        
        layout.addWidget(self.list_widget)
        self.setLayout(layout)
        self.setWindowTitle("动态悬停提示")
        self.resize(350, 250)

    def show_dynamic_tooltip(self, item):
        # 这里可以写动态生成提示内容的逻辑，比如根据item文本计算、查询数据等
        dynamic_tip = f"动态提示：当前项文本是「{item.text()}」，索引为{self.list_widget.row(item)}"
        # 设置当前项的工具提示（也可以直接用QToolTip.showText()手动显示）
        item.setToolTip(dynamic_tip)

if __name__ == "__main__":
    app = QApplication(sys.argv)
    window = DynamicHoverTooltipDemo()
    window.show()
    sys.exit(app.exec_())

小提示 #

• 两种方法可以同时使用，不会影响你之前实现的「选中项显示提示」的逻辑。
• 如果发现itemEntered信号没触发，检查一下是否开启了鼠标追踪：self.list_widget.setMouseTracking(True)（不过QListWidget默认已经处理了项的鼠标进入事件，一般不需要手动设置）。

内容的提问来源于stack exchange，提问作者Propy Propy