winautox

二、快速开始

按下面 4 步，完成「找到窗口 → 看清有哪些按钮 → 点击 → 输入」。
每一步都配有完整可运行代码和「这一步在干什么」的说明。

请先完成 环境配置和安装，并保持记事本已打开（或你自己的目标窗口）。

核心概念（先花 1 分钟看懂）

名词白话解释
HWND窗口的身份证号（一个整数）。找到它，才能操作这个窗口。
ClassName窗口/控件的「类型名」，如记事本主窗常见 Notepad。
标题窗口标题栏文字。可用「包含」匹配，不必写全。
控件窗口里的按钮、输入框、列表项等。
Name / aid控件显示名 / AutomationId。有 aid 时优先用 aid，更稳。
mode='uia'用系统无障碍接口操作控件，新手首选。

学习路径建议：本页跑通 → 示例代码 → 方法手册总览。

1. 绑定窗口

目标：让程序知道「要操作哪一个窗口」。

from winautox import WinAuto
import time

# 方式 A：标题「包含」关键字（弹窗、动态标题更稳，推荐）
hwnd = WinAuto.find_hwnd('Notepad', '记事本')
if not hwnd:
    # 英文系统 / 未命名文档可再试
    hwnd = WinAuto.find_hwnd('Notepad', 'Untitled') or WinAuto.find_hwnd('Notepad', '无标题')
if not hwnd:
    raise RuntimeError('请先打开记事本')

auto = WinAuto(hwnd, mode='uia')   # 绑定 + 选定操作模式
auto.activate()                    # 激活到前台（很重要）
time.sleep(0.3)                    # 给界面一点反应时间
print('已绑定 hwnd=', auto.hwnd)

快捷写法（效果相同）：

auto = WinAuto.from_find_hwnd('Notepad', '记事本', mode='uia')
auto.activate()
time.sleep(0.3)

不知道 ClassName？

  1. 用本库后面的「导出控件树」，看打印里的 class=
  2. 或用桌面软件「控件浏览器」点选窗口，看生成的代码

换自己的软件时：把 'Notepad' 和 '记事本' 改成实际 ClassName / 标题关键字即可。

2. 导出控件树（最重要的一步）

目标：看清窗口上有哪些按钮、输入框，以及它们的 Name / aid。
不 dump 就瞎猜 Name，是新手最常卡住的原因。

# 接上一步的 auto
wins = auto.dump_windows_controls(
    max_windows=10,   # 最多导出几个顶层窗
    max_lines=500,    # 每个窗最多打印多少行控件
)
WinAuto.print_windows_dump(wins)

在终端输出里用编辑器搜索，例如搜索 文件、编辑、按钮上的文字。典型一行类似：

ButtonControl  Name="文件"  AutomationId=""  ClassName="..."

请记下：

字段对应参数说明
控件类型名ctrl_type=如 ButtonControl、EditControl
Namename=界面上看得见的字
AutomationIdaid=有则优先，比 Name 更稳
ClassNamecls=可选辅助条件

桌面软件也可以可视化点选控件并生成代码，见 软件附录。

3. 查找并点击

目标：根据上一步记下的 Name，点一下按钮。

# 写法 1：直接按名字点（内部会先 find）
auto.click(name='文件', mode='uia')

# 写法 2：先找到，再判断，再点（更适合调试）
btn = auto.find(ctrl_type='ButtonControl', name='文件', depth=15)
if btn:
    print('找到按钮，准备点击')
    auto.click(btn, mode='uia')
else:
    print('没找到。请回到第 2 步 dump，核对 Name 是否一字不差（含空格）。')

小技巧：

  • depth 太小可能找不到深层控件，可试 15～32
  • 同名控件多个时，加上 aid= 或 cls= 缩小范围
  • UIA 点不动时，可试 mode='mouse'，或 拟人点击

更多点击方式：查找与点击。

4. 输入文字

目标：往编辑框写入文字（中文请用粘贴方式）。

edit = auto.find(ctrl_type='EditControl', depth=10)
if not edit:
    edit = auto.find(ctrl_type='DocumentControl', depth=10)
if not edit:
    raise RuntimeError('没找到编辑框，请先 dump 控件树')

# paste=True：先写入剪贴板再 Ctrl+V，中文最稳
auto.input('hello winautox', ctrl=edit, paste=True)
auto.keys('{Enter}', edit)   # 模拟回车（可选）

一步完成「点输入框 + 输入 + 回车」可用 send_msg（需能定位到输入框）：

auto.send_msg('你好', ctrl_type='EditControl')  # 按你的实际 aid/name 传参

详见 输入与键盘。

完整小例子（记事本从头到尾）

把下面整段保存为 quickstart.py，打开记事后运行：

# -*- coding: utf-8 -*-
from winautox import WinAuto
import time

hwnd = (
    WinAuto.find_hwnd('Notepad', '记事本')
    or WinAuto.find_hwnd('Notepad', '无标题')
    or WinAuto.find_hwnd('Notepad', 'Untitled')
)
if not hwnd:
    raise RuntimeError('请先打开记事本')

auto = WinAuto(hwnd, mode='uia', delay=0.15)
auto.activate()
time.sleep(0.3)

# 可选：第一次先看控件树
# WinAuto.print_windows_dump(auto.dump_windows_controls(max_windows=5, max_lines=200))

edit = (
    auto.find(ctrl_type='EditControl', depth=10)
    or auto.find(ctrl_type='DocumentControl', depth=10)
)
if not edit:
    raise RuntimeError('未找到编辑区')

auto.clear_input(ctrl=edit)                      # 清空（Ctrl+A + Delete）
auto.input('快速开始成功', ctrl=edit, paste=True)
print('当前内容预览:', auto.copy(edit))
print('完成。接下来打开方法手册继续学。')

✅ 能打印「快速开始成功」相关内容，说明你已经完成第一次自动化。

学完本页之后去哪

想做什么去哪看
多抄几个现成例子示例代码
查全部方法方法手册总览
点不准 / 坐标点击查找与点击
复制图文、笔记剪贴板
用软件试跑再生成代码软件附录
报错排查常见问题

上一页环境配置和安装 · 下一页示例代码