如何在 Python 终端中通过 ANSI 转义序列获取鼠标悬停位置-Python教程-PHP中文网

如何在 Python 终端中通过 ANSI 转义序列获取鼠标悬停位置

本文详解终端如何启用鼠标事件捕获、解析 ansi 鼠标坐标报文，并结合 textual 等库实现精准悬停检测——核心在于启用 x11/xterm 鼠标协议并实时解析 stdin 流中的坐标数据。

本文详解终端如何启用鼠标事件捕获、解析 ansi 鼠标坐标报文，并结合 textual 等库实现精准悬停检测——核心在于启用 x11/xterm 鼠标协议并实时解析 stdin 流中的坐标数据。

要在终端中实现鼠标悬停位置检测（如 Textual 中按钮高亮），关键并非“读取屏幕像素”，而是启用终端的鼠标事件报告模式，并监听标准输入流（stdin）中由终端主动发送的 ANSI 鼠标坐标报文。

✅ 启用鼠标事件报告（ANSI Mouse Protocol）

现代终端（如 xterm、kitty、gnome-terminal、alacritty）支持多种鼠标协议，最常用的是 X11/Xterm 鼠标协议（CSI ? 1000 h） 和增强型 SGR 鼠标协议（CSI ? 1006 h）。需向终端输出启用序列：

import sys

# 启用 SGR 鼠标协议（推荐：支持 Unicode 坐标、更可靠）
sys.stdout.write("\x1b[?1006h")
sys.stdout.flush()

# （可选）同时启用普通 X11 协议（兼容旧终端）
# sys.stdout.write("\x1b[?1000h")
# sys.stdout.flush()

⚠️ 注意：

print() 默认带换行和缓冲，必须使用 sys.stdout.write() + flush()；
序列仅对当前终端会话生效，退出前建议关闭（"\x1b[?1006l"）；
并非所有终端默认支持——kitty、wezterm、foot 原生支持；macOS Terminal 需手动启用；Windows Terminal v1.15+ 支持 1006。

? 解析鼠标事件报文

启用后，当鼠标移动或点击时，终端会向 stdin 发送形如以下的 ESC 序列（以 ESC [ M 开头）：

testing-python

使用pytest编写和评估有效的Python测试。适用于编写测试、审查测试代码、调试测试失败或提高测试覆盖率。

下载

# SGR 协议示例（推荐解析方式）：
ESC [ <c r c m esc><p>其中 </p>
<ul>
<li>0–2: 左/中/右键释放  </li>
<li>32–34: 左/中/右键按下  </li>
<li>64–66: 滚轮上/中/下（部分终端）  </li>
<li>35: 移动时按键未按下（即悬停移动）  </li>
<li>96–98: 滚轮（带 Shift/Ctrl/Alt 修饰）</li>
</ul>
<p>Python 中可实时读取 stdin 字节流并解析：</p>
<pre class="brush:php;toolbar:false;">import sys
import tty
import termios

def enable_mouse():
    sys.stdout.write("\x1b[?1006h")
    sys.stdout.flush()

def disable_mouse():
    sys.stdout.write("\x1b[?1006l")
    sys.stdout.flush()

def read_mouse_event():
    # 设置为原始模式（禁用行缓冲）
    old_settings = termios.tcgetattr(sys.stdin)
    try:
        tty.setraw(sys.stdin.fileno())
        while True:
            b = sys.stdin.buffer.read(1)
            if b == b'\x1b' and sys.stdin.buffer.read(1) == b'[':
                # 读取后续字符直到 'M'
                data = b'\x1b['
                while True:
                    c = sys.stdin.buffer.read(1)
                    data += c
                    if c == b'M':
                        break
                if len(data) >= 6 and data[2:3] == b'<h3>? Textual 的实现逻辑（为何能精准悬停？）</h3><p>Textual 并不依赖“截图识别”或“像素级定位”，而是采用<strong>双层映射策略</strong>：</p><ol>
<li>
<strong>布局建模</strong>：渲染时构建完整的 WidgetTree，精确记录每个控件（如 Button）在虚拟终端坐标系中的 region（左/上/宽/高）；</li>
<li>
<strong>事件匹配</strong>：收到鼠标坐标 (x, y) 后，遍历 widget 区域树，用 region.contains(x, y) 判断是否悬停；</li>
<li>
<strong>增量重绘</strong>：仅重绘状态变更的 widget，避免全屏刷新。</li>
</ol><p>因此，<strong>鼠标坐标本身精度有限（字符单元格级别），但结合布局模型即可实现像素级语义悬停</strong>——这也是终端 UI 库的通用范式。</p><h3>✅ 总结与最佳实践</h3>