Weixin

主入口类，连接并操作单个微信客户端实例。

构造方法

python

Weixin(
    pid=None,                          # 微信进程 PID，None 自动查找
    on_login=None,                     # 登录回调 callback(login: Login)
    default_login_timeout=60,          # 默认登录等待超时（秒）
    background=False,                  # 后台模式
    offscreen=True,                    # 后台模式下窗口移到屏幕外
    idle_wait=0,                       # 物理输入等待时间（秒）
    lock_input=False,                  # 操作期间锁定物理输入
    resize=False,                      # 自动调整窗口大小
    install_path=None,                 # 微信安装路径
    ocr="wcocr",                       # OCR 引擎 "wcocr" | "rapidocr"
    wxocr_weixin_install_path=None,    # 微信 OCR 插件所需的带版本号安装路径
    wxocr_plugin_path=None,            # 微信 OCR 插件 wxocr.dll 路径
)

参数	类型	默认值	说明
`pid`	`int \| None`	`None`	微信进程 PID，传入时精确绑定该进程，None 自动查找或启动
`on_login`	`callable \| None`	`None`	登录回调函数，签名 `callback(login: Login)`
`default_login_timeout`	`float`	`60`	等待手动登录超时（秒）
`background`	`bool`	`False`	后台模式（通过 SendMessage 发送虚拟鼠标/键盘消息）
`offscreen`	`bool`	`True`	后台模式下窗口移到屏幕外，仅 `background=True` 时生效
`idle_wait`	`float`	`0`	人类操作等待时间（秒），>0 时自动启动物理输入监控
`lock_input`	`bool`	`False`	操作期间锁定物理键盘鼠标（需管理员权限）
`resize`	`bool`	`False`	自动调整窗口大小（宽高为桌面的 1/3 × 1/2）
`install_path`	`str \| None`	`None`	微信安装路径，None 自动从注册表检测
`ocr`	`str`	`"wcocr"`	OCR 引擎：`"wcocr"`（微信自带）或 `"rapidocr"`
`wxocr_weixin_install_path`	`str \| None`	`None`	微信 OCR 所需的带版本号安装路径，None 自动检测
`wxocr_plugin_path`	`str \| None`	`None`	wxocr.dll 路径，None 自动检测

属性

属性	类型	说明
`pid`	`int`	微信进程 PID
`version`	`str`	微信版本号
`language`	`str`	界面语言代码（`"cn"` / `"cn_t"` / `"en"`）
`status`	`str`	状态：`"online"` / `"locked"` / `"login"` / `"offline"`
`is_online`	`bool`	是否在线（主窗口是否存在）
`chat`	`Chat \| None`	当前主窗口激活的聊天对象
`chats`	`List[Chat \| SeparateChat]`	所有已打开的聊天窗口
`processes`	`Dict[int, str]`	微信主进程及子进程信息 `{pid: name}`
`all_pids`	`Set[int]`	微信主进程及子进程 PID 集合
`has_handlers`	`bool`	是否注册了任何事件处理器
`current_version`	`str`	当前微信版本号（通过设置页获取）
`nav_tabs`	`List[str]`	导航栏可用标签页列表
`discovery_tabs`	`List[str]`	发现列表中所有可点击项名称

子模块

属性	类型	说明
`navigator`	`Navigator`	导航栏
`session`	`Session`	会话列表
`moment`	`Moment`	朋友圈
`collections`	`Collections`	收藏
`file_manager`	`FileManager`	文件管理器
`contacts`	`Contacts`	通讯录
`settings`	`Settings`	设置
`preview`	`Preview`	图片/视频预览
`browser`	`Browser`	内置浏览器

消息发送

`send_text(nickname, content, quote=None, timeout=0)`

发送文本消息。

nickname str — 联系人/群聊名称
content str — 文本内容
quote Message | int | None — 引用消息（Message 对象或 msg_id）
timeout float — 状态检测超时（秒），0 不等待
返回 MessageStatus

`send_file(nickname, file_path, quote=None, timeout=0)`

发送文件。

file_path str | List[str] — 文件路径或路径列表，支持 URL

`send_image(nickname, file_path, quote=None, timeout=0)`

发送图片。

file_path str | List[str] — 图片路径或路径列表

`send_video(nickname, file_path, quote=None, timeout=0)`

发送视频。

file_path str | List[str] — 视频路径或路径列表

`send_at(nickname, content, at_members, quote=None, timeout=0)`

发送@消息（群聊）。

at_members List[str] — 要@的成员列表，["所有人"] 可@全员

`send_emotion(nickname, keyword=None, index=0, quote=None, timeout=0)`

发送表情。

keyword str | None — 搜索关键词，None 发送自定义表情
index int — 第几个表情（从 0 开始）

`send_collection(nickname, keyword, quote=None, timeout=0)`

发送收藏内容。

`send_card(nickname, share)`

发送名片。将 share 联系人的名片发送给 nickname。

`send_pat(nickname)`

发送拍一拍。

返回 bool

消息读取

`get_messages(nickname)`

获取指定会话当前可见的消息列表（完整解析，含发送者识别）。

返回 List[Message]

`get_messages_lazy(nickname)`

获取指定会话当前可见的消息列表（轻量模式，不截图识别发送者）。

source/sender 与各区域坐标留空，调用 message.refresh() 或任意操作方法时才惰性填充，适合只需要消息内容的场景。

返回 List[Message]

`iter_messages(nickname, count=None)`

逐条获取指定会话最近的消息（生成器，从最新到最旧）。

count int | None — 要获取的消息数量，None 获取全部（滚动到顶部）
返回 Iterator[Message]

`get_recently_messages(nickname, count=None)`

获取指定会话最近的消息列表（从最新到最旧）。

count int | None — 要获取的消息数量，None 获取全部
返回 List[Message]

`scroll_chat_to_bottom(nickname)`

将指定会话的消息列表滚动到底部（最新消息处）。

`clear_chat_input(nickname)`

清空指定会话的输入框。

`paste_chat_input(nickname, content)`

通过右键粘贴将内容输入到指定会话的输入框（不发送）。

content str | List[str] — 文本内容或文件路径列表

`cancel_chat_quote(nickname)`

取消指定会话输入框中的引用消息。

返回 bool — 当前无引用时返回 False

`separate_chat(nickname)`

将指定会话打开为独立窗口。已是独立窗口时直接返回该实例，不重复打开。

返回 SeparateChat

`is_chat_pinned(nickname)`

指定私聊会话是否已置顶。

返回 bool

`is_chat_muted(nickname)`

指定私聊会话是否已开启消息免打扰。

返回 bool

会话操作

`chat_with(nickname, chat_type=None, find_in_chat=True, find_in_separate_chat=True, find_in_visible_sessions=True)`

获取与指定联系人的聊天窗口对象。优先查找已打开的独立窗口。

nickname str — 联系人或群聊名称
chat_type List[str] | None — 搜索时优先匹配的分类，如 ["联系人", "群聊"]
find_in_chat bool — 是否检查当前主窗口聊天是否已是目标会话
find_in_separate_chat bool — 是否查找已打开的独立聊天窗口
find_in_visible_sessions bool — 是否尝试在可见会话列表中直接点击
返回 Chat | SeparateChat

`chat_with_contact(nickname)`

获取与指定联系人的聊天窗口（搜索时优先匹配联系人分类）。

`chat_with_room(nickname)`

获取与指定群聊的聊天窗口（搜索时优先匹配群聊分类）。

`chat_with_contact_or_room(nickname)`

获取与指定联系人或群聊的聊天窗口。

`chat_with_official_account(nickname)`

获取与指定公众号的聊天窗口。

`chat_with_service_account(nickname)`

获取与指定服务号的聊天窗口。

`open_session(nickname)`

通过在会话列表中查找并点击来打开指定会话。

返回 SessionItem

`close_session(nickname)`

关闭指定会话（从会话列表中隐藏）。

`get_sessions(count=None, speed=10)`

获取会话列表（含未读消息数）。

count int | None — 获取数量，None 获取全部
speed int — 滚动速度
返回 List[SessionItem]

`iter_sessions(count=None, speed=10)`

逐条获取会话列表（生成器，含未读消息数）。

返回 Iterator[SessionItem]

`get_visible_sessions()`

获取当前可见区域内的会话列表（不滚动）。

返回 List[SessionItem]

`get_unread_sessions()`

获取所有有未读消息的会话列表。

返回 List[SessionItem]

`iter_unread_sessions()`

逐条获取有未读消息的会话（生成器）。

返回 Iterator[SessionItem]

`get_selected_session()`

获取当前选中（激活）的会话名称。

返回 str | None

`scroll_session_to_top()` / `scroll_session_to_bottom()`

将会话列表滚动到顶部/底部。

`pin_session(nickname)` / `unpin_session(nickname)`

置顶/取消置顶会话（通过会话列表右键菜单）。

返回 SessionItem

`mark_session_as_read(nickname)` / `mark_session_as_unread(nickname)`

将会话标为已读/未读。

返回 SessionItem

`mute_session(nickname)` / `unmute_session(nickname)`

开启/关闭会话消息免打扰（通过会话列表右键菜单）。

返回 SessionItem

`separate_session(nickname)`

通过会话列表右键菜单"独立窗口显示"打开会话。

返回 SessionItem

`separate_session_by_click(nickname)`

双击会话列表项打开独立窗口。

返回 SessionItem

`hide_session(nickname)`

从会话列表中隐藏该会话（不显示，不删除聊天记录）。

返回 SessionItem

`delete_session(nickname)`

删除会话（会清除聊天记录，不可逆）。

返回 SessionItem

`get_separate_chat(contact_name)`

获取独立窗口的聊天会话。

contact_name str — 联系人名称
返回 SeparateChat | None — 窗口不存在则返回 None

`get_separate_chats()`

获取所有已打开的独立聊天窗口（按 PID 过滤）。

返回 List[SeparateChat]

`create_room(nicknames)`

创建群聊。

nicknames List[str] — 至少 2 个好友昵称

`create_note(content)`

创建笔记并写入内容，完成后关闭笔记窗口。

content str — 笔记文本内容

`add_friend(keyword, message=None, remark=None, permission=None, hide_my_posts=False, hide_their_posts=False)`

添加好友。

返回 dict — {"result": bool, "reason": str | None}

联系人管理

`get_contact_profile(nickname)`

获取联系人资料。

返回 dict

`set_contact_info(nickname, *, remark=None, labels=None, phones=None, description=None, images=None)`

一次性设置联系人信息。

`set_contact_remark(nickname, remark)`

设置备注名。

`set_contact_label(nickname, labels)`

为联系人设置标签（覆盖式）。

labels List[str] — 标签列表

`set_contact_phone(nickname, phones)`

为联系人设置电话号码（覆盖式）。

phones List[str] — 电话号码列表

`set_contact_description(nickname, description)`

设置联系人的描述信息。

`set_contact_image(nickname, images)`

设置联系人的备注图片（覆盖式）。

images List[str] — 图片路径列表

`add_contact_label(nickname, labels)`

为联系人添加标签（增量式）。

`add_contact_phone(nickname, phones)`

为联系人添加电话号码（增量式）。

`add_contact_image(nickname, images)`

为联系人添加备注图片（增量式）。

`remove_contact_label(nickname, labels)`

移除联系人的标签。

`remove_contact_phone(nickname, phones)`

移除联系人的电话号码。

`remove_contact_image(nickname, images)`

删除联系人的备注图片。

images List[int] — 要删除的图片序号列表

`collect_contact_image(nickname, images)`

收藏联系人的指定备注图片。

images List[int] — 图片序号列表
返回 int — 成功收藏的数量

`save_contact_image(nickname, images, save_path)`

保存联系人的指定备注图片到指定目录。

images List[int] — 图片序号列表
save_path str — 保存目录路径
返回 int — 成功保存的数量

`set_contact_star(nickname)` / `cancel_contact_star(nickname)`

设为/取消星标朋友。

`black_contact(nickname)` / `unblack_contact(nickname)`

加入/移出黑名单。

`delete_contact(nickname)`

删除联系人。

`recommend_contact(nickname, receiver_nickname)`

将指定联系人推荐给另一个朋友（发送名片）。

返回 bool

`get_contact_permission(nickname)`

获取联系人的朋友权限设置。

返回 dict

`set_friend_permission(nickname, permission="all", hide_my_posts=False, hide_their_posts=False)`

设置朋友权限。

permission str — "all" 或 "chatonly"

好友申请

`get_new_friends()`

获取"新的朋友"列表。

返回 List[Contact | NewFriend] — Contact（已添加）或 NewFriend（等待验证）

`iter_new_friends()`

逐条获取"新的朋友"列表（生成器）。

`auto_accept_new_friend(func=None)`

自动通过"新的朋友"里待验证的好友申请。

func callable | None — 回调函数，签名 func(accepted_count: int, item: NewFriend) -> 决策

回调返回值支持以下形式：

返回值	效果
`True`	通过，不做任何额外设置
`False` / `None`	跳过
`(True, {...})`	通过，并按选项字典设置
`(False, {...})`	跳过

选项字典支持的键：

键	类型	说明
`remark`	`str`	备注名
`tags`	`list`	标签列表
`permission`	`str`	`"chatonly"` 表示仅聊天
`hide_my_posts`	`bool`	不让他看我的朋友圈
`hide_their_posts`	`bool`	不看他的朋友圈

func 为 None 时全部通过且不做任何设置。

返回 List[dict] — [{"nickname": str, "result": bool, "reason": str | None}, ...]

python

# 全部通过
wx.auto_accept_new_friend()

# 全部通过，统一备注和标签
wx.auto_accept_new_friend(
    lambda n, item: (True, {"remark": "自动通过", "tags": ["新客户"]})
)

# 最多通过 5 个
wx.auto_accept_new_friend(
    lambda n, item: (n < 5, {"permission": "chatonly"})
)

群聊管理

`set_room_info(nickname, name=None, announcement=None, remark=None, my_nickname=None, mute=None, pin=None, save_address_book=None, display_member_nickname=None, fold=None)`

一次性设置群聊信息。

参数	类型	说明
`name`	`str \| None`	群名称
`announcement`	`str \| None`	群公告
`remark`	`str \| None`	群备注
`my_nickname`	`str \| None`	我在群中的昵称
`mute`	`bool \| None`	消息免打扰
`pin`	`bool \| None`	置顶
`save_address_book`	`bool \| None`	保存到通讯录
`display_member_nickname`	`bool \| None`	显示群成员昵称
`fold`	`bool \| None`	折叠会话

`set_room_name(nickname, name)`

设置群聊名称。

`set_room_announcement(nickname, content)`

设置群公告。

`set_room_remark(nickname, remark)`

设置群聊备注。

`set_room_nickname(nickname, my_nickname)`

设置我在群中的昵称。

`add_room_members(nickname, members)` / `remove_room_members(nickname, members)`

添加/移除群成员。

`exit_room(nickname, clear_history=False)`

退出群聊。

nickname str — 群聊名称
clear_history bool — 是否同时清空聊天记录，默认 False

`pin_chat(nickname)` / `unpin_chat(nickname)`

置顶/取消置顶会话。

`mute_chat(nickname)` / `unmute_chat(nickname)`

消息免打扰。

`fold_chat(nickname)` / `unfold_chat(nickname)`

折叠/取消折叠会话。

`pin_room_chat(nickname)` / `unpin_room_chat(nickname)`

置顶/取消置顶群聊会话。

`mute_room_chat(nickname)` / `unmute_room_chat(nickname)`

开启/关闭群聊消息免打扰。

`fold_room_chat(nickname)` / `unfold_room_chat(nickname)`

折叠/取消折叠群聊会话。

`add_room_address_book(nickname)` / `remove_room_address_book(nickname)`

将群聊保存到/从通讯录移除。

`display_room_member_nickname(nickname)` / `hidden_room_member_nickname(nickname)`

显示/隐藏群成员昵称。

`clear_chat_history(nickname)`

清空指定会话的聊天记录。

`clear_room_chat_history(nickname)`

清空指定群聊会话的聊天记录。

`exit_room(nickname, clear_history=False)`

退出指定群聊。

clear_history bool — 是否同时清空聊天记录，默认 False

通讯录

`get_labels()` / `iter_labels()`

获取标签列表，操作完自动关闭通讯录管理窗口。

返回 List[Label] / Iterator[Label]

`add_label(name)`

新建标签。

返回 bool — True 成功，False 标签已存在

`rename_label(old_name, new_name)`

修改标签名。

`delete_label(name)`

删除标签。

`get_rooms(count=None, speed=1, timeout=300)`

获取最近群聊列表。

返回 List[dict] — [{"nickname": str, "member_count": int, "raw_text": str}, ...]

`iter_rooms(count=None, speed=1, timeout=300)`

逐条获取最近群聊列表（生成器）。

`open_contacts_manager(category=None)`

打开通讯录管理窗口。

category str | None — 分类名称，如 "最近群聊"、"标签"、"朋友权限"
返回 ContactsManager

`close_contacts_manager()`

关闭通讯录管理窗口。

`get_wechat_contacts(count=None)` / `get_wechat_contacts_brief(count=None)`

获取微信联系人列表。完整版解析详情，轻量版仅返回 nickname。

返回 List[WeChatContact]

`get_wework_contacts(count=None)` / `get_wework_contacts_brief(count=None)`

获取企业微信联系人列表。

返回 List[WeWorkContact]

`get_official_accounts(count=None)` / `get_official_accounts_brief(count=None)`

获取公众号列表。

返回 List[OfficialAccount]

`get_service_accounts(count=None)` / `get_service_accounts_brief(count=None)`

获取服务号列表。

返回 List[ServiceAccount]

`iter_wechat_contacts(count=None)` / `iter_wework_contacts(count=None)`

生成器逐条获取联系人/企业微信联系人（完整版）。

`iter_official_accounts(count=None)` / `iter_service_accounts(count=None)`

生成器逐条获取公众号/服务号（完整版）。

`get_new_friends()` / `iter_new_friends()`

获取"新的朋友"列表。返回 Contact（已添加）或 NewFriend（待验证）。

朋友圈

`open_moments()`

打开朋友圈窗口，返回 Moment 实例。不会自动关闭窗口，用完请调用 close_moments()。

返回 Moment

`close_moments()`

关闭朋友圈窗口（未打开时不操作）。

`refresh_moments()`

刷新朋友圈（回到列表顶部并加载最新动态）。

`get_visible_moments()`

获取当前可见区域内的朋友圈动态列表（不滚动、不关闭窗口）。

返回 List[MomentItem]

`get_center_moment()`

获取当前处于朋友圈列表视野中间位置的动态。

返回 MomentItem | None

`scroll_to_next_moment()`

将下一条朋友圈动态滚动到视野中央并返回该动态。

返回 MomentItem | None

`get_moments(count=10, position="top")`

获取朋友圈动态列表，操作完自动关闭朋友圈窗口。

count int — 获取数量
position "top" | "current" — 起始位置
返回 list

`iter_moments(count=10, position="top")`

逐条获取朋友圈动态（生成器），操作完自动关闭朋友圈窗口。

`publish_moment(text=None, images=None, video=None, remind_contacts=None, permission=None, permission_contacts=None, permission_labels=None)`

发布朋友圈，操作完自动关闭朋友圈窗口。支持纯文字、图文、视频三种模式（图片和视频互斥）。

参数	类型	说明
`text`	`str \| None`	文本内容
`images`	`List[str] \| None`	图片路径列表（最多 9 张，与 video 互斥）
`video`	`str \| None`	视频路径（与 images 互斥）
`remind_contacts`	`List[str] \| None`	提醒谁看的联系人列表
`permission`	`str \| None`	`"公开"` / `"私密"` / `"谁可以看"` / `"不给谁看"`
`permission_contacts`	`List[str] \| None`	隐私联系人列表
`permission_labels`	`List[str] \| None`	隐私标签列表

返回 bool

`like_moment(moment_item)` / `unlike_moment(moment_item)`

对指定动态点赞/取消点赞，操作完自动关闭朋友圈窗口。

moment_item MomentItem — 朋友圈动态对象
返回 bool

`comment_moment(moment_item, content)`

对指定动态评论，操作完自动关闭朋友圈窗口。

返回 bool

`like_moment_when(func, count=10, position="top")`

条件批量点赞：遍历朋友圈，回调返回 True 时点赞。

func callable — 签名 func(liked_count: int, item: MomentItem) -> bool
返回 List[MomentItem] — 成功点赞的动态列表

`comment_moment_when(func, count=10, position="top")`

条件批量评论：遍历朋友圈，回调返回评论内容时评论。

func callable — 签名 func(commented_count: int, item: MomentItem) -> str | None
返回 List[MomentItem] — 成功评论的动态列表

`capture_moment(moment_item)`

对指定动态截图，操作完自动关闭朋友圈窗口。

返回 bytes — PNG 格式

消息监听

`on(events=None)`

注册事件处理器（装饰器）。

python

@wx.on(Event.TEXT)
def handler(weixin, chat, message):
    print(message.content)

@wx.on([Event.TEXT, Event.IMAGE])
def on_multi(weixin, chat, message):
    print(message.type_label)

@wx.on()  # 监听所有消息
def on_all(weixin, chat, message):
    print(message)

`once(events=None)`

注册一次性事件处理器。

`off(events=None, func=None)`

移除事件处理器。

`add_chat_listen(names)`

注册要监听的聊天窗口。

names str | List[str]
返回 List[SeparateChat]

`add_all_chats_listen()`

自动发现并注册所有已打开的独立聊天窗口。

返回 List[SeparateChat]

`remove_chat_listen(names)`

移除指定聊天的监听。

names str | List[str]

`remove_all_chats_listen()`

移除所有聊天监听。

`run(interval=0.1, idle_interval=0.1, auto_scan=False, listen_mode="ui")`

启动消息监听（阻塞运行，Ctrl+C 退出）。

参数	类型	默认值	说明
`interval`	`float`	`0.1`	有新消息时的轮询间隔（秒）
`idle_interval`	`float`	`0.1`	无新消息时的轮询间隔（秒）
`auto_scan`	`bool`	`False`	UI 模式下是否自动扫描新窗口
`listen_mode`	`str`	`"ui"`	监听模式：`"ui"`（UI 自动化）或 `"db"`（数据库监听）

数据库模式（listen_mode="db"）：

通过监控微信 SQLite WAL 文件变化检测新消息
无需打开独立窗口，自动监听所有会话
需要指定 pid 参数和管理员权限
回调中 chat 固定为 None，message 为 dict 字典
详见消息监听 - 数据库监听模式

数据库模式 message 字段：

字段	说明
`id`	local_id（本地消息 ID）
`msg_id`	server_id（服务器消息 ID）
`type`	消息类型（对应 DBEvent 枚举值）
`is_sender`	是否为自己发送（1=是, 0=否）
`msg`	消息内容（文本或解析后的字典）
`from_wxid`	发送者 wxid
`sender`	发送者昵称
`to_wxid`	接收者 wxid
`receiver`	接收者昵称
`room_wxid`	群聊 wxid
`room_nickname`	群聊昵称
`at_user_list`	@用户列表
`create_time`	消息创建时间戳

`stop()`

停止监听。

通话

`voice_call(nickname)`

发起语音通话。

返回 VoipCall

`video_call(nickname)`

发起视频通话。

返回 VoipCall

设置

账号与登录

方法	返回	说明
`get_account_info()`	`dict`	获取账号信息（昵称、微信号、登录方式等）
`get_login_method()`	`str`	获取当前登录方式
`set_login_method(method)`	—	切换登录方式
`logout()`	—	退出登录

存储

方法	返回	说明
`get_storage_info()`	`dict`	获取存储空间详情
`get_storage_path()`	`str`	获取当前存储位置路径
`change_storage_path(storage_path)`	—	更改微信存储位置
`manage_storage()`	—	打开存储空间管理窗口
`clean_redundant_data()`	—	清理历史版本冗余数据
`clean_cache()`	—	清理缓存
`clear_all_chats_history()`	—	清空全部聊天记录
`get_keep_chat_history()`	`bool`	获取"保留聊天记录"开关状态
`set_keep_chat_history(enable)`	—	设置"保留聊天记录"开关

外观与语言

方法	返回	说明
`get_language()`	`str`	获取当前语言设置
`set_language(language)`	—	切换语言
`get_appearance()`	`str`	获取外观设置
`set_appearance(appearance)`	—	设置外观
`get_font_size()`	`int`	获取当前字体大小
`set_font_size(size)`	—	设置字体大小（0~80，步长 10）

通用设置

方法	返回	说明
`get_auto_start()`	`bool`	开机自启动状态
`set_auto_start(enable)`	—	设置开机自启动
`get_auto_update()`	`bool`	自动更新状态
`set_auto_update(enable)`	—	设置自动更新
`get_auto_download()`	`dict`	自动下载设置 `{"enabled": bool, "size_mb": int}`
`set_auto_download(enable, size_mb=None)`	—	设置自动下载

聊天设置

方法	返回	说明
`get_translate_language()`	`str`	文字翻译目标语言
`set_translate_language(language)`	—	设置翻译目标语言
`get_auto_translate()`	`bool`	自动翻译开关
`set_auto_translate(enable)`	—	设置自动翻译
`get_readonly_file()`	`bool`	以只读方式打开文件
`set_readonly_file(enable)`	—	设置只读打开文件
`get_show_search_history()`	`bool`	显示网络搜索历史
`set_show_search_history(enable)`	—	设置搜索历史显示
`get_auto_voice_to_text()`	`bool`	语音消息自动转文字
`set_auto_voice_to_text(enable)`	—	设置语音自动转文字
`get_use_system_browser()`	`bool`	使用系统浏览器打开网页
`set_use_system_browser(enable)`	—	设置使用系统浏览器

窗口与截图设置

方法	返回	说明
`get_keep_window_on_screenshot()`	`bool`	截图时保留当前窗口
`set_keep_window_on_screenshot(enable)`	—	设置截图时保留窗口
`get_hide_on_screen_share()`	`bool`	演示屏幕时隐藏微信
`set_hide_on_screen_share(enable)`	—	设置演示时隐藏微信

通知设置

方法	返回	说明
`get_notification_info()`	`dict`	获取通知设置信息
`set_notification_info(**kwargs)`	—	设置通知信息
`get_message_notification_sound()`	`bool`	新消息通知声音
`set_message_notification_sound(enable)`	—	设置通知声音
`get_voip_notification_sound()`	`bool`	语音/视频通话通知声音
`set_voip_notification_sound(enable)`	—	设置通话通知声音
`get_moment_notification_badge()`	`bool`	通知标记朋友圈
`set_moment_notification_badge(enable)`	—	设置朋友圈通知标记
`get_game_notification_badge()`	`bool`	通知标记游戏
`set_game_notification_badge(enable)`	—	设置游戏通知标记
`get_only_friend_interaction_reminder()`	`bool`	仅提醒朋友与我的互动
`set_only_friend_interaction_reminder(enable)`	—	设置仅朋友互动提醒

快捷键设置

方法	返回	说明
`get_shortcut_info()`	`dict`	获取快捷键设置信息
`reset_shortcuts()`	—	恢复快捷键默认设置

插件

方法	返回	说明
`get_plugins()`	`List[dict]`	获取插件列表
`download_plugin(plugin_name)`	`bool`	下载插件

关于与更新

方法	返回	说明
`get_about_info()`	`dict`	获取关于微信页面信息
`check_update()`	`WeixinUpdate`	检查微信更新
`open_help()`	—	打开微信帮助页面
`upload_log()`	—	上传微信日志
`open_feedback()`	—	打开意见反馈页面
`open_privacy_agreement()`	—	打开隐私协议
`open_service_agreement()`	—	打开服务协议

`open_collections(category="全部收藏")`

打开收藏页面并切换到指定分类，返回当前可见的收藏项列表。

category str — 分类名称："全部收藏" / "最近使用" / "链接" / "图片与视频" / "笔记" / "文件" / "聊天记录" / "语音" / "小程序"
返回 List[Collection]

`get_collections(category="全部收藏", count=None, speed=5)`

获取收藏列表。

category str — 收藏分类
count int | None — 获取数量，None 获取全部
speed int — 滚动速度
返回 List[Collection]

`iter_collections(category="全部收藏", count=None, speed=5)`

逐条获取收藏列表（生成器）。

返回 Iterator[Collection]

`get_visible_collections()`

获取当前可见区域内的收藏项列表（不滚动）。

返回 List[Collection]

`search_collections(keyword)`

搜索收藏。

返回 List[Collection]

聊天文件

`open_file_manager(category=None, order_by=None)`

打开聊天文件管理器。

category str | None — 文件类型筛选，如 "全部" / "文档" / "表格" / "图片" / "视频"
order_by str | None — 排序方式："按最新时间" / "按最旧时间" / "按从大到小" / "按从小到大"
返回 bool

`close_file_manager()`

关闭聊天文件管理器窗口。

`search_files(keyword)`

搜索聊天文件（仅返回当前可见的搜索结果）。

返回 List[ChatFile]

`get_files_by_search(keyword)`

搜索聊天文件并通过滚动遍历获取全部搜索结果。

返回 List[ChatFile]

`get_files(category=None)`

获取聊天文件列表。

返回 List[ChatFile]

`iter_files(count=None, speed=100, category=None)`

逐条获取聊天文件列表（生成器）。

count int | None — 要获取的文件数量，None 获取全部
speed int — 滚动速度
category str | None — 文件类型筛选

`get_visible_files()`

获取当前可见区域内的聊天文件列表（不滚动）。

返回 List[ChatFile]

`get_file_by_id(file_id)`

按 file_id 在当前可见文件列表中查找单个文件。

返回 ChatFile | None

`get_file_category()`

获取聊天文件管理器当前激活的文件类型筛选项名称。

返回 str | None

`get_file_order_by()`

获取聊天文件管理器当前的排序方式。

返回 str | None

`download_file(chat_file)`

下载聊天文件到微信默认路径。

`download_file_to(chat_file, file_path)`

下载聊天文件到指定路径。

返回 bool

`save_file_as(chat_file, file_path)`

将聊天文件另存为到指定路径。

返回 bool

`delete_file(chat_file)`

删除聊天文件。

返回 bool

状态与检查

`status` (属性)

获取微信当前状态。

返回 str — "online" / "locked" / "login" / "offline"

`is_online()`

微信是否在线（主窗口是否存在）。

返回 bool

`is_locked()`

检查微信是否已锁定。

返回 bool

`processes` (属性)

获取微信主进程及所有子进程的完整信息（每次调用刷新）。

返回 dict — {pid: process_name}

`all_pids` (属性)

获取微信主进程及所有子进程的 PID 集合。

返回 Set[int]

`check_new_messages()` / `check_new_contacts()` / `check_new_moments()`

检查是否有新通知（通过导航栏红点像素检测）。

返回 bool

`get_self_profile()`

获取当前登录账号信息。

返回 dict — {"nickname": str, "account": str}

`get_self_info()`

获取当前登录账号信息（含头像）。

返回 dict

导航栏

`nav_tabs` (属性)

导航栏当前可用的标签页名称列表。

返回 List[str]

`discovery_tabs` (属性)

发现列表中所有可点击项的名称列表。

返回 List[str]

`switch_to(tab_name)`

切换到指定的导航栏标签页。

tab_name str — 标签页名称，如 "微信"、"通讯录"、"收藏"、"发现"、"更多"

`switch_to_weixin()`

切换到微信（会话列表）标签页。

`switch_to_contacts()`

切换到通讯录标签页。

返回 Contacts

`switch_to_collections()`

切换到收藏标签页。

返回 Collections

`switch_to_moments()`

切换到朋友圈。

返回 Moment

`switch_to_channels()`

切换到视频号。

返回 Browser

`switch_to_search()`

切换到搜一搜。

返回 Browser

`switch_to_games()`

切换到游戏中心。

`switch_to_apps()`

切换到小程序面板。

返回 Browser

`switch_to_phone()`

切换到手机标签页。

`switch_to_more()`

切换到更多标签页。

`open_discovery(name)`

在"发现"列表中查找指定项并打开。

name str — 如 "朋友圈"、"视频号"、"搜一搜"

`open_settings()`

打开设置窗口。

返回 Settings

`close_settings()`

关闭设置窗口。

`open_chat_history_manager()`

打开聊天记录管理。

`open_channels_live_companion()`

打开视频号直播伴侣。

`lock()`

锁定微信（Ctrl+L）。

`unlock(timeout=60)`

解锁微信（需要在手机上确认）。

返回 bool

快捷键

`shortcut(name)`

通过快捷键名称执行对应的键盘快捷键。

支持的名称（见 Weixin.SHORTCUTS）：

名称	快捷键
`"发送消息"`	Enter
`"语音输入文字"`	Ctrl+Win
`"截图"`	Alt+A
`"锁定"`	Ctrl+L
`"显示窗口"`	Ctrl+Alt+W

也可以直接传入按键组合字符串，如 "Ctrl+Shift+A"。

`wakeup()`

唤醒微信窗口（Ctrl+Alt+W）。

`lock()`

锁定微信（Ctrl+L）。

`capture()`

调用截图快捷键（Alt+A）。

`voice_input()`

语音输入文字（Ctrl+Win）。

`enter()`

发送消息（Enter）。

窗口操作

继承自 WeixinWindow：

python

wx.activate()       # 激活窗口
wx.minimize()       # 最小化
wx.maximize()       # 最大化
wx.restore()        # 还原
wx.close()          # 关闭
wx.pin()            # 置顶
wx.unpin()          # 取消置顶
wx.move_offscreen() # 移到屏幕外
wx.move_back()      # 移回原位

`click(control, button="left", click="once")`

点击 uiautomation 控件。根据 background 属性选择点击方式。

control Control — uiautomation 控件对象
button str — "left" / "right" / "middle"
click str — "once" / "double"

微信更新

`find_new_version_window()`

检测是否弹出了新版本更新窗口。

返回 bool

`ignore_version_update()`

忽略本次更新。

`update_new_version()`

更新新版本。

`process_later()`

稍后处理。

OCR

`ocr(image)` / `get_image_text(image)`

识别图片中的文字。

image bytes | str — 图片字节数据或文件路径
返回 dict — {text: {center, left_top, right_bottom, width, height}}

截图

`get_screenshot()`

对微信主窗口截图。

返回 bytes — PNG 格式

`screenshot(save_path)`

截图并保存到文件。

类方法

`Weixin.open(install_path=None, timeout=30)`

启动一个新的微信客户端，返回 PID（支持多开）。

install_path str | None — 微信安装路径
timeout float — 等待启动超时（秒）
返回 int — 新进程 PID

Weixin ​

构造方法 ​

属性 ​

子模块 ​

消息发送 ​

send_text(nickname, content, quote=None, timeout=0) ​

send_file(nickname, file_path, quote=None, timeout=0) ​

send_image(nickname, file_path, quote=None, timeout=0) ​

send_video(nickname, file_path, quote=None, timeout=0) ​

send_at(nickname, content, at_members, quote=None, timeout=0) ​

send_emotion(nickname, keyword=None, index=0, quote=None, timeout=0) ​

send_collection(nickname, keyword, quote=None, timeout=0) ​

send_card(nickname, share) ​

send_pat(nickname) ​

消息读取 ​

get_messages(nickname) ​

get_messages_lazy(nickname) ​

iter_messages(nickname, count=None) ​

get_recently_messages(nickname, count=None) ​

scroll_chat_to_bottom(nickname) ​

clear_chat_input(nickname) ​

paste_chat_input(nickname, content) ​

cancel_chat_quote(nickname) ​

separate_chat(nickname) ​

is_chat_pinned(nickname) ​

is_chat_muted(nickname) ​

会话操作 ​

chat_with(nickname, chat_type=None, find_in_chat=True, find_in_separate_chat=True, find_in_visible_sessions=True) ​

chat_with_contact(nickname) ​

chat_with_room(nickname) ​

chat_with_contact_or_room(nickname) ​

chat_with_official_account(nickname) ​

chat_with_service_account(nickname) ​

open_session(nickname) ​

close_session(nickname) ​

get_sessions(count=None, speed=10) ​

iter_sessions(count=None, speed=10) ​

get_visible_sessions() ​

get_unread_sessions() ​

iter_unread_sessions() ​

get_selected_session() ​

scroll_session_to_top() / scroll_session_to_bottom() ​

pin_session(nickname) / unpin_session(nickname) ​

mark_session_as_read(nickname) / mark_session_as_unread(nickname) ​

mute_session(nickname) / unmute_session(nickname) ​

separate_session(nickname) ​

separate_session_by_click(nickname) ​

hide_session(nickname) ​

delete_session(nickname) ​

get_separate_chat(contact_name) ​

get_separate_chats() ​

create_room(nicknames) ​

create_note(content) ​

add_friend(keyword, message=None, remark=None, permission=None, hide_my_posts=False, hide_their_posts=False) ​

联系人管理 ​

get_contact_profile(nickname) ​

set_contact_info(nickname, *, remark=None, labels=None, phones=None, description=None, images=None) ​

set_contact_remark(nickname, remark) ​

set_contact_label(nickname, labels) ​

set_contact_phone(nickname, phones) ​

set_contact_description(nickname, description) ​

set_contact_image(nickname, images) ​

add_contact_label(nickname, labels) ​

add_contact_phone(nickname, phones) ​

add_contact_image(nickname, images) ​

remove_contact_label(nickname, labels) ​

remove_contact_phone(nickname, phones) ​

remove_contact_image(nickname, images) ​

collect_contact_image(nickname, images) ​

save_contact_image(nickname, images, save_path) ​

set_contact_star(nickname) / cancel_contact_star(nickname) ​

black_contact(nickname) / unblack_contact(nickname) ​

delete_contact(nickname) ​

recommend_contact(nickname, receiver_nickname) ​

get_contact_permission(nickname) ​

set_friend_permission(nickname, permission="all", hide_my_posts=False, hide_their_posts=False) ​

好友申请 ​

get_new_friends() ​

iter_new_friends() ​

auto_accept_new_friend(func=None) ​

Weixin

构造方法

属性

子模块

消息发送

`send_text(nickname, content, quote=None, timeout=0)`

`send_file(nickname, file_path, quote=None, timeout=0)`

`send_image(nickname, file_path, quote=None, timeout=0)`

`send_video(nickname, file_path, quote=None, timeout=0)`

`send_at(nickname, content, at_members, quote=None, timeout=0)`

`send_emotion(nickname, keyword=None, index=0, quote=None, timeout=0)`

`send_collection(nickname, keyword, quote=None, timeout=0)`

`send_card(nickname, share)`

`send_pat(nickname)`

消息读取

`get_messages(nickname)`

`get_messages_lazy(nickname)`

`iter_messages(nickname, count=None)`

`get_recently_messages(nickname, count=None)`

`scroll_chat_to_bottom(nickname)`

`clear_chat_input(nickname)`

`paste_chat_input(nickname, content)`

`cancel_chat_quote(nickname)`

`separate_chat(nickname)`

`is_chat_pinned(nickname)`

`is_chat_muted(nickname)`

会话操作

`chat_with(nickname, chat_type=None, find_in_chat=True, find_in_separate_chat=True, find_in_visible_sessions=True)`

`chat_with_contact(nickname)`

`chat_with_room(nickname)`

`chat_with_contact_or_room(nickname)`

`chat_with_official_account(nickname)`

`chat_with_service_account(nickname)`

`open_session(nickname)`

`close_session(nickname)`

`get_sessions(count=None, speed=10)`

`iter_sessions(count=None, speed=10)`

`get_visible_sessions()`

`get_unread_sessions()`

`iter_unread_sessions()`

`get_selected_session()`

`scroll_session_to_top()` / `scroll_session_to_bottom()`

`pin_session(nickname)` / `unpin_session(nickname)`

`mark_session_as_read(nickname)` / `mark_session_as_unread(nickname)`

`mute_session(nickname)` / `unmute_session(nickname)`

`separate_session(nickname)`

`separate_session_by_click(nickname)`

`hide_session(nickname)`

`delete_session(nickname)`

`get_separate_chat(contact_name)`

`get_separate_chats()`

`create_room(nicknames)`

`create_note(content)`

`add_friend(keyword, message=None, remark=None, permission=None, hide_my_posts=False, hide_their_posts=False)`

联系人管理

`get_contact_profile(nickname)`

`set_contact_info(nickname, *, remark=None, labels=None, phones=None, description=None, images=None)`

`set_contact_remark(nickname, remark)`

`set_contact_label(nickname, labels)`

`set_contact_phone(nickname, phones)`

`set_contact_description(nickname, description)`

`set_contact_image(nickname, images)`

`add_contact_label(nickname, labels)`

`add_contact_phone(nickname, phones)`

`add_contact_image(nickname, images)`

`remove_contact_label(nickname, labels)`

`remove_contact_phone(nickname, phones)`

`remove_contact_image(nickname, images)`

`collect_contact_image(nickname, images)`

`save_contact_image(nickname, images, save_path)`

`set_contact_star(nickname)` / `cancel_contact_star(nickname)`

`black_contact(nickname)` / `unblack_contact(nickname)`

`delete_contact(nickname)`

`recommend_contact(nickname, receiver_nickname)`

`get_contact_permission(nickname)`

`set_friend_permission(nickname, permission="all", hide_my_posts=False, hide_their_posts=False)`

好友申请

`get_new_friends()`

`iter_new_friends()`

`auto_accept_new_friend(func=None)`