PAYATHON 2026

如何用 Python 检测 Linux GUI 元素并实现光标吸附?

数据小许

推荐先用 AT-SPI 验证控件覆盖范围

建议先用 AT-SPI 获取应用控件的语义信息和矩形范围,再为无法覆盖的标题栏按钮、dock 等目标增加桌面环境专用适配。

X11/EWMH 可以辅助获取窗口信息,但没有标准接口返回关闭、最小化和最大化按钮各自的位置。Wayland 下也可以使用无障碍接口,不过仍需分别验证控件树、全局坐标和系统光标控制。

目标 优先考虑的方式 主要限制
应用内按钮、搜索栏、文本框 AT-SPI 应用必须暴露相应的无障碍对象
应用自己绘制的标题栏按钮 先检查 AT-SPI 取决于 toolkit 和应用实现
window manager 绘制的标题栏按钮 检查其无障碍支持,再考虑专用适配 EWMH 不提供按钮矩形
taskbar/dock 图标 检查对应组件的 AT-SPI 树 取决于桌面组件或 extension 的实现

为什么 X11/EWMH 无法直接定位标题栏按钮?

EWMH 描述窗口层面的属性和请求,例如窗口状态、桌面归属及窗口边框范围。

其中,_NET_FRAME_EXTENTS 的内容为:

_NET_FRAME_EXTENTS, left, right, top, bottom, CARDINAL[4]/32

这四个值表示 window manager 在窗口四周添加的边框宽度,没有描述按钮的数量、排列、尺寸或点击区域。即使知道顶部边框的高度,也无法据此计算关闭按钮的准确位置。EWMH 窗口属性规范

python-xlib 和 ewmh 可以用于枚举 X11 窗口、读取几何信息和状态,但更换封装库不会增加协议本身没有提供的信息。也不能假设每个按钮都是独立的 X11 子窗口:控件可能只是 toolkit 或 window manager 绘制的一部分。

按窗口右上角的固定偏移量计算按钮位置,只适用于已限定桌面环境、主题和缩放配置的适配方案,不能作为通用 Linux GUI 检测方法。

AT-SPI 能否识别关闭、最小化和最大化按钮?

可以尝试。能否识别取决于谁绘制按钮,以及绘制方是否把按钮暴露为无障碍对象。

应用绘制的标题栏

使用 client-side decorations(CSD)时,标题栏控件属于应用界面,可以出现在应用的 AT-SPI 树中。例如,GTK 的 Gtk.WindowControls 用于显示最小化、最大化和关闭按钮,并参与 GTK 的无障碍体系。具体应用是否暴露这些按钮、能否返回有效矩形,仍需实际检查。Gtk.WindowControls 文档

window manager 绘制的标题栏

使用 server-side decorations(SSD)时,按钮由 window manager 或 compositor 绘制,通常不属于应用自己的无障碍子树。

这时应检查装饰绘制方是否另外暴露了无障碍对象。如果没有,遍历应用的 AT-SPI 树也找不到这些按钮,需要针对装饰实现进行适配。GNOME Shell extension 可以作为集成方式之一,但不能假定它天然提供所有标题栏按钮的矩形。

控件矩形与可点击性

AT-SPI 的 Component.get_extents() 可以返回控件的 (x, y, width, height),并允许指定坐标系。文档要求对象同时具有 VISIBLE 和 SHOWING 状态,返回值才有意义。Component.get_extents 文档

识别候选目标时,可以结合 role、状态以及 Action、EditableText 接口判断。不要只看名称是否包含 Close,因为名称可能被本地化,也可能为空。矩形本身也不能证明目标当前未被其他窗口遮挡。

Python 可以怎样读取这些信息?

可以通过 PyGObject 使用 gi.repository.Atspi。已有项目也可能使用 pyatspi,两者都用于访问 AT-SPI,无法自动补齐应用没有暴露的控件。

下面的一次性诊断示例会遍历部分无障碍树,输出具有动作或文本编辑接口的可见控件及其矩形。运行环境需要安装 PyGObject 和 Atspi introspection 数据,并能访问当前桌面会话的无障碍服务。

import gi

gi.require_version("Atspi", "2.0")
from gi.repository import Atspi, GLib


def candidate_rect(node):
    states = node.get_state_set()
    required = (
        Atspi.StateType.VISIBLE,
        Atspi.StateType.SHOWING,
        Atspi.StateType.ENABLED,
    )
    if not all(states.contains(state) for state in required):
        return None

    component = node.get_component_iface()
    if component is None:
        return None

    action = node.get_action_iface()
    editable = node.get_editable_text_iface()
    has_action = action is not None and action.get_n_actions() > 0
    if not has_action and editable is None:
        return None

    rect = component.get_extents(Atspi.CoordType.SCREEN)
    if rect.width <= 0 or rect.height <= 0:
        return None

    return rect.x, rect.y, rect.width, rect.height


