Skip to main content

Window：Windows 窗口自动化核心类

Window 类提供了对 Windows 窗口最全面的控制能力，支持后台点击、输入、精准坐标控制及高清截图。

1. 导入模块​

在开始编写代码前，请先导入核心类及相关枚举：

# 导入窗口操作核心类及截图格式枚举
from ascript.windows.window import Window

2. 静态方法（找窗口、开程序）​

🔍 批量查找 find_all()​

扫描当前系统中所有满足条件的窗口。

代码块：

# 扫描并返回满足条件的窗口对象列表
Window.find_all(title_re=None, process_name=None, class_name=None, visible_only=True)

参数详解：

  • title_re (str): 窗口标题的正则表达式。
  • process_name (str): 进程名称（如 "chrome.exe"），匹配时忽略大小写。
  • class_name (str): 窗口的系统类名（ClassName），需完全匹配。
  • visible_only (bool): 是否只匹配当前对用户可见的窗口。默认为 True。

案例：

# 找到所有名为“微信”的窗口并打印它们的句柄
wins = Window.find_all(title_re="微信")
for w in wins:
    print(f"找到句柄: {w.hwnd}")

🎯 快速检索 find()​

查找并返回满足条件的第一个窗口。

代码块：

# 查找满足条件的第一个窗口对象
Window.find(title_re=None, process_name=None, class_name=None, visible_only=True, timeout=0)

参数详解：

  • title_re (str): 窗口标题的正则表达式。
  • process_name (str): 进程名称。
  • class_name (str): 窗口的系统类名。
  • visible_only (bool): 是否只匹配可见窗口。
  • timeout (int): 检索超时时间（秒）。为 0 时立即返回；大于 0 时将以 0.5s 为间隔持续轮询。

案例：

# 等待记事本打开，最多等 10 秒
win = Window.find(process_name="notepad.exe", timeout=10)

⚡ 启动程序 launch()​

启动目标程序，并自动获取其窗口对象。

代码块：

# 启动程序并自动关联窗口
Window.launch(name=None, path=None, allow_multiple=False, timeout=15)

参数详解：

  • name (str): 程序标识名。
  • path (str): 程序可执行文件的完整物理路径。
  • allow_multiple (bool): 是否允许启动多个实例。若为 False 且程序已运行，则直接唤醒现有窗口。
  • timeout (int): 等待新窗口生成的超时秒数。

案例：

# 启动记事本
win = Window.launch(path="notepad.exe")

3. 实例方法（窗口操控）​

3.1 布局控制​

📐 综合调整 set_rect()​

统一修改窗口的位置和大小。

代码块：

# 调整窗口的坐标和宽高
win.set_rect(x=None, y=None, width=None, height=None)

参数详解：

  • x (int): 目标左上角 X 轴坐标。为 None 则保持当前位置。
  • y (int): 目标左上角 Y 轴坐标。为 None 则保持当前位置。
  • width (int): 目标宽度。为 None 则保持当前数值。
  • height (int): 目标高度。为 None 则保持当前数值。

案例：

# 将窗口移动到 (100, 100) 并设置宽高为 800x600
win.set_rect(x=100, y=100, width=800, height=600)

📍 移动位置 move()​

仅修改窗口在屏幕上的位置。

代码块：

# 将窗口移动到指定坐标
win.move(x, y)

参数详解：

  • x (int): 目标 X 轴起始坐标。
  • y (int): 目标 Y 轴起始坐标。

案例：

# 将窗口挪到屏幕左上角
win.move(0, 0)

📏 修改尺寸 resize()​

仅修改窗口的大小。

代码块：

# 调整窗口的宽度和高度
win.resize(width, height)

参数详解：

  • width (int): 目标窗口宽度。
  • height (int): 目标窗口高度。

案例：

# 将窗口调整为 1024x768
win.resize(1024, 768)

3.2 交互与截图​

📸 窗口截图 capture()​

获取窗口画面。

代码块：

# 截取窗口内容
win.capture(save_path=None, format=WindowCaptureFormat.PIL, rect=None, force_activate=True)

参数详解：

  • save_path (str): 图片保存路径。若为 None 则不保存。
  • format: 输出格式。支持：WindowCaptureFormat.PIL, .NUMPY, .OPENCV。
  • rect (WindowRect): 局部区域坐标。若为 None 则截取整窗。
  • force_activate (bool): 截图前是否强制将窗口激活并置顶。

案例：

# 截图并保存为 PNG
win.capture(save_path="shot.png")

🖱️ 鼠标点击 click()​

向窗口发送后台点击消息。

代码块：

# 模拟点击窗口内的某个位置
win.click(x, y, is_relative=True, button="left")

参数详解：

  • x / y (int): 点击位置坐标。
  • is_relative (bool): 是否使用相对坐标（窗口左上角为原点）。
  • button (str): 使用的按键。支持 "left" (左键) 和 "right" (右键)。

案例：

# 在窗口相对坐标 (50, 50) 点左键
win.click(50, 50)

🖱️ 鼠标长按 long_click()​

模拟鼠标在指定位置的长按操作。

代码块：

# 在窗口内长按鼠标
win.long_click(x, y, duration=1.0, is_relative=True)

参数详解：

  • x / y (int): 坐标位置。
  • duration (float): 按下的持续时间（秒）。
  • is_relative (bool): 是否使用相对坐标。

案例：

# 在坐标 (100, 100) 处长按 2 秒
win.long_click(100, 100, duration=2.0)

🚜 鼠标拖拽 drag()​

模拟从起点到终点的平滑拖拽。

代码块：

# 模拟鼠标滑动手势
win.drag(x1, y1, x2, y2, duration=0.5, is_relative=True)

参数详解：

  • x1, y1 (int): 起始坐标。
  • x2, y2 (int): 终点坐标。
  • duration (float): 拖拽滑动的总耗时（秒）。
  • is_relative (bool): 是否使用相对坐标。

案例：

# 从 (10, 10) 拖拽到 (100, 100)
win.drag(10, 10, 100, 100)

⌨️ 文本输入 type_text()​

向窗口发送文本字符串序列。

代码块：

# 后台模拟键盘输入
win.type_text(text)

参数详解：

  • text (str): 需要输入的文本内容内容。

案例：

# 自动输入文字
win.type_text("Hello World")

3.3 状态管理​

🔝 置顶设置 set_always_on_top()​

设置或取消窗口的置顶状态。

代码块：

# 设置窗口是否永远在最前
win.set_always_on_top(toggle=True)

参数详解：

  • toggle (bool): 为 True 则置顶，False 则取消。

🌟 激活窗口 activate()​

将窗口切换至前台焦点。

代码块：

# 唤醒并激活窗口
win.activate()
  • 说明： 无参数。若窗口最小化则会自动恢复。

📉 最小化 minimize()​

将窗口最小化到任务栏。

代码块：

# 最小化窗口
win.minimize()
  • 说明： 无参数。

🚪 关闭窗口 close()​

以标准方式请求关闭窗口。

代码块：

# 关闭窗口
win.close()
  • 说明： 无参数。发送 WM_CLOSE 消息。

💀 终结进程 kill()​

强行结束窗口所属的进程。

代码块：

# 强行结束程序
win.kill()
  • 说明： 无参数。成功返回 True，失败返回 False。

4. 窗口属性 (Properties)​

这些属性可以通过 win.属性名 直接读取：

属性返回类型说明
win.titlestr获取窗口当前的标题文字
win.class_namestr获取窗口系统类名
win.pidint获取进程 ID
win.process_namestr获取进程文件名
win.process_pathstr获取程序完整路径
win.is_visiblebool判断窗口当前是否可见
win.is_minimizedbool判断窗口是否最小化
win.is_maximizedbool判断窗口是否最大化
win.is_respondingbool判断程序是否未卡死
win.is_always_on_topbool判断窗口是否置顶
win.rectWindowRect获取坐标尺寸对象

💡 终极实战案例​

# 导入模块
from ascript.windows.window import Window

# 1. 查找或启动记事本
win = Window.find(process_name="notepad.exe") or Window.launch(path="notepad.exe")

if win:
    # 2. 调整布局
    win.set_rect(x=100, y=100, width=600, height=400)
    win.activate()
    
    # 3. 自动化操作
    win.type_text("Hello, Windows Automation!")
    win.capture(save_path="result.png")