本文详解终端如何启用鼠标事件捕获、解析 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 开头）：
立即学习“Python免费学习笔记（深入）”；
# SGR 协议示例（推荐解析方式）： ESC [ <C ; R ; C m # 如 \x1b[<0;23;45M → 左键释放，列23，行45 ESC [ <32;12;8M # 右键按下（32 = 32 + 32，见下表）
其中 < 后数字编码含义（SGR 模式）：
- 0–2: 左/中/右键释放
- 32–34: 左/中/右键按下
- 64–66: 滚轮上/中/下（部分终端）
- 35: 移动时按键未按下（即悬停移动）
- 96–98: 滚轮（带 Shift/Ctrl/Alt 修饰）
Python 中可实时读取 stdin 字节流并解析：
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'<':
# 解析 SGR 格式：<B;Y;X
parts = data[3:-1].split(b';')
if len(parts) == 3:
btn, row, col = map(int, parts)
print(f"Mouse at (col={col}, row={row}), button={btn}")
finally:
termios.tcsetattr(sys.stdin, termios.TCSADRAIN, old_settings)
if __name__ == "__main__":
enable_mouse()
try:
read_mouse_event()
finally:
disable_mouse()? Textual 的实现逻辑（为何能精准悬停？）
Textual 并不依赖“截图识别”或“像素级定位”，而是采用双层映射策略：
- 布局建模：渲染时构建完整的 WidgetTree，精确记录每个控件（如 Button）在虚拟终端坐标系中的 region（左/上/宽/高）；
- 事件匹配：收到鼠标坐标 (x, y) 后，遍历 widget 区域树，用 region.contains(x, y) 判断是否悬停；
- 增量重绘：仅重绘状态变更的 widget，避免全屏刷新。
因此，鼠标坐标本身精度有限（字符单元格级别），但结合布局模型即可实现像素级语义悬停——这也是终端 UI 库的通用范式。
✅ 总结与最佳实践
- ✅ 优先使用 CSI ? 1006 h/l（SGR 协议），兼容性与可靠性优于 1000；
- ✅ 必须配置 stdin 为 raw 模式，否则无法捕获无回车的 ESC 序列；
- ✅ 坐标系原点为左上角 (1,1)，列（x）在前，行（y）在后；
- ❌ 不要尝试用 \x1b[?38h 等过时/无效序列——它们不属于标准鼠标协议；
- ? 生产环境推荐直接使用 Textual、Rich 或 prompt_toolkit，它们已封装完整协议适配与错误处理。