desktop = Atspi.get_desktop(0)
stack = [(desktop, 0)] if desktop is not None else []
remaining = 2000  # Diagnostic traversal limit, not an API requirement.

while stack and remaining > 0:
    node, depth = stack.pop()
    remaining -= 1

    try:
        rect = candidate_rect(node)
        if rect is not None:
            print(node.get_role_name(), repr(node.get_name()), rect)
    except GLib.Error:
        pass  # A remote object may disappear during inspection.

    if depth >= 20:
        continue

    try:
        for index in range(node.get_child_count()):
            child = node.get_child_at_index(index)
            if child is not None:
                stack.append((child, depth + 1))
    except GLib.Error:
        continue

这里使用的入口和接口分别是 Atspi.get_desktop()、get_component_iface() 和 Action.get_n_actions()。

这个示例用于检查目标是否暴露,不能完整检测可点击目标。部分可交互控件不符合筛选条件,遍历上限也可能导致目标被遗漏。生产实现应针对当前相关窗口维护候选缓存,通过界面变化事件更新,避免在 MediaPipe 的每一帧中遍历整个桌面。

Wayland 下有哪些额外限制?

AT-SPI 使用独立的无障碍通信机制,在 Wayland 下也可能可用。即使拿到控件对象,也需要确认能否取得可用于桌面光标的全局坐标。

Wayland 的普通客户端不知道自身 surface 的全局位置,也不能直接访问其他客户端的 surface。因此,在某些 toolkit、compositor 和版本组合下,AT-SPI 可以提供窗口内相对位置,却无法提供可靠的屏幕绝对位置。必须在目标环境中验证 CoordType.SCREEN 的返回值,不能仅因调用成功就直接用于吸附。Wayland 协议模型

控制系统光标还需要单独的输入后端。可以评估桌面支持的 org.freedesktop.portal.RemoteDesktop,在用户授权的会话中发送指针事件;具备相应支持时,也可以通过 ConnectToEIS() 使用 libei。具体可用接口取决于 portal 后端及其版本。RemoteDesktop portal 文档

portal 提供输入控制能力,不提供 GUI 按钮列表。NotifyPointerMotionAbsolute() 使用指定屏幕流的逻辑坐标,不能直接假定它与截图像素、MediaPipe 映射坐标或 AT-SPI 坐标相同。

如果 Wayland 环境缺少可靠的全局位置映射,就需要 compositor 或桌面环境协助。对 GNOME 的适配与对其他桌面的适配应分别实现;在 XWayland 中读取 X11 信息也不能覆盖所有原生 Wayland 应用。

如何接入现有的手势光标逻辑?

建议按以下顺序实现:

  1. 先选定一个桌面会话和几种目标应用,分别检查应用内按钮、标题栏按钮、dock 图标是否出现在 AT-SPI 树中。
  2. 验证矩形与实际显示位置一致,再统一 MediaPipe、目标矩形和输入后端的坐标系。
  3. 优先对已验证的控件启用吸附。缺少目标数据时保留普通光标移动,再逐项补充桌面专用适配。
  4. 选择候选目标时,先计算手势映射位置到目标矩形的距离;进入阈值后,将显示光标吸附到矩形中心。
  5. 使用迟滞避免反复吸附和释放,并在目标消失、禁用或窗口布局变化后重新验证。

迟滞可以用两个阈值表达:

enter_radius < exit_radius

未锁定目标时,距离小于 enter_radius 才进入吸附;锁定后,距离大于 exit_radius 才释放。释放判断应使用手势映射得到的未吸附位置。如果使用已经固定在目标中心的系统光标位置,距离会一直很小,导致无法正常解除吸附。

还要检查多显示器偏移、负坐标及 fractional scaling。SHOWING 状态不能替代跨窗口遮挡检查,点击前应确认目标仍然有效。关闭按钮可以采用更保守的候选选择规则,避免在相邻按钮之间跳转。

对于当前项目,先用 X11 验证 AT-SPI 目标检测与吸附逻辑,通常更容易排查坐标问题;如果最终需要支持 Wayland,应尽早独立验证全局坐标和输入后端。窗口控制按钮的完整覆盖仍需要按实际桌面环境补充实现。

备注:内容仅供参考。