uiautomation 模块

不要使用 3.7.6 和 3.8.1 版本，comtypes 在这两个版本中无法正常工作。请安装较早版本或最新版本。 https://github.com/enthought/comtypes/issues/202

该模块适用于 Windows 上的 UIAutomation（Windows XP SP3、Windows Vista、Windows 7 和 Windows 8/8.1/10）。它支持已实现 UIAutomation Provider 的应用程序的 UIAutomation，如 MFC、Windows Form、WPF、Modern UI（Metro UI）、Qt（部分支持）、Firefox（版本<=56 或 >=60）、Chrome 和基于 Electron 的应用（需要 --force-renderer-accessibility 命令行参数）。

我在业余时间开发了它，用于个人用途。

uiautomation 基于 Apache 许可证 2.0 共享。这意味着代码可以自由复制和分发，使用时无需任何费用。

uiautomation1.x 支持 py2、py3，且不依赖任何第三方包。

uiautomation2.0+ 仅支持 py3，并依赖 comtypes 和 typing（Python3.5+ 内置）。 uiautomation2.0+ 与早期版本不向后兼容。请参阅 API 变更。

你可以通过"pip install uiautomation"安装 uiautomation。安装完成后，调用 uiautomation 的 automation.py 将位于"C:\PythonXX\Scripts"中。你可以使用此脚本遍历 UI 控件。

运行"C:\PythonXX\Scripts\automation.py -h"获取帮助。运行 demos\automation_calculator.py 查看简单演示。

在 Windows 8/8.1 上，要自动化 Metro 应用，该应用必须位于前台。如果 Metro 应用切换到后台，uiautomation 将无法获取其控件信息。

另外，你应该以管理员身份运行 Python。否则，在 Windows 7 或更高版本上，uiautomation 可能无法枚举控件或获取控件信息。

系统要求：

Microsoft UIAutomation 最低支持客户端： Windows 7、Windows Vista SP2 及 Platform Update for Windows Vista、Windows XP SP3 及 Platform Update for Windows Vista [仅桌面应用]

Microsoft UIAutomation 最低支持服务器： Windows Server 2008 R2、Windows Server 2008 SP2 及 Platform Update for Windows Server 2008、Windows Server 2003 SP2 及 Platform Update for Windows Server 2008 [仅桌面应用]

C++ dll 源代码：UIAutomationClient

如何使用 uiautomation？运行 'automation.py -h'

了解 automation.py 的参数，并尝试以下示例： automation.py -t 0 -n，打印当前活动窗口的控件，显示全名 automation.py -r -d 1 -t 0，打印桌面（控件树的根）及其子控件（顶层窗口）

顶层窗口

automation.py 打印控件的属性及其支持的模式。你可以使用控件和模式获取控件信息并操作它们。

控件应该支持某些模式，或根据其控件类型有条件地支持某些模式。

参考 UI Automation 客户端的控件模式映射获取完整的控件模式表。

uiautomation 根据你提供的控件属性从控件树中搜索控件。

假设控件树如下：

根（Name='Desktop'，Depth=0）　　窗口1（Depth=1）　　　　控件1-001（Depth=2）　　　　控件1-...（Depth=2）　　　　... 　　　　控件1-100（Depth=2）　　窗口2（Name='window2'，Depth=1）　　　　控件2-1（Depth=2）　　　　　　控件2-1-001（Depth=3）　　　　　　控件2-1-...（Depth=3）　　　　　　... 　　　　　　控件2-1-100（Depth=3）　　　　控件2-2（Depth=2）　　　　控件2-3（Depth=2）　　　　控件2-4（Name='2-4'，Depth=2）　　　　　　编辑控件（Name='myedit1'，Depth=3）　　　　　　编辑控件（Name='myedit2'，Depth=3）

如果你想找到名为"myedit2"的编辑控件并输入"hi"，你可以编写以下代码：

