Kivy是跨平台的Python GUI开发框架，在开发桌面端应用时，鼠标悬停检测是常见的交互需求，collide_point()是Kivy控件内置的用于判断坐标点是否在控件范围内的方法，但显示缩放场景下直接使用该方法很容易出现检测偏差。
collide_point()基础用法
collide_point()是Kivy中所有控件都继承自Widget类的方法，接收两个参数分别是x坐标和y坐标，返回布尔值表示传入的坐标点是否在当前控件的矩形范围内。下面是一个简单的按钮悬停检测基础示例：
from kivy.app import App
from kivy.uix.button import Button
from kivy.core.window import Window
class HoverButton(Button):
def __init__(self, **kwargs):
super().__init__(**kwargs)
self.background_normal = '' # 清除默认背景
self.background_color = (0.2, 0.6, 0.8, 1) # 默认背景色
def on_mouse_pos(self, window, pos):
# pos是鼠标当前坐标，格式为(x, y)
if self.collide_point(*pos):
# 鼠标在按钮范围内，修改背景色
self.background_color = (0.4, 0.8, 1, 1)
else:
# 鼠标不在按钮范围内，恢复默认背景色
self.background_color = (0.2, 0.6, 0.8, 1)
class HoverApp(App):
def build(self):
btn = HoverButton(text='悬停测试按钮', size_hint=(None, None), size=(200, 50), pos=(100, 100))
# 绑定鼠标移动事件
Window.bind(mouse_pos=btn.on_mouse_pos)
return btn
if __name__ == '__main__':
HoverApp().run()
显示缩放导致的问题
当系统开启显示缩放（比如Windows系统设置125%、150%缩放）或者应用运行在高DPI屏幕上时，Kivy获取到的鼠标原始坐标和实际控件的逻辑坐标会存在比例偏差。因为显示缩放会让系统对界面元素进行缩放绘制，控件的pos和size属性是逻辑坐标，而鼠标事件的pos是物理屏幕坐标，两者的比例和缩放比例不一致，直接把鼠标物理坐标传入collide_point()就会导致检测错误。
比如系统设置150%缩放，鼠标物理坐标是(300, 300)，对应的逻辑坐标应该是(200, 200)，如果直接传入(300, 300)到collide_point()，而控件逻辑位置是(200, 200)，尺寸是(100, 100)，那么就会判断为不在范围内，实际鼠标已经在控件上方。
坐标转换解决方案
解决这个问题的核心是获取当前的显示缩放比例，把鼠标的物理坐标转换为Kivy的逻辑坐标，再传入collide_point()方法。Kivy的Window对象提供了density属性，这个属性就是当前的显示缩放比例，我们可以用这个属性来做坐标转换。
修改后的悬停检测代码示例如下：
from kivy.app import App
from kivy.uix.button import Button
from kivy.core.window import Window
class ScaledHoverButton(Button):
def __init__(self, **kwargs):
super().__init__(**kwargs)
self.background_normal = ''
self.background_color = (0.2, 0.6, 0.8, 1)
def on_mouse_pos(self, window, pos):
# 获取当前显示缩放比例
scale = Window.density
# 将鼠标物理坐标转换为逻辑坐标
logical_x = pos[0] / scale
logical_y = pos[1] / scale
# 使用转换后的逻辑坐标进行碰撞检测
if self.collide_point(logical_x, logical_y):
self.background_color = (0.4, 0.8, 1, 1)
else:
self.background_color = (0.2, 0.6, 0.8, 1)
class ScaledHoverApp(App):
def build(self):
btn = ScaledHoverButton(text='缩放适配悬停按钮', size_hint=(None, None), size=(200, 50), pos=(100, 100))
Window.bind(mouse_pos=btn.on_mouse_pos)
return btn
if __name__ == '__main__':
ScaledHoverApp().run()
注意事项
- Window.density属性在应用启动后才会被正确赋值，不要在应用初始化阶段过早获取这个属性，否则可能得到默认值1.0，导致转换错误。
- 如果应用同时支持多屏幕，不同屏幕可能有不同的缩放比例，这种情况下需要额外处理屏幕坐标映射，不过大部分桌面场景下单屏幕使用Window.density已经足够。
- 除了collide_point()，Kivy还有collide_widget()方法用于判断两个控件是否碰撞，同样的逻辑缩放场景下也需要做坐标转换后再使用。
通过上述坐标转换的方法，就可以在显示缩放的场景下，让collide_point()方法正确实现鼠标悬停检测，避免坐标偏差带来的交互问题。
Kivycollide_point鼠标悬停检测显示缩放坐标转换修改时间：2026-06-23 16:33:31