ItChat-UOS API详解：从基础到高级的完整函数参考手册-CSDN博客

ItChat-UOS API详解：从基础到高级的完整函数参考手册

【免费下载链接】ItChat-UOS 复活Itchat,你只需要 pip install itchat-uos 项目地址: https://gitcode.com/gh_mirrors/it/ItChat-UOS

ItChat-UOS 是一个强大的Python微信个人号接口库，通过使用统信UOS的网页版微信协议，让你能够轻松实现微信自动化操作。这个完整的API参考手册将为你详细介绍ItChat-UOS的所有核心功能和使用方法，帮助你从基础入门到高级应用全面掌握这个强大的微信自动化工具。🚀

📋 核心功能概述

ItChat-UOS提供了全面的微信自动化功能，包括消息收发、联系人管理、群聊操作等。通过简单的Python代码，你可以实现微信机器人、自动化客服、消息监控等多种应用场景。

核心模块结构

ItChat-UOS采用模块化设计，主要包含以下核心模块：

登录模块 (itchat/components/login.py)：处理微信登录、二维码生成、会话保持等
联系人模块 (itchat/components/contact.py)：管理好友、群聊、公众号等联系人信息
消息模块 (itchat/components/messages.py)：处理消息的发送和接收
热重载模块 (itchat/components/hotreload.py)：实现登录状态持久化
注册模块 (itchat/components/register.py)：管理消息处理器注册和运行

🔐 登录与认证API

1. 自动登录函数

itchat.auto_login(hotReload=False, statusStorageDir='itchat.pkl', 
                  enableCmdQR=False, picDir=None, qrCallback=None,
                  loginCallback=None, exitCallback=None)

参数说明：

hotReload：是否启用热重载功能，避免重复扫码
statusStorageDir：登录状态存储文件路径
enableCmdQR：在命令行显示二维码，可设置正负值调整显示效果
picDir：二维码图片保存目录
qrCallback：二维码回调函数，接收uuid、status、qrcode参数
loginCallback：登录成功后的回调函数
exitCallback：退出登录时的回调函数

使用示例：

# 基础登录
itchat.auto_login()

# 启用热重载，避免重复扫码
itchat.auto_login(hotReload=True)

# 命令行显示二维码
itchat.auto_login(enableCmdQR=True)

# 自定义回调函数
def after_login():
    print("登录成功！")
    
itchat.auto_login(loginCallback=after_login)

2. 手动登录控制

对于需要更精细控制的场景，ItChat-UOS提供了分步登录API：

# 获取二维码UUID
uuid = itchat.get_QRuuid()

# 下载并显示二维码
itchat.get_QR(uuid=uuid, enableCmdQR=True)

# 检查登录状态
status = itchat.check_login(uuid)

# 初始化Web微信
itchat.web_init()

# 开始接收消息
itchat.start_receiving()

3. 登录状态管理

# 保存登录状态到文件
itchat.dump_login_status('login_status.pkl')

# 从文件加载登录状态
itchat.load_login_status('login_status.pkl')

# 退出登录
itchat.logout()

💬 消息处理API

1. 消息注册装饰器

这是ItChat-UOS最核心的功能之一，让你能够轻松处理各种类型的消息：

@itchat.msg_register(msgType, isFriendChat=False, 
                     isGroupChat=False, isMpChat=False)
def message_handler(msg):
    # 处理消息的逻辑
    return response

消息类型常量：

itchat.content.TEXT：文本消息
itchat.content.PICTURE：图片消息
itchat.content.VOICE：语音消息
itchat.content.VIDEO：视频消息
itchat.content.FILE：文件消息
itchat.content.CARD：名片消息
itchat.content.MAP：位置消息
itchat.content.SHARING：分享消息
itchat.content.FRIENDS：好友请求

完整示例：

import itchat
from itchat.content import *

# 处理文本消息
@itchat.msg_register(TEXT)
def text_reply(msg):
    return f"收到消息：{msg.text}"

# 处理图片消息
@itchat.msg_register(PICTURE)
def image_reply(msg):
    msg.download(msg.fileName)  # 下载图片
    return "图片已保存！"

# 处理好友请求
@itchat.msg_register(FRIENDS)
def add_friend(msg):
    msg.user.verify()  # 自动通过验证
    return "你好，欢迎成为好友！"

# 处理群聊@消息
@itchat.msg_register(TEXT, isGroupChat=True)
def group_reply(msg):
    if msg.isAt:  # 判断是否被@
        return f"@{msg.actualNickName} 我收到了你的消息"