uiautomation.EditControl(searchDepth=3, Name='myedit2').SendKeys('hi')

但这段代码运行速度较慢，因为在控件树中 myedit2 之前有超过 200 个控件。如果从根节点搜索深度为 3，uiautomation 必须遍历超过 200 个控件才能找到 myedit2。更好的方法是：

window2 = uiautomation.WindowControl(searchDepth=1, Name='window2') # 搜索 2 次
sub = window2.Control(searchDepth=1, Name='2-4')    # 搜索 4 次
edit = sub.EditControl(searchDepth=1, Name='myedit2')   # 搜索 2 次
edit.SendKeys('hi')

这段代码运行速度比之前的更快。你也可以将四行代码合并成一行。

uiautomation.WindowControl(searchDepth=1, Name='window2').Control(searchDepth=1, Name='2-4').EditControl(searchDepth=1, Name='myedit2').SendKeys('hi')

现在让我们以notepad.exe为例。启动notepad.exe并运行automation.py -t 3，然后切换到记事本并等待5秒

automation.py将打印记事本的控件并将它们保存到@AutomationLog.txt中：

ControlType: PaneControl ClassName: #32769 Name: 桌面 Depth: 0 （桌面窗口，根控件） 　　ControlType: WindowControl ClassName: Notepad Depth: 1 （顶级窗口） 　　　　ControlType: EditControl ClassName: Edit Depth: 2 　　　　　　ControlType: ScrollBarControl ClassName: Depth: 3 　　　　　　　　ControlType: ButtonControl ClassName: Depth: 4 　　　　　　　　ControlType: ButtonControl ClassName: Depth: 4 　　　　　　ControlType: ThumbControl ClassName: Depth: 3 　　　　ControlType: TitleBarControl ClassName: Depth: 2 　　　　　　ControlType: MenuBarControl ClassName: Depth: 3 　　　　　　　　ControlType: MenuItemControl ClassName: Depth: 4 　　　　　　ControlType: ButtonControl ClassName: Name: 最小化 Depth: 3 （最小化按钮） 　　　　　　ControlType: ButtonControl ClassName: Name: 最大化 Depth: 3 （最大化按钮） 　　　　　　ControlType: ButtonControl ClassName: Name: 关闭 Depth: 3 （关闭按钮） ...

运行以下代码

# -*- coding: utf-8 -*-
# 此脚本仅适用于Win32版本的notepad.exe
# 如果你的notepad.exe是Windows 11中的Windows Store版本，你需要卸载它。
import subprocess
import uiautomation as auto

def test():
    print(auto.GetRootControl())
    subprocess.Popen('notepad.exe', shell=True)
    # 你应该先找到顶级窗口，然后从顶级窗口中查找子控件
    notepadWindow = auto.WindowControl(searchDepth=1, ClassName='Notepad')
    if not notepadWindow.Exists(3, 1):
        print('无法找到记事本窗口')
        exit(0)
    print(notepadWindow)
    notepadWindow.SetTopmost(True)
    # 在notepadWindow中查找第一个EditControl
    edit = notepadWindow.EditControl()
    # 通常你不需要捕获异常
    # 但如果遇到COMError异常，将其放在try块中
    try:
        # 使用值模式获取或设置值
        edit.GetValuePattern().SetValue('Hello')# 或者 edit.GetPattern(auto.PatternId.ValuePattern)
    except auto.comtypes.COMError as ex:
        # 可能你没有以管理员身份运行Python
        # 或者控件没有实现此模式方法（对此我没有解决方案）
        pass
    edit.SendKeys('{Ctrl}{End}{Enter}World')
    print('当前文本:', edit.GetValuePattern().Value)
    # 在notepadWindow中查找第一个TitleBarControl，
    # 然后在TitleBarControl中查找第二个ButtonControl，即最大化按钮
    notepadWindow.TitleBarControl().ButtonControl(foundIndex=2).Click()
    # 在notepadWindow中查找第一个Name为'关闭'的按钮，即关闭按钮
    # 从关闭按钮到记事本窗口的相对深度为2
    notepadWindow.ButtonControl(searchDepth=2, Name='关闭').Click()
    # 然后记事本会弹出一个窗口询问你是否保存，按快捷键alt+n不保存
    auto.SendKeys('{Alt}n')

