事件监听

基本用法

使用 @bot.handle() 装饰器注册事件处理函数：

from pywechat_libencode import WeChat, events

bot = WeChat(version="4.1.8.67")

# 监听所有消息
@bot.handle()
def on_all(bot, data):
    print(data)

# 监听指定事件
@bot.handle(events=events.TEXT_MESSAGE)
def on_text(bot, data):
    print(data)

# 监听多个事件
@bot.handle(events=[events.TEXT_MESSAGE, events.IMAGE_MESSAGE])
def on_text_or_image(bot, data):
    print(data)

bot.run()

事件类型列表

事件	常量	值	说明
全部信息	ALL_MESSAGE	-1	监听所有类型消息
用户退出登录	USER_LOGOUT_MESSAGE	0	用户主动退出
文本消息	TEXT_MESSAGE	1	普通文本消息
图片消息	IMAGE_MESSAGE	3	图片消息
好友减少	FRIEND_DECREASE_MESSAGE	14	被删除或删除好友
好友增加	FRIEND_INCREASE_MESSAGE	15	新增好友
语音消息	VOICE_MESSAGE	34	语音消息
好友请求	FRIEND_REQUEST_MESSAGE	37	收到好友申请
名片消息	CARD_MESSAGE	42	个人名片消息
视频消息	VIDEO_MESSAGE	43	视频消息
表情消息	EMOJI_MESSAGE	47	表情包消息
位置消息	LOCATION_MESSAGE	48	位置分享消息
XML卡片消息	XML_CARD_MESSAGE	49	文件/红包/转账/小程序/公众号文章
语音/视频电话	VOIP_MESSAGE	50	语音视频通话邀请
同步消息	SYNC_MESSAGE	51	消息同步
用户登录	USER_LOGIN_MESSAGE	1002	用户登录成功
聊天对象变化	CHAT_CHANGE_MESSAGE	1005	当前聊天窗口变化
登录二维码	LOGIN_QR_CODE_MESSAGE	1007	登录二维码生成
安全退出	SECURITY_LOGOUT_MESSAGE	1028	手机退出/异常退出
系统消息	SYSTEM_MESSAGE1	10000	系统通知消息
微信连接成功	WECHAT_CONNECT_MESSAGE	10001	微信连接建立
系统消息(撤回/拍一拍)	SYSTEM_MESSAGE2	10002	撤回消息/拍一拍等

完整事件处理示例

from pywechat_libencode import WeChat4, events

bot = WeChat4(version="4.1.8.67")

@bot.handle(events=events.TEXT_MESSAGE)
def on_text(bot: WeChat4, data: dict):
    """处理文本消息"""
    content = data["content"]["String"]
    from_wxid = data["fromUserName"]["String"]
    account_wxid = data["account_wxid"]

    # 跳过自己发出的消息
    if from_wxid == account_wxid:
        return

    # 跳过群消息
    if from_wxid.endswith("@chatroom"):
        return

    # 自动回复
    bot.send_text(from_wxid, f"收到: {content}")

@bot.handle(events=events.FRIEND_REQUEST_MESSAGE)
def on_friend_request(bot: WeChat4, data: dict):
    """自动通过好友验证"""
    v3 = data["v3"]
    v4 = data["v4"]
    scene = data["scene"]
    bot.verify_friend(v3=v3, v4=v4, scene=scene)

@bot.handle(events=events.IMAGE_MESSAGE)
def on_image(bot: WeChat4, data: dict):
    """处理图片消息"""
    print(f"收到图片: {data}")

@bot.handle(events=events.USER_LOGIN_MESSAGE)
def on_login(bot: WeChat4, data: dict):
    """登录成功回调"""
    print("登录成功！")
    bot.init()  # 初始化联系人和群列表

bot.run()

WeChat3 消息数据格式

WeChat3 版本的消息数据字段名与 WeChat4 略有不同：

@bot.handle(events=events.TEXT_MESSAGE)
def on_text(bot: WeChat3, data: dict):
    content = data["Content"]["String"]       # 注意首字母大写
    from_wxid = data["FromUserName"]["String"]  # 注意首字母大写
    self_wxid = data["from"]

WeChat4 消息数据格式

@bot.handle(events=events.TEXT_MESSAGE)
def on_text(bot: WeChat4, data: dict):
    content = data["content"]["String"]         # 首字母小写
    from_wxid = data["fromUserName"]["String"]  # 驼峰命名
    account_wxid = data["account_wxid"]