2. 消息对象属性

消息对象包含丰富的属性信息：

属性	说明	示例
`msg.text`	消息文本内容	"你好"
`msg.type`	消息类型	"Text"
`msg.fromUserName`	发送者ID	"@123456789"
`msg.toUserName`	接收者ID	"filehelper"
`msg.fileName`	文件名	"image.jpg"
`msg.user`	发送者用户对象	User对象
`msg.isAt`	是否被@	True/False
`msg.actualNickName`	实际昵称	"张三"

👥 联系人管理API

1. 获取联系人列表

# 获取所有联系人（包括好友、群聊、公众号）
contact_list = itchat.get_contact()

# 获取好友列表
friends = itchat.get_friends()

# 获取群聊列表
chatrooms = itchat.get_chatrooms()

# 获取公众号列表
mps = itchat.get_mps()

2. 搜索联系人

# 搜索好友
itchat.search_friends(name='张三')  # 按昵称搜索
itchat.search_friends(remarkName='同事')  # 按备注搜索
itchat.search_friends(wechatAccount='zhangsan123')  # 按微信号搜索

# 搜索群聊
itchat.search_chatrooms(name='技术交流群')

# 搜索公众号
itchat.search_mps(name='人民日报')

3. 联系人信息更新

# 更新好友信息
itchat.update_friend('@user123')

# 更新群聊信息（获取详细成员信息）
itchat.update_chatroom('@@chatroom123', detailedMember=True)

# 设置好友备注
itchat.set_alias('@user123', '技术总监')

# 设置好友置顶
itchat.set_pinned('@user123', isPinned=True)

📤 消息发送API

1. 发送文本消息

# 发送给文件传输助手
itchat.send_msg('你好，文件传输助手', toUserName='filehelper')

# 发送给指定好友
itchat.send_msg('你好，朋友！', toUserName='@user123')

# 发送给群聊
itchat.send_msg('群公告：今晚8点开会', toUserName='@@chatroom123')

2. 发送媒体文件

# 发送图片
itchat.send_image('photo.jpg', toUserName='@user123')

# 发送文件
itchat.send_file('document.pdf', toUserName='@user123')

# 发送视频
itchat.send_video('video.mp4', toUserName='@user123')

# 通用发送方法（自动识别类型）
itchat.send('@img@photo.jpg', toUserName='@user123')  # 图片
itchat.send('@fil@document.pdf', toUserName='@user123')  # 文件
itchat.send('@vid@video.mp4', toUserName='@user123')  # 视频

3. 文件上传与发送

对于需要重复发送的文件，可以先上传获取mediaId：

# 上传文件获取mediaId
result = itchat.upload_file('large_file.zip')
if result['BaseResponse']['Ret'] == 0:
    media_id = result['MediaId']
    # 使用mediaId发送，避免重复上传
    itchat.send_file('large_file.zip', toUserName='@user123', mediaId=media_id)

🏢 群聊管理API

1. 群聊创建与管理

# 创建群聊
member_list = [
    {'UserName': '@user1'},
    {'UserName': '@user2'},
    {'UserName': '@user3'}
]
itchat.create_chatroom(member_list, topic='技术交流群')

# 修改群名称
itchat.set_chatroom_name('@@chatroom123', '新的群名称')

# 添加群成员
itchat.add_member_into_chatroom('@@chatroom123', [
    {'UserName': '@user4'},
    {'UserName': '@user5'}
])

# 移除群成员
itchat.delete_member_from_chatroom('@@chatroom123', [
    {'UserName': '@user4'}
])

2. 获取群成员头像

# 获取群聊头像
itchat.get_head_img(chatroomUserName='@@chatroom123')

# 获取群成员头像
itchat.get_head_img(userName='@member123', 
                    chatroomUserName='@@chatroom123')

🔄 高级功能API

1. 多实例支持

ItChat-UOS支持多账号同时在线：

# 创建新实例
account1 = itchat.new_instance()
account1.auto_login(hotReload=True, statusStorageDir='account1.pkl')

account2 = itchat.new_instance()
account2.auto_login(hotReload=True, statusStorageDir='account2.pkl')

# 分别为不同实例注册消息处理器
@account1.msg_register(itchat.content.TEXT)
def reply1(msg):
    return "这是账号1的回复"

@account2.msg_register(itchat.content.TEXT)
def reply2(msg):
    return "这是账号2的回复"

# 分别运行
account1.run()
account2.run()

2. 异步组件支持

ItChat-UOS提供异步版本，适合高性能应用：

# 使用异步组件
from itchat.async_components import load_components
import asyncio

async def main():
    # 加载异步组件
    from itchat.async_components import load_components
    load_components(Core)
    
    # 创建异步实例
    instance = Core()
    await instance.auto_login()
    
    # 异步消息处理
    @instance.msg_register(itchat.content.TEXT)
    async def text_reply(msg):
        return "异步回复：" + msg.text
    
    await instance.run()

asyncio.run(main())

3. 消息撤回功能

# 撤回消息（需要消息ID）
itchat.revoke(msgId='1234567890', toUserName='@user123')

⚙️ 配置与日志API

1. 日志配置

# 设置日志级别
itchat.set_logging(logging.INFO)

# 自定义日志处理器
import logging
logger = logging.getLogger('itchat')
handler = logging.FileHandler('itchat.log')
logger.addHandler(handler)

2. 运行配置

# 启动消息处理循环
itchat.run(debug=True)  # 启用调试模式

# 停止运行
itchat.logout()

🛠️ 实用技巧与最佳实践

1. 错误处理与重试

import time
from itchat.returnvalues import ReturnValue

def send_message_with_retry(msg, toUserName, max_retries=3):
    for i in range(max_retries):
        result = itchat.send_msg(msg, toUserName)
        if isinstance(result, ReturnValue) and result.get('BaseResponse', {}).get('Ret') == 0:
            return True
        time.sleep(2)  # 等待2秒后重试
    return False

2. 消息队列处理

from itchat.storage.messagequeue import MessageQueue

# 创建消息队列
mq = MessageQueue()

# 批量处理消息
@itchat.msg_register(itchat.content.TEXT)
def handle_message(msg):
    mq.put(msg)
    
def process_queue():
    while True:
        msg = mq.get()
        # 处理消息逻辑
        print(f"处理消息：{msg.text}")

3. 性能优化建议

使用热重载：避免重复扫码，提高开发效率
批量操作：对于联系人管理，尽量批量处理
异步处理：对于高并发场景，使用异步版本
合理使用缓存：缓存常用联系人信息，减少API调用

🚀 实战应用示例

示例1：智能客服机器人

import itchat
from itchat.content import TEXT

@itchat.msg_register(TEXT)
def customer_service(msg):
    if '价格' in msg.text:
        return '我们的产品价格表请查看：price.pdf'
    elif '技术支持' in msg.text:
        return '技术问题请拨打：400-123-4567'
    elif '订单' in msg.text:
        return '订单查询请提供订单号'
    else:
        return '您好，我是智能客服，请问有什么可以帮助您？'

itchat.auto_login(hotReload=True)
itchat.run()

示例2：自动消息转发

import itchat
from itchat.content import *

@itchat.msg_register([TEXT, PICTURE, FILE])
def forward_message(msg):
    # 转发给文件传输助手
    if msg.type == TEXT:
        itchat.send_msg(f"转发消息：{msg.text}", toUserName='filehelper')
    elif msg.type == PICTURE:
        msg.download(msg.fileName)
        itchat.send_image(msg.fileName, toUserName='filehelper')
    elif msg.type == FILE:
        msg.download(msg.fileName)
        itchat.send_file(msg.fileName, toUserName='filehelper')

itchat.auto_login()
itchat.run()

📚 官方文档与资源

官方文档：docs/official.md
AI功能源码：plugins/ai/
入门教程：docs/intro/start.md
消息处理指南：docs/intro/messages.md
联系人管理：docs/intro/contact.md

🎯 总结

ItChat-UOS提供了全面而强大的微信自动化API，从基础的登录认证到高级的群聊管理，每个功能都经过精心设计。通过本参考手册，你应该能够：

掌握ItChat-UOS的核心API使用方法
实现各种微信自动化场景
优化你的微信机器人性能
避免常见的错误和陷阱

无论你是想构建一个简单的自动回复机器人，还是开发复杂的企业级微信应用，ItChat-UOS都能为你提供强大的支持。开始你的微信自动化之旅吧！💪

提示：使用ItChat-UOS时请遵守微信用户协议，合理使用自动化功能，避免对他人造成骚扰。

【免费下载链接】ItChat-UOS 复活Itchat,你只需要 pip install itchat-uos 项目地址: https://gitcode.com/gh_mirrors/it/ItChat-UOS

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考