if __name__ == '__main__':
    test()

auto.GetRootControl()返回根控件（桌面窗口） auto.WindowControl(searchDepth=1, ClassName='Notepad')创建一个WindowControl，参数指定如何搜索控件可以使用以下参数 searchFromControl = None, searchDepth = 0xFFFFFFFF, searchInterval = SEARCH_INTERVAL, foundIndex = 1 Name SubName RegexName ClassName AutomationId ControlType Depth Compare

参数的注释请参见Control.init。更多示例请参见demos文件夹中的脚本。

Control.Element返回低级COM对象IUIAutomationElement， Control的几乎所有方法和属性都是通过IUIAutomationElement COM API和Win32 API实现的。当调用间接调用Control.Element的控件方法或属性，且Control.Element为None时， uiautomation开始根据你提供的属性搜索控件。如果uiautomation在uiautomation.TIME_OUT_SECOND（默认10秒）内找不到控件，将引发LookupError异常。如果uiautomation成功找到控件，Control.Element将具有有效值。你可以使用Control.Exists(maxSearchSeconds, searchIntervalSeconds)检查控件是否存在，此函数不会引发任何异常。调用Control.Refind或Control.Exists使Control.Element再次无效，uiautomation将开始新的搜索。

例如：

#!python3
# -*- coding:utf-8 -*-
# 此脚本仅适用于Win32版本的notepad.exe
# 如果你的notepad.exe是Windows 11中的Windows Store版本，你需要卸载它。
import subprocess
import uiautomation as auto
auto.uiautomation.SetGlobalSearchTimeout(15)  # 设置新的超时时间为15秒
def main():
    subprocess.Popen('notepad.exe', shell=True)
    window = auto.WindowControl(searchDepth=1, ClassName='Notepad')
    # 或使用Compare进行自定义搜索
    # window = auto.WindowControl(searchDepth=1, ClassName='Notepad', Compare=lambda control,depth:control.ProcessId==100)
    edit = window.EditControl()
    # 调用SendKeys时，uiautomation会在15秒内开始搜索窗口和编辑控件
    # 因为SendKeys间接调用Control.Element，而Control.Element为None
    # 如果窗口和编辑控件在15秒内不存在，将引发LookupError异常
    try:
        edit.SendKeys('第一个记事本')
    except LookupError as ex:
        print("15秒内未找到第一个记事本")
        return
    # 第二次调用SendKeys不会触发搜索，之前的调用已确保Control.Element有效
    edit.SendKeys('{Ctrl}a{Del}')
    window.GetWindowPattern().Close()  # 关闭第一个记事本，即使window和edit的Elements有值，它们也变得无效

    subprocess.Popen('notepad.exe')  # 运行第二个记事本
    window.Refind()  # 需要重新查找窗口，触发新的搜索
    edit.Refind()  # 需要重新查找编辑控件，触发新的搜索
    edit.SendKeys('第二个记事本')
    edit.SendKeys('{Ctrl}a{Del}')
    window.GetWindowPattern().Close()  # 关闭第二个记事本，window和edit再次变为无效

    subprocess.Popen('notepad.exe')  # 运行第三个记事本
    if window.Exists(3, 1): # 触发新的搜索
        if edit.Exists(3):  # 触发新的搜索
            edit.SendKeys('第三个记事本')  # edit.Exists确保edit.Element现在有有效值
            edit.SendKeys('{Ctrl}a{Del}')
        window.GetWindowPattern().Close()
    else:
        print("3秒内未找到第三个记事本")


if __name__ == '__main__':
    main()