chatautox

消息列表

聊天窗口内的消息气泡列表与左侧 UIA 会话列表不同：通过 WinAuto.im_client() 创建 IM 客户端（默认内置 IM 适配器），再调用 GetNextNewMessage / GetNewMessage 等读取 Message。

完整分支处理（笔记/合并/小程序/下载等）见 消息处理指南。

API 参考

✨im_client

from chatautox import WinAuto

# 流程绑定头 + im_client（控件浏览器拾取非 IM 主窗口时，会自动查找 IM 主窗口）
# hwnd = WinAuto.find_main_hwnd(WIN_CLASS, WIN_TITLES, ...)
# auto = WinAuto(hwnd, mode='uia')
auto.activate()
time.sleep(0.3)
im = auto.im_client(debug=False, auto_listen=False)

参数（im_client）：

参数名类型默认值描述
clientclass / str / NoneNoneNone→内置 IM 适配器；或 'pkg.Module.Client'
debugboolFalseIM 客户端调试日志
auto_listenboolFalse是否启动后台子窗口监听
refreshboolFalseTrue 强制重建客户端

说明：默认内置 IM 适配器 时若 auto 绑定的不是 IM 主窗口（如控件浏览器），会自动查找 IM 主窗口；不传拾取到的 Qt 类名，保证与直接构造 IM 客户端行为一致。

返回值：IM 客户端实例（为内置 IM 客户端实例）。

消息项字段（Message）

字段说明
msg.attrfriend=对方发送，self=自己发送，system/time/tickle=系统或时间行
msg.typetext / image / video / file / voice / note / merge / link / quote / miniapp 等
msg.content气泡摘要文字
msg.sender发送者（群聊需 fetch_sender=True）

✨GetNextNewMessage（推荐：轮询新消息列表）

from chatautox import WinAuto
from chatautox.param import WxResponse

auto = WinAuto.from_main_hwnd(WIN_CLASS, WIN_TITLES[0], mode='uia')
auto.activate()
time.sleep(0.3)
im = auto.im_client(debug=False, auto_listen=False)

def on_message(msg):
    print(f"[{msg.attr}] type={msg.type} sender={msg.sender} content={msg.content}")
    if msg.attr == 'friend':
        pass  # 仅处理对方发来的
    elif msg.attr == 'self':
        pass  # 自己发的

while True:
    batch = im.GetNextNewMessage(
        filter_mute=False,
        fetch_sender=False,      # 群聊 True 补全 sender
        callback=on_message,     # 每条解析完立刻回调
        use_profile_sender=False,
    )
    # batch = {'chat_name': str, 'chat_type': 'friend'|'group', 'msg': [Message, ...]}
    if batch.get('msg'):
        print(batch.get('chat_name'), batch.get('chat_type'), len(batch.get('msg') or []))
    time.sleep(1)

首帧基线：循环内第一次调用通常返回空 batch（不交付历史消息），之后才会在侧栏未读或当前聊天新消息时交付。单次调用无法持续监听。

# 单次探测（非持续监听）
batch = im.GetNextNewMessage(filter_mute=False, callback=on_message)
msgs = batch.get('msg') or []

参数：

参数名类型默认值描述
filter_muteboolFalse是否跳过免打扰会话
fetch_senderboolFalse群聊是否补全 msg.sender
callbackCallableNone每条消息解析后立即调用 callback(msg)
use_profile_senderboolFalseTrue 优先资料卡识别发送人

返回值：

  • 类型：dict
  • 字段：chat_name、chat_type、msg（List[Message]）

✨GetNextUnreadBarMessages

处理当前聊天内「N条新消息」跳转条（不会被 GetNextNewMessage 自动处理）。

def on_message(msg):
    print(msg.attr, msg.type, msg.content)

batch = im.GetNextUnreadBarMessages(fetch_sender=False, callback=on_message)
print('跳转条:', batch.get('chat_name'), len(batch.get('msg') or []))

返回值：同 GetNextNewMessage；无跳转条时 {}

✨GetAllMessage / ✨GetNewMessage

# 需已打开目标会话（如 im.ChatWith('示例会话')）
msgs = im.GetAllMessage(fetch_sender=False)
for msg in msgs:
    print(msg.attr, msg.type, msg.sender, msg.content)

new_msgs = im.GetNewMessage()  # 当前会话增量；切换 chat 后首轮为空
方法说明返回
GetAllMessage(fetch_sender=…)当前聊天全部消息List[Message]
GetNewMessage()当前聊天增量新消息（首帧建立基线，不输出历史）List[Message]
ChatInfo()当前会话名与类型dict
ChatWith(name)切换到指定会话None
# 切换会话并查看当前聊天信息
im.ChatWith('示例会话')
time.sleep(0.5)
print(im.ChatInfo())   # {'chat_name': '...', 'chat_type': 'friend', ...}

✨GetNextListenChatMessage / ✨AddListenChat

独立聊天子窗口（双击会话弹出）的消息列表：

im.AddListenChat('示例会话', callback=on_message)
im.StartListening()

# 或同步轮询（可与 GetNextNewMessage 同脚本交错）
batch = im.GetNextListenChatMessage(nickname='示例会话', callback=on_message)

✨MakeMessageAnchor / ✨ResolveMessageByAnchor（消息锚点）

处理 GetNextNewMessage callback 里的 msg 时，可先生成锚点，后续即使消息因滚动、Recycler 重绘导致 runtimeid 变化或位置移动，仍可在当前视口内按锚点找回同一条并继续操作（下载、点击、转文字等）。

原理（与 GetNextNewMessage 内部一致）：

字段说明
key交付键 = 内容指纹（chat + type + attr + sender + 正文 + 同屏同文案序号）+ runtimeid
stable_key仅内容指纹，不含 runtimeid（UI 重绘后 rid 会变）
hint_rid创建时的 msg.id（ListItem runtimeid），多条同指纹时用于消歧
summary人类可读摘要，调试打印用

runtimeid 在重绘/切会话后会变，不要只靠 GetMessageById(rid) 长期追踪；应用 MakeMessageAnchor + ResolveMessageByAnchor。

from chatautox import WinAuto

auto = WinAuto.from_main_hwnd(WIN_CLASS, WIN_TITLES[0], mode='uia')
auto.activate()
time.sleep(0.3)
im = auto.im_client(debug=False, auto_listen=False)

_last_anchor = None

def on_message(msg):
    global _last_anchor
    _last_anchor = im.MakeMessageAnchor(msg)
    print('[anchor]', _last_anchor['summary'])
    print('  key=', _last_anchor['key'])

batch = im.GetNextNewMessage(filter_mute=False, callback=on_message)
# ... 中间可能滚动聊天区、做其它 UI 操作 ...

msg = im.ResolveMessageByAnchor(_last_anchor)
if msg is None:
    print('视口内未找到（可能已滚出屏幕）')
else:
    print('找回:', msg.attr, msg.type, msg.content)
    msg.roll_into_view()
    # msg.download() / auto.click_bubble(msg.control) 等

WinAuto 等价调用：auto.make_msg_anchor(msg) / auto.resolve_msg_by_anchor(anchor)。

按 type 遍历消息列表示例

详见 消息处理指南 — 按 type 完整分支示例。

上一页列表与会话下一页控件别名