本教程介绍如何在AutoHotkey中【完结】最强windows自动化教程及UIA v2-UIAutomation的v2版本的库。包含完整的AHK代码示例、实现原理和详细说明,适合从入门到进阶的AutoHotkey开发者参考。
本教程介绍如何在AutoHotkey中【完结】最强windows自动化教程及UIA v2-UIAutomation的v2版本的库。包含完整的AHK代码示例、实现原理和详细说明,适合从入门到进阶的AutoHotkey开发者参考。
简介
这是一套使用UIAutomation 进行自动化的教程,全部课程一共11课,课程是英文课程,不够你不用担心看不懂,我已经为每节课添加中文字幕,帮你轻松看懂课程,同时,UIAutomation库的帮助文档我也已经全部翻译放在了下面,看完课程你可以轻松自动化的各种操作。目前借助UIAutomation 进行自动化可以说Autohotkey自动化的天花板了。欢迎朋友品鉴。
UIAutomation 是一个 Microsoft 辅助功能框架,允许以编程方式与用户可访问的元素(单击按钮、发送文本等)进行交互。它是 Acc/MSAA 框架的继承者。 有关详细信息,请查看 UIA 的 Microsoft 文档。
运作方式
- 使用检查工具(辅助功能见解、UIAViewer(单独运行 UIA.ahk)、inspect.exe 或 AHK v1 UIA 工具 UIAViewer、UIATreeInspector),检查您感兴趣的元素:要单击的按钮、要检查的复选框等
- 在检查工具中,找到元素的特征,您可以使用该特征将其与其他元素区分开来:这可能是 Name、AutomationId 或其他内容
- 获取起始点元素:通常是带有 UIA 的窗口元素。ElementFromHandle,带有 UIA 的根元素(桌面)。GetRootElement 等
- 将 Find 方法之一与唯一特征结合使用,从起点元素获取感兴趣的元素
- 现在,您可以获取有关元素的信息或与之交互
01.入门
下载库
首先,将库下载到您的计算机,按绿色的“代码”按钮并下载 ZIP。将 zip 文件的内容解压缩到计算机的某个位置。现在,您可以运行任何示例文件。
您还需要一个工具来检查 UIAutomation 元素。使用 UIAViewer 可以最轻松地完成此操作,UIAViewer 会在您单独运行 UIA.ahk 时打开。
什么是元素?
元素是 UIAutomation 的基本构建基块。屏幕上显示的所有内容都分为多个元素:
- “最大”元素是根元素 – 桌面本身。它包含屏幕上显示的所有元素,并且没有比它更大的元素(它在 UIA 树中没有任何父元素)。如果您有多个桌面,则只能访问当前显示的桌面。
- 桌面元素的直接子元素是窗口和任务栏:例如,如果打开记事本,则它将是 Window 类型元素,作为 Root 元素的子元素。
- 每个窗口都有一个元素树,这些元素构成窗口的内容。在这里,我们有所有的按钮、复选框、编辑元素等。小元素可能包含在较大的“容器”元素(如组)中。
UIAViewer
如果运行 UIAViewer 并单击“开始捕获”按钮,则应看到如下内容:

在这里,我们打开了一个记事本窗口,我们看到光标下方的元素用一个蓝色框突出显示(“编辑”菜单项),并显示了一些关于它的信息:
- 在“属性”列表框中,我们有一些描述元素的属性:例如,按钮的名称是“Edit”,类型是“MenuItem”,等等。UIAViewer 不会显示所有可用属性(以使其更加紧凑),但您可以使用辅助功能见解来显示所有可用属性。
- 在“模式”列表框中,我们可以看到与项目交互的不同方式。模式只是与元素交互的不同方式:例如,选项卡项通常是可选的,因此它将具有可用的 SelectionItemPattern,它具有 IsSelected 属性并包含用于选择项的 Select() 方法。按钮不可选择,也没有 SelectionItemPattern,但它通常具有用于单击 (Invoke()) 的 InvokePattern。 在记事本中,Edit MenuItem 元素具有 ExpandCollapsePattern,其中包含展开(打开“编辑”菜单)和折叠(关闭菜单)的方法,还可以获取有关其状态的信息,例如是否折叠。LegacyIAccessiblePattern 包含来自 MSAA/Acc(UIA 的前身)的信息和方法,也可用于获取有关它的一些信息并与之交互。 您可以尝试双击模式方法进行测试。
- 在右侧的 TreeView 中,我们看到 UIA 树的一部分:Edit 菜单项、同级元素、父元素,如果它有任何子元素,那么这些元素也是如此。这为我们提供了有关如何获取与此相关的其他元素的信息。
- 在底部显示了一个UIA“路径”。这可用于“旅行”到元素以访问其属性并与之交互。
记事本的 UIA 树
如果我们将鼠标悬停在某个元素上一段时间,则会显示记事本窗口的整个树(此时可以按 Esc 停止捕获)。在上图中,它显示在 UIAViewer 的右侧:在顶部,我们看到记事本窗口元素,然后是它的直接子元素(文档“文本编辑器”、状态栏“状态栏”、标题栏、菜单栏“应用程序”),子元素有自己的子元素。子元素和子元素的子元素称为后代,如果我们也包含 Window 元素,则称为子树。
若要查看有关与记事本窗互的简单示例,请转到库主文件夹中的“示例”文件夹,然后打开 Example1_Notepad.ahk:
让我们看一下这个例子:
#include ..\Lib\UIA.ahk包括主 UIA 库文件。如果您不确定 #include 是如何工作的,请在此处查看如何使用 #include。通常最简单的方法是将脚本放在 Lib 文件夹所在的同一文件夹中,然后您可以使用它来包含它。#include <UIA>npEl := UIA.ElementFromHandle("ahk_exe notepad.exe")通过使用 UIA 类中的 ElementFromHandle 方法,获取起始点元素(记事本窗口元素,在 UIAViewer 中是树顶部的最顶层元素)。 是一个新的 IUIAutomationElement 类型对象(IUIAutomation 只是告诉我们它是 UIAutomation 接口的一部分),它可用于访问所有这些元素属性(名称、类型等)、访问模式以与之交互等等。要了解有关元素的更多信息,请查看此 Wiki 的“元素类”部分。npEldocumentEl := npEl.FindElement([{Type:"Document"}, {Type:"Edit"}])在这里,我们在记事本窗口树中查找与“文档”或“编辑”类型匹配的第一个元素。在 UIAViewer 中,我们看到 window 元素的正下方有一个,这就是我们将得到的元素。与记事本窗口元素完全相同,这也是一个 IUIAutomationElement 对象。document "Text Editor"documentEl.Value := "Lorem ipsum"设置元素的 Value 属性。大多数属性无法更改(例如“名称”和“类型”),但“值”是可更改的。
或者,我们也可以使用 UIA 路径来获取 documentEl。如果我们使用 UIAViewer 检查元素,则显示的路径为 .要使用它,我们可以使用 数组表示法或使用 ElementFromPath .此方法不太可靠,因为 UIAutomation 树可能会更改,并且元素类型可以在不同的 Windows 版本之间更改。例如,在 Windows 11 中,document 元素具有路径,这意味着 ClassName 已在 Windows 10 更改为 Windows 11 。当然,我们可以手动更正它,翻译成 Type Document。{T:30,CN:"Edit"}documentEl := npEl[{T:30,CN:"Edit"}]documentEl := npEl.ElementFromPath({T:30,CN:"Edit"}){T:30,CN:"RichEditD2DPT"}EditRichEditD2DPT{T:30}
UIA 路径
有多种类型的路径可用于移动到元素,您可以通过右键单击状态栏在它们之间切换:

- UIA 路径:这是路径,只是使用元素类型和索引在树上向下移动的一种紧凑形式。对于“ABq”,“A”解码为Type MenuBar,“B”解码为Type MenuItem,q解码为索引2。这意味着我们从 Window 元素开始移动到第一个 MenuBar 元素,然后转到其第二个 MenuItem 子元素:.虽然很短且通常很可靠,但如果用户界面变化太大,这种方法很容易中断。例如,这种路径在 Microsoft Edge 中几乎从不起作用,因为根据光标是在网页中还是在 URL 栏中,第一个元素的位置会发生变化。
NotepadElement["ABq"].Name == "Edit" - 条件路径:这是一条不太紧凑的路径,它使用缩短的条件沿着树向下移动。虽然与 UIA 路径基本相同,但它也使用 ClassName、AutomationId 和可选的 Name 属性。对于相同的 Edit MenuItem 元素,路径如下所示:.这里“T”代表“Type”,“i”代表“index”,10 是 MenuBar 的 Type 值。
{T:10}, {T:11, i:2}NotepadElement["ABq"] == NotepadElement[{T:10}, {T:11, i:2}] - 数值路径:这是最不可靠的路径(最容易中断),它只使用索引在树上向下移动。对于“编辑菜单项”,这将是 ,这意味着选择了记事本元素第四个子项的第二个子项:。
4,2NotepadElement[4,2].Name == "Edit"
02. UIA树
什么是树
UIAutomation 框架将整个桌面以及所有窗口和控件保存在由元素组成的大树中。顶部是根元素:桌面本身。桌面元素直接子元素是所有窗口(记事本、Chrome 等),然后窗口又具有子元素(工具栏、主要内容、按钮等)等。
UIAutomation 树不是一个固定的结构。例如,如果窗口关闭,则其元素及其所有子元素都将被销毁。当网页重新加载或导航到新页面时,浏览器窗口的树也会随着更改而更新。有时,树的某些部分不会立即可用,而仅在客户端需要它们时构造(例如,用鼠标将鼠标悬停在元素上)。
访问整个树通常是不可取的,因为它包含数千个元素,并且从中搜索我们感兴趣的元素可能需要很长时间。通常,我们尝试获取树的较小部分,例如窗口元素,而对于大型复杂窗口,甚至获取树的较小部分。
访问树
有多种方法可以从树中获取元素,在这里我们介绍一些更重要的方法。要访问树,我们需要使用主 UIA 类。在本 Wiki 的“UIA 类”部分阅读有关此内容的更多信息。
GetRootElement
UIA.GetRootElement()
调用将为我们提供根或 Desktop 元素。这包含整个桌面。如果有多个桌面,则只能访问当前可见的桌面。UIA.GetRootElement
ElementFromHandle
UIA.ElementFromHandle(hwnd:="", cacheRequest:=0, activateChromiumAccessibility:=500)
ElementFromHandle 通常仅与 hwnd 参数一起使用:
- hwnd 可以是 WinTitle、窗口句柄(返回主窗口的 UIA 元素)或控件句柄(返回控件的 UIA 句柄)。要获取记事本窗口的元素,我们可以使用
notepadEl := UIA.ElementFromHandle("ahk_exe notepad.exe") - cacheRequest:缓存请求对象(可选)。在本 Wiki 的缓存部分阅读更多内容。
- activateChromiumAccessibility:一些窗口实际上是基于 Chromium 的 Web 应用程序,与 Chrome 和 Edge 浏览器所基于的相同。有时,UIA 的辅助功能不会自动激活,因此 ElementFromHandle 可能需要向窗口发送其他信号。如果设置了 activateChromiumAccessibility ,则在未启用 UIA 的情况下,它会尝试激活 UIA。该值本身将决定等待激活确认的时间。如果传递了 VarRef,则该变量将设置为 Chromium Document 元素(仅当激活完成时)。
元素从点
UIA.ElementFromPoint(x?, y?, cacheRequest:=0, activateChromiumAccessibility:=500)
ElementFromPoint 顾名思义:从屏幕坐标中获取元素。如果未提供坐标,则使用当前鼠标位置。(可选)可以提供缓存请求,并且 activateChromiumAccessibility 的工作方式与 ElementFromHandle 中的工作方式相同。
注意:默认情况下,AutoHotkey MouseGetPos 返回相对于活动窗口的坐标。确保将其更改为屏幕坐标CoordMode "Mouse", "Screen"
GetFocusedElement
UIA.GetFocusedElement(cacheRequest:=0)
检索具有输入焦点的元素,如文本框或按钮。该元素可能仍具有子元素。
元素从铬
UIA.ElementFromChromium(winTitle:="", activateChromiumAccessibility:=500, cacheRequest:=0)
从 Chromium 应用(基于 Web 浏览器的应用程序,如 Skype、Discord 等)中检索 Chromium 元素。activateChromiumAccessibility 的工作方式与 ElementFromHandle 中的工作方式相同(设置超时,如果提供了 VarRef,则将其设置为 Chromium 文档元素)。
ElementFromIAccessible
UIA.ElementFromIAccessible(IAcc, childId:=0)
从 MSAA/Acc 对象(UIA 的前身)获取元素。这仅适用于窗口本机实现 IAccessible 的 Acc 对象,其中不包括大多数 Win32 窗口(如记事本、Windows 资源管理器等)。不鼓励使用此方法,因为 UIA 通常具有更可靠的方法来获取可用的元素。
在树上四处走动
可以通过多种方式从树中的一个元素移动到另一个元素:
FindElement/WaitElement/ElementExist
一种方法是使用具有适当条件的 FindElement/WaitElement/ElementExist 方法(它们都从 Element 对象开始)。例如。在此 Wiki 中阅读有关 Condition 对象和 Element 方法的更多信息。Element.FindElement({Name:"Something"})
数组表示法
“数组表示法”可用于逐级遍历树级别。这可以通过条件对象和/或逗号分隔路径来完成。 示例 1:将返回 Elements 的第一个子项的第二个子项。 示例 2:将首先返回 Elements Button-type childs first “Something”命名元素。Element[1,2]Element[{Type:"Button"}, {Name:"Something}]
ElementFromPath/WaitElementFromPath/ElementFromPathExist
使用 ElementFromPath/WaitElementFromPath/ElementFromPathExist 的遍历看起来与 Array 表示法非常相似,前面的示例如下所示: 和Element.ElementFromPath("1,2")Element.ElementFromPath({Type:"Button"}, {Name:"Something})
WalkTree(沃克树酒店)
这是使用 TreeWalkers 遍历树的简单方法。在有关 TreeWalkers 的部分中查看更多信息。
树行者
本 Wiki 的 TreeWalker 部分介绍了 TreeWalkers 的使用。这些很少需要使用。
03. UIA主函数类
UIA 接口/类是 UIA.ahk 库的主要对象。它是我们用来访问元素、与一些常规 UIA 属互、创建条件、TreeWalkers、添加事件处理程序等的起点。
初始化
UIA 在首次使用 UIA 类时初始化,例如 .默认情况下,IUIAutomation 的最高可用版本已初始化,这取决于你的 Windows 版本:对于 Windows 11,它通常是版本 7。若要将 UIA 限制为某个 IUIAutomation 版本(以便脚本在较旧的 Windows 版本上正常运行),请在使用 UIA 之前更改 IUIAutomationMaxVersion 全局变量。 UIA 的运行版本存储在 UIA 中。IUIAutomationVersion。UIA.ElementFromHandle
以下是提供 IUIAutomation 版本的 Windows 版本:
- IUIAutomation : Windows 7、Windows Vista SP2 和 Windows Vista 的平台更新、Windows XP SP3 和 Windows Vista 的平台更新
- IUIAutomation2:Windows 8
- IUIAutomation3:Windows 8.1
- IUIAutomation4:Windows 10 版本 1607IUIAutomation4: Windows 10, version 1607
- IUIAutomation5:Windows 10 版本 1607IUIAutomation5: Windows 10, version 1607
- IUIAutomation6:Windows 10 版本 1809IUIAutomation6: Windows 10, version 1809
UIA 对象
UIAutomation 接口公开了一些方法,这些方法使我们能够发现、访问和筛选 UI 自动化元素。此接口的成员不特定于特定元素。
性能
- IUIAutomationMaxVersion:当前正在运行的版本
- TrueCondition :包含一个 True 条件
- TreeWalkerTrue :包含使用 True 条件创建的 TreeWalker
- ControlViewWalker:参见 TreeWalkers 部分
- ContentViewWalker:参见 TreeWalkers 部分
- RawViewWalker :参见 TreeWalkers 部分
- RawViewCondition:请参阅“条件”部分
- ControlViewCondition:请参阅“条件”部分
- ContentViewCondition:请参阅“条件”部分
- ProxyFactoryMapping(代理工厂映射)
- ReservedNotSupportedValue
- ReservedMixedAttributeValue
IUIAutomation2 属性 [从 Windows 8 及更高版本提供]
- AutoSetFocus:指定对 UI 自动化控件模式方法的调用是否自动将焦点设置为目标元素。默认值为 True。可以获取和设置此属性。
- ConnectionTimeout:指定 UI 自动化等待提供程序响应自动化元素的客户端请求的时间长度。默认值为 20000 毫秒(20 秒),最小值似乎是 50 毫秒。可以获取和设置此属性。
- TransactionTimeout:指定UI自动化等待提供程序响应客户端请求以获取有关自动化元素的信息的时间长度。默认值为 2000 毫秒(2 秒),最小值似乎是 50 毫秒。可以获取和设置此属性。
IUIAutomation6 属性 [从 Windows 10 版本 1809 及更高版本提供]
- ConnectionRecoveryBehavior :指示可访问技术客户端在提供程序无响应时是否调整提供程序请求超时。
- CoalesceEvents:获取或设置可访问的技术客户端是接收所有事件,还是接收检测和筛选重复事件的子集。
枚举
UIA 类还包含许多值,这些值可用作方法的参数。可以作为 UIA.Enumeration.Name 访问这些名称,也可以作为 UIA 从值中获取名称。枚举[Value]。例如,是值 ,而等于字符串 。在大多数情况下,您可以在需要时使用枚举名称,并且库会自动使用正确的枚举:例如,将“Type”替换为“UIA”。Property.ControlType“值和带有”UIA.ControlType.Button“值。 如果需要合并枚举,则可以使用管道“|”运算符来完成此操作:UIA.ControlType.Button50000UIA.ControlType[50000]ButtonUIA.CreateCondition("Type", "Button")UIA.TreeScope.Family == UIA.TreeScope.Element | UIA.TreeScope.Children
控件类型
这些都是元素可以是的不同类型。元素的类型还决定了哪些属性和模式可供其使用。例如,按钮通常具有可用的 InvokePattern;CheckBox 具有可用的 TogglePattern 和 ToggleState。
按钮、日历、复选框、组合框、编辑、超链接、图像、列表项、列表、菜单、菜单栏、菜单项、进度条、单选按钮、滚动条、滑块、微调器、状态栏、选项卡、TabItem、文本、工具栏、工具提示、树、树项、自定义、组、拇指、数据网格、数据项、文档、拆分按钮、窗口、窗格、标题、标题项、表、标题栏、分隔符、语义缩放、应用栏
属性
属性名称可用于访问元素属性。 将返回元素的 Name 属性。Element.Name
RuntimeId、BoundingRectangle、ProcessId、ControlType(缩写形式:Type)、LocalizedControlType、Name、AcceleratorKey、AccessKey、HasKeyboardFocus、IsKeyboardFocusable、IsEnabled、AutomationId、ClassName、HelpText、ClickablePoint、Culture、IsControlElement、IsContentElement、LabeledBy、IsPassword、NativeWindowHandle、ItemType、IsOffscreen、Orientation、FrameworkId、IsRequiredForForm、ItemStatus、IsDockPatternAvailable、IsExpandCollapsePatternAvailable、IsGridItemPatternAvailable、 IsGridPatternAvailable、IsInvokePatternAvailable、IsMultipleViewPatternAvailable、IsRangeValuePatternAvailable、IsScrollPatternAvailable、IsScrollItemPatternAvailable、IsSelectionItemPatternAvailable、IsSelectionPatternAvailable、IsTablePatternAvailable、IsTableItemPatternAvailable、IsTextPatternAvailable、IsTogglePatternAvailable、IsTransformPatternAvailable、IsValuePatternAvailable、IsWindowPatternAvailable、ValueValue、Value、ValueIsReadOnly、RangeValueValue、RangeValueIsReadOnly、RangeValueMinimum、RangeValueMaximum、RangeValueLargeChange、RangeValueSmallChange、ScrollHorizontalScrollPercent、ScrollHorizontalViewSize、ScrollVerticalScrollPercent、ScrollVerticalViewSize、ScrollHorizontallyScrollable、ScrollVerticallyScrollable、SelectionSelection、SelectionCanSelectMultiple、SelectionIsSelectionRequired、GridRowCount、GridColumnCount、GridItemRow、GridItemColumnSpan、GridItemContainingGrid、DockDockPosition、ExpandCollapseExpandCollapseState、MultipleViewCurrentView、MultipleViewSupportedViews、WindowCanMaximize、WindowCanMinimize、WindowWindowVisualState、WindowWindowInteractionState、WindowIsModal、WindowIsTopmost、SelectionItemIsSelected、SelectionItemSelectionContainer、TableRowHeaders、TableColumnHeaders、TableRowOrColumnMajor、TableItemRowHeaderItems、TableItemColumnHeaderItems、ToggleToggleState、TransformCanMove、TransformCanResize、TransformCanRotate、IsLegacyIAccessiblePatternAvailable、LegacyIAccessibleChildId、LegacyIAccessibleName、LegacyIAccessibleValue、LegacyIAccessibleDescription、LegacyIAccessibleRole、LegacyIAccessibleState、LegacyIAccessibleHelp、LegacyIAccessibleKeyboardShortcut、LegacyIAccessibleSelection、LegacyIAccessibleDefaultAction、AriaRole、AriaProperties、IsDataValidForForm、ControllerFor、DescribedBy、FlowsTo、ProviderDescription、IsItemContainerPatternAvailable、IsVirtualizedItemPatternAvailable、IsSynchronizedInputPatternAvailable、OptimizeForVisualContent、IsObjectModelPatternAvailable、AnnotationAnnotationTypeId、AnnotationAnnotationTypeName、AnnotationAuthor、AnnotationDateTime、AnnotationTarget、IsAnnotationPatternAvailable、IsTextPattern2Available、StylesStyleId、StylesStyleName、StylesFillColor、StylesFillPatternStyle、StylesShape、StylesFillPatternColor、StylesExtendedProperties、IsStylesPatternAvailable、IsSpreadsheetPatternAvailable、SpreadsheetItemFormula、SpreadsheetItemAnnotationObjects、SpreadsheetItemAnnotationTypes、IsSpreadsheetItemPatternAvailable、Transform2CanZoom、IsTransformPattern2Available、LiveSetting、IsTextChildPatternAvailable、IsDragPatternAvailable、DragIsGrabbed、DragDropEffect、DragDropEffects、IsDropTargetPatternAvailable、DropTargetDropTargetEffect、DropTargetDropTargetEffects、DragGrabbedItems、Transform2ZoomLevel、Transform2ZoomMinimum、Transform2ZoomMaximum、FlowsFrom、IsTextEditPatternAvailable、IsPeripheral、IsCustomNavigationPatternAvailable、PositionInSet、SizeOfSet、Level、AnnotationTypes、AnnotationObjects、LandmarkType、LocalizedLandmarkType、FullDescription、FillColor、OutlineColor、FillType、VisualEffects、OutlineThickness、CenterPoint、Rotation、Size、IsSelectionPattern2Available、Selection2FirstSelectedItem、Selection2LastSelectedItem、Selection2CurrentSelectedItem、Selection2ItemCount、IsDialog
有一些自定义属性(这意味着它们不能与 Find 方法一起使用):
位置、存在、子项、父项
模式
根据元素的类型确定元素具有的专用方法和属性类型。有关详细信息,请参阅本 Wiki 中的“模式”部分。
调用、选择、值、范围值、滚动、ExpandCollapse、网格、GridItem、MultipleView、窗口、SelectionItem、停靠、表、TableItem、文本、切换、转换、ScrollItem、LegacyIAccessible、ItemContainer、VirtualizedItem、SynchronizedInput、ObjectModel、注释、样式、电子表格、SpreadsheetItem、TextChild、拖动、DropTarget、TextEdit、CustomNavigation
事件
可以将事件注册到事件处理程序,以检测用户界面中的更改。
ToolTipOpened、ToolTipClosed、StructureChanged、MenuOpened、AutomationPropertyChanged、AutomationFocusChanged、AsyncContentLoaded、MenuClosed、LayoutInvalidated、Invoke_Invoked、SelectionItem_ElementAddedToSelection、SelectionItem_ElementRemovedFromSelection、SelectionItem_ElementSelected、Selection_Invalidated、Text_TextSelectionChanged、Text_TextChanged、Window_WindowOpened、Window_WindowClosed、MenuModeStart、MenuModeEnd、InputReachedTarget、InputReachedOtherElement、 InputDiscarded、 SystemAlert、 LiveRegionChanged、 HostedFragmentRootsInvalidated、 Drag_DragStart、 Drag_DragCancel、 Drag_DragComplete、 DropTarget_DragEnter、 DropTarget_DragLeave、 DropTarget_Dropped、 TextEdit_TextChanged、 TextEdit_ConversionTargetChanged、 更改、 通知、 ActiveTextPositionChanged
树状体
在 Find 方法中用于确定搜索范围。
没有 元素:仅元素本身 儿童:直接子女 家庭:元素和直系子女 后代:子树及其子树 子树 :元素本身、其子项及其子树 父级 : 未使用 祖先 : 未使用
匹配模式
在条件中用于更改字符串值的匹配模式。默认情况下,FindElement(s) 方法的匹配模式为 Exact,因此仅找到完全匹配项。
StartsWith、子字符串、精确、正则表达式
TreeTraversalOptions
可用于在 FindElement 方法中自定义树导航顺序。
默认值、PostOrder、LastToFirstOrder
其他枚举列表
TextAttribute:文本内容的格式和样式属性(文本属性)
AnimationStyle、BackgroundColor、BulletStyle、CapStyle、Culture、FontName、FontSize、FontWeight、ForegroundColor、HorizontalTextAlignment、IndentationFirstLine、IndentationLeading、IndentationTrailing、IsHidden、IsItalic、IsReadOnly、IsSubscript、IsSuperscript、MarginBottom、MarginLeading、MarginTop、MarginTrailing、OutlineStyles、OverlineColor、OverlineStyle、StrikethroughColor、StrikethroughStyle、Tabs、TextFlowDirections、UnderlineColor、UnderlineStyle、AnnotationTypes、AnnotationObjects、 StyleName、 StyleId、 Link、 IsActive、 SelectionActiveEnd、 CaretPosition、 CaretBidiMode、 LineSpacing、 BeforeParagraphSpacing、 AfterParagraphSpacing、 SayAsInterpretAs AnnotationType 未知、拼写错误、语法错误、注释、公式错误、跟踪更改、页眉、页脚、突出显示、尾注、脚注、插入更改、删除更改、移动更改、格式更改、未同步更改、编辑锁定更改、外部更改、冲突更改、作者、高级证明问题、数据验证错误、循环参考错误、数学 风格 自定义、标题1、标题2、标题3、标题4、标题5、标题6、标题7、标题8、标题9、标题、副标题、正常、强调、引用、项目符号列表、编号列表 地标类型 自定义、窗体、主要、导航、搜索 标题级别 无、1、2、3、4、5、6、7、8、9 改变 总结 元数据 SayAsInterpretAs AsyncContentLoaded状态 开始、进展、完成 AutomationIdentifierType 属性、模式、事件、ControlType、TextAttribute、LandmarkType、批注、更改、样式 ConditionType:IUIAutomation 条件的类型枚举 true、false、property、and、or、not EventArgsType 简单、PropertyChanged、StructureChanged、AsyncContentLoaded、WindowClosed、TextEditTextChanged、更改、通知、ActiveTextPositionChanged、StructuredMarkup AutomationElement模式 无,完整 CoalesceEventsOptions 已禁用、已启用 ConnectionRecoveryBehaviorOptions 已禁用、已启用 PropertyConditionFlags None、IgnoreCase、MatchSubstring ActiveEnd:包含 SelectionActiveEnd 文本属性的可能值,该属性指示插入符号相对于表示当前选定文本的文本范围的位置。 无、开始、结束 AnimationStyle:包含 AnimationStyle 文本属性的值。 无、LasVegasLights、BlinkingBackground、SparkleText、MarchingBlackAnts、MarchingRedAnts、微光、其他:-1 BulletStyle:包含 BulletStyle 文本属性的值。 无、HollowRoundBullet、FilledRoundBullet、HollowSquareBullet、FilledSquareBullet、DashBullet、其他:-1 CapStyle:包含指定 CapStyle 文本属性值的值。 无、小写、全写、全写、小写、单写、标题、其他:-1 CaretBidiMode:包含 CaretBidiMode 文本属性的可能值,该属性指示插入符号是位于从左到右排列还是从右到左排列的文本中。 LTR、RTL CaretPosition:包含 CaretPosition 文本属性的可能值,该属性指示插入符号相对于文本范围中文本行的位置。 未知、EndOfLine、BeginningOfLine DockPosition:包含指定由 Dock 控件模式表示的停靠窗口位置的值。 上、左、下、右、填充、无 ExpandCollapseState:包含指定可以展开和折叠的 UI 元素的状态的值。 折叠、扩展、部分扩展、叶节点 FillType:包含 FillType 属性的值。 无, 颜色, 渐变, 图片, 模式 FlowDirection:包含 values 表示 TextFlowDirections 文本属性。 默认、RightToLeft、BottomToTop、垂直 LiveSetting:包含 LiveSetting 属性的可能值。此属性由属于实时区域的提供程序元素实现。 关闭,礼貌,自信 导航方向:包含用于指定 Microsoft UI 自动化树中的导航方向的值。 Parent、NextSibling、PreviousSibling、FirstChild、LastChild NotificationKind:定义指示通知事件类型的值,以及向侦听器提供有关事件处理的提示。 ItemAdded、ItemRemoved、ActionCompleted、ActionAborted、其他 NotificationProcessing:定义指示应如何处理通知的值。 ImportantAll、ImportantMostRecent、All、MostRecent、CurrentThenMostRecent OrientationType:包含指定控件方向的值。 无、水平、垂直 OutlineStyles:包含 OutlineStyle 文本属性的值。 无, 轮廓, 阴影, 雕刻, 浮雕 提供程序选项 ClientSideProvider、ServerSideProvider、NonClientAreaProvider、OverrideProvider、ProviderOwnsSetFocus、UseComThreading、RefuseNonClientSupport、HasNativeIAccessible、UseClientCoordinates RowOrColumnMajor:包含指定表中的数据是主要按行还是按列读取的值。 RowMajor、ColumnMajor、不确定 SayAsInterpretAs:定义指示文本转语音引擎应如何解释特定数据的值。 无、拼写、红衣主教、序数、数字、日期、时间、电话、货币、净、网址、地址、名称、媒体、Date_MonthDayYear、Date_DayMonthYear、Date_YearMonthDay、Date_YearMonth、Date_MonthYear、Date_DayMonth、Date_MonthDay、Date_Year、Time_HoursMinutesSeconds12、Time_HoursMinutes12、Time_HoursMinutesSeconds24、Time_HoursMinutes24 ScrollAmount:包含指定滚动方向和距离的值。 LargeDecrement、SmallDecrement、NoAmount、LargeIncrement、SmallIncrement StructureChangeType:包含指定 Microsoft UI 自动化树结构中的更改类型的值。 ChildAdded、ChildRemoved、ChildrenInvalidated、ChildrenBulkAdded、ChildrenBulkRemoved、ChildrenReordered SupportedTextSelection:包含指定支持的文本选择属性的值。 无、单个、多个 SynchronizedInputType:包含指定同步输入类型的值。 KeyUp、KeyDown、LeftMouseUp、LeftMouseDown、RightMouseUp、RightMouseDown TextDecorationLineStyle:包含指定 OverlineStyle、StrikethroughStyle 和 UnderlineStyle 文本属性的值。 无、单、仅字、双、点、破折号、破折号、破折号点、破折号点、波浪形、厚单、双波浪形、厚波浪形、长破折号、厚破折号、厚破折号、厚破折号点、厚破折号点、厚点、厚长破折号、其他:-1 TextEditChangeType:描述在引发或处理文本编辑事件时控件执行的文本编辑更改。 无、自动更正、合成、合成定稿、自动完成 TextPatternRangeEndpoint:包含指定文本范围的终结点的值。 开始、结束 TextUnit:包含指定用于导航的文本单位的值。 字符、格式、单词、行、段落、页面、文档 ToggleState:包含指定实现 Toggle 控件模式的 Microsoft UI 自动化元素的切换状态的值。 关、开、不确定 ZoomUnit:包含 IUIAutomationTransformPattern2::ZoomByUnit 方法的可能值,该方法可缩放指定单元的控件的视区。 NoAmount、LargeDecrement、SmallDecrement、LargeIncrement、SmallIncrement WindowVisualState:包含指定窗口的可视状态的值。 正常、最大化、最小化 WindowInteractionState:包含指定窗口当前状态的值,以便进行用户交互。 运行、 关闭、 ReadyForUserInteraction、 BlockedByModalWindow、 NotResponding
元素访问方法
GetRootElement
GetRootElement(cacheRequest:=0)
检索表示桌面的 UI 自动化元素。(可选)包含缓存请求(请参阅本 Wiki 中的缓存部分)
ElementFromHandle
ElementFromHandle(hwnd:="", cacheRequest:=0, activateChromiumAccessibility:=500)
检索指定窗口的 UI 自动化元素。此外,activateChromiumAccessibility 标志会自动设置为 500,这意味着 Chromium 窗口辅助功能将通过发送WM_GETOBJECT消息自动激活,并且最多等待 500 毫秒,直到激活辅助功能。每个窗口仅执行一次此操作,进一步的调用将不会发送激活信号。
元素从铬
ElementFromChromium(winTitle:="", activateChromiumAccessibility:=500, cacheRequest:=0)
从 Chromium 应用(基于 Web 浏览器的应用程序,如 Skype、Discord 等)中检索 Chromium 元素。activateChromiumAccessibility 的工作方式与 ElementFromHandle 中的工作方式相同。
元素从点
ElementFromPoint(x?, y?, cacheRequest:=0, activateChromiumAccessibility:=500)
检索桌面上指定点处的 UI 自动化元素,该元素不一定是该点下最深的元素。此外,activateChromiumAccessibility 标志可以设置为 0 以不激活基于 Chromium 的应用中的辅助功能,否则为 Chromium 激活的超时期限。如果为 activateChromiumAccessibility 提供了 VarRef,则它将设置为 Chromium 元素。
GetFocusedElement
GetFocusedElement(cacheRequest:=0)
检索具有输入焦点的 UI 自动化元素。
ElementFromIAccessible
UIA.ElementFromIAccessible(IAcc, childId:=0)
从 MSAA/Acc 对象(UIA 的前身)获取元素。这仅适用于窗口本机实现 IAccessible 的 Acc 对象,其中不包括大多数 Win32 窗口(如记事本、Windows 资源管理器等)。不鼓励使用此方法,因为 UIA 通常具有更可靠的方法来获取可用的元素。
有关这些内容的更完整描述,请参阅本 Wiki 的 UIA 树部分。
Condition 方法
创建树行者
CreateTreeWalker(condition)
检索可用于遍历 Microsoft UI 自动化树的 TreeWalker 对象。
创建条件
CreateCondition(conditionObject)
从对象创建新的属性条件:
单个属性条件由一个对象组成,其中键是属性名称,value 是属性值:=> 创建一个条件,其中 Name 属性必须与“Test”完全匹配{Name:"Test"}
{} 中的所有内容都是“and”条件 => Name 必须与 “Something” 匹配,并且 ControlType 必须为 Button{Type:"Button", Name:"Something"}
[] 中的所有内容都是“或”条件 名称必须与“测试”匹配,或者名称必须与“某物”匹配[{Name:"Test"}, {Name:"Something"}]
对象键“not”创建 not 条件
matchmode 键(缩写形式:mm)可以是 UIA 之一。MatchMode 值(StartsWith 和 RegEx 除外)并定义 MatchMode 子字符串(值为 2)= 可以包含字符串中的任何位置;精确(值 3)= 完全匹配
casesense 键(缩写形式:cs)定义区分大小写(默认值:区分大小写/True):True=区分大小写;False = 不区分大小写
创建条件
CreateCondition(property, value, flags?)
根据属性名称和值创建新的属性条件。建议改用 CreateCondition(conditionObject)。
创建AndCondition
CreateAndCondition(c1,c2)
将两个条件与“and”组合在一起。建议改用 CreateCondition(conditionObject)。
CreateOrCondition
CreateOrCondition(c1,c2)
将两个条件与“or”组合在一起。建议改用 CreateCondition(conditionObject)。
CreateNotCondition
CreateNotCondition(c)
创建新的“非”条件。建议改用 CreateCondition(conditionObject)。
有关这些内容的更完整描述,请参阅本 Wiki 中的 TreeWalker 和 Conditions 部分。
事件方法
AddAutomationEventHandler
AddAutomationEventHandler(handler, element, eventId, scope:=0x4, cacheRequest:=0)
注册处理 Microsoft UI 自动化事件的方法。eventId 必须是 UIA。事件值。scope 必须是 TreeScope 枚举。cacheRequest 可以指定是否使用缓存。handler 是一个事件处理程序对象,可以使用 UIA 创建。CreateEventHandler 函数。
删除AutomationEventHandler
RemoveAutomationEventHandler(handler, element, eventId)
AddPropertyChangedEventHandler
AddPropertyChangedEventHandler(handler, element, propertyArray, scope:=0x4, cacheRequest:=0)
注册一个方法,该方法处理属性更改事件的数组
RemovePropertyChangedEventHandler
RemovePropertyChangedEventHandler(handler, element)
AddStructureChangedEventHandler
AddStructureChangedEventHandler(handler, element, scope:=0x4, cacheRequest:=0)
RemoveStructureChangedEventHandler
RemoveStructureChangedEventHandler(handler, element)
AddFocusChangedEventHandler
AddFocusChangedEventHandler(handler, cacheRequest:=0)
删除焦点更改事件处理程序
RemoveFocusChangedEventHandler(handler)
RemoveAllEventHandlers
RemoveAllEventHandlers()
一次删除所有已注册的事件处理程序。
IUIAutomation3 事件方法
AddTextEditTextChangedEventHandler
AddTextEditTextChangedEventHandler(handler, element, textEditChangeType, scope:=0x4, cacheRequest:=0)
删除文本编辑文本更改事件处理程序
RemoveTextEditTextChangedEventHandler(handler, element)
IUIAutomation4 事件方法
AddChangesEventHandler
AddChangesEventHandler(handler, element, scope, changeTypes, changesCount, cacheRequest:=0)
RemoveChangesEventHandler
RemoveChangesEventHandler(handler, element)
IUIAutomation5 事件方法:
AddNotificationEventHandler
AddNotificationEventHandler(handler, element, scope:=0x4, cacheRequest:=0)
删除通知事件处理程序
RemoveNotificationEventHandler(handler, element)
IUIAutomation6 事件方法:
CreateEventHandlerGroup(创建事件处理程序组)
CreateEventHandlerGroup()
AddEventHandlerGroup
AddEventHandlerGroup(handlerGroup, element)
RemoveEventHandlerGroup(handlerGroup, 元素)
AddActiveTextPositionChangedEventHandler
AddActiveTextPositionChangedEventHandler(handler, element, scope=0x4, cacheRequest:=0)
RemoveActiveTextPositionChangedEventHandler(handler, 元素)
杂项方法
RuntimeIdToString
RuntimeIdToString(runtimeId)
将 RuntimeId(整数数组)转换为字符串。
RuntimeIdFromString
RuntimeIdFromString(str)
将字符串形式的 RuntimeId 转换回 RuntimeId 数组
滤波器
Filter(elementArray, function)
如果 “function” 的计算结果为 True,则从元素数组中筛选元素
CreateCache请求
CreateCacheRequest(properties?, patterns?, scope?, mode?, filter?)
创建新的缓存请求对象(请参阅 Wiki 中的缓存部分) (可选)还可以启动属性(属性名称或 ID 的数组)、模式(模式名称或 ID 的数组)、TreeScope、AutomationElementMode 和 TreeFilter(仅缓存与条件匹配的元素的条件)。
比较元素
CompareElements(e1,e2)
检查两个元素是否相等。以正常方式执行此操作是行不通的e1 == e2
比较运行时 ID
CompareRuntimeIds(r1,r2)
GetPropertyProgrammaticName
GetPropertyProgrammaticName(Id)
GetPatternProgrammaticName
GetPatternProgrammaticName(Id)
PollForPotentialSupportedPatterns
PollForPotentialSupportedPatterns(pElement, &patternIds, &patternNames)
返回一个对象,其中键是名称,值是 ID
PollForPotentialSupportedProperties
PollForPotentialSupportedProperties(pElement, &propertyIds, &propertyNames)
04. 元素
元素是整个 UIA 树中的节点,它本身可能具有子节点。元素可以是控件,如 Button、Edit、CheckBox,它也可以具有子元素:例如,Button 元素可能具有按钮内图像或文本的子元素。元素也可以只是其他元素(如窗格或表)的容器。
有了元素,我们主要可以做三件事:
- 使用属性获取有关元素的信息:名称、位置、类型等。
- 执行简单的交互,例如聚焦元素或单击它(更复杂的交互使用模式完成)
- 查找新元素:使用 FindElement 方法,我们可以从起点找到感兴趣的元素(例如从根元素获取所有 Window 元素(=打开的窗口),使用 WaitElement 方法可以等待元素出现(或消失)。
性能
可以通过属性访问有关元素的信息。有两种类型的属性:元素属性和控件模式属性。
元素属性
自动化元素属性由一组通用属性(如 Name、AcceleratorKey 和 ClassName)组成,这些属性由所有 UIAutomation 元素公开,而不考虑控件类型。通常元素属性不会改变(例如名称保持不变)。
元素属性列表
位置*、长度*、父级*、子级*、存在*、值**、ProcessId、类型(ControlType 的缩写)、LocalizedControlType、名称、AcceleratorKey、AccessKey、HasKeyboardFocus、IsKeyboardFocusable、IsEnabled、AutomationId、ClassName、HelpText、Culture、IsControlElement、IsContentElement、IsPassword、NativeWindowHandle、ItemType、Orientation、FrameworkId、IsRequiredForForm、ItemStatus、BoundingRectangle、LabeledBy、AriaRole、AriaProperties、IsDataValidForForm、ControllerFor、DescribedBy、FlowsTo、ProviderDescription、OptimizeForVisualContent、LiveSetting、FlowsFrom、IsPeripheral、PositionInSet、SizeOfSet、Level、AnnotationTypes、AnnotationObjects、LandmarkType、LocalizedLandmarkType
* 这些是原始 UIAutomation 实现中没有的自定义属性。Location 返回一个对象,其元素的位置为:{x, y, w, h}。 Length 返回元素具有的子元素数。Children 返回所有直接子元素的数组。Parent 返回父元素。Exists 检查元素是否仍可访问。
** 大多数属性不能使用修饰符,但 Value 支持设置属性:Element.Value 返回当前值,Element.Value := “new value” 设置值。
大多数属性是单词或数字,但有些属性返回对象:
- Location 返回一个对象,其中包含元素的 x 和 y 屏幕坐标、宽度和高度,以及元素的左、上、右和下边界(与 BoundingRectangle 相同):{x, y, w, h} 可以作为 .若要获取相对坐标,请改用 GetPos 方法。
Element.Location.x - BoundingRectangle 返回一个对象,该对象包含屏幕坐标中元素的左、上、右和下边界。可以使用 访问它们。
BoundingRectangle .l, BoundingRectangle.t, BoundingRectangle.r, BoundingRectangle.b - LabeledBy 返回一个元素
- ControllerFor、DescribedBy、FlowsTo 返回元素数组
可以使用以下属性访问:Element.PropertyElement.CurrentProperty
对于缓存的属性,属性名称前面需要加上“Cached”:Element.CachedName
控件模式属性
具有特定控件模式的元素支持控件模式属性。每个控件模式都有一组相应的控件模式属性,控件必须公开这些属性。例如,支持 GridPattern 的控件应具有 ColumnCount 和 RowCount 属性,或者 ValuePattern 具有 Value 属性。大多数控件模式属性都是动态值(它们可能会随着用户交互而更改)。
控件模式属性的访问方式与普通属性相同:将返回 ToggleState 属性值。或者,可以将 GetPropertyValue 方法与相应的属性枚举一起使用:Element.ToggleStateElement.GetPropertyValue(UIA.Property.Name)
控件模式属性列在本 Wiki 的“模式”部分下,因为它们取决于可用的模式。
方法
每个元素都有可用于与元素交互的方法(以有限的方式,大多数交互都是通过模式完成的)、获取属性以及查找下一个感兴趣的元素。
交互方式
以下是每个元素可用的交互方法。更具体的交互方式(例如设置值、切换等)是通过模式完成的。
SetFocus
SetFocus()将焦点设置为元素。这通常也会激活窗口
点击
Click(WhichButton:="", ClickCount:=1, DownOrUp:="", Relative:="", NoActivate:=False)
尝试单击该元素。该方法依赖于 WhichButton 变量:默认情况下,它会尝试使用任何类似“点击”的方法,例如 InvokePattern Invoke()、TogglePattern Toggle()、SelectionItemPattern Select()。
- WhichButton :如果 WhichButton 留空(默认),则将使用任何类似“点击”的模式方法(Invoke()、Toggle()、Select() 等)。 如果 WhichButton 是一个数字,则之后将以该毫秒数调用 Sleep。例如。Element.Click(200) 将在“点击”后休眠 200 毫秒。 如果 WhichButton 为“left”或“right”,则本机 Click() 将用于将光标移动到元素的中心并执行单击。
- ClickCount :如果 WhichButton 不是数字或留空,则使用,即将使用 AHK Click()。在这种情况下,如果 ClickCount 是数字 <10,则将执行该点击次数。 如果 ClickCount 为 >=10,则将以该毫秒数调用 Sleep。ClickCount 和睡眠时间都可以通过用空格分隔来组合。 例如。Element.Click(“left”, 1000) 将在点击后 1000 毫秒休眠。 Element.Click(“left”, 2) 将双击该元素 Element.Click(“left”, “2 1000”) 将双击该元素,然后休眠 1000 毫秒
- DownOrUp :如果使用 AHK Click,则将按下鼠标或松开鼠标。
- 相对 :如果“相对”为“Rel”或“Relative”,则 X 和 Y 坐标被视为与当前鼠标位置的偏移量。 否则,它需要 X 和 Y 的偏移值(例如,“-5 10”会从元素中心偏移 X 偏移 -5,将 Y 偏移 +10)。
- NoActivate :如果使用 AHK Click,则如果可单击点在屏幕上不可见,这将确定在单击之前是否激活窗口。默认值为不激活。
ControlClick(控制点击)
ControlClick(WhichButton:="left", ClickCount:=1, Options:="")
使用 ControlClick 单击元素。
- WhichButton :确定用于单击的按钮(左、右、中)。如果 WhichButton 是一个数字,则之后将调用 Sleep。 例如。ControlClick(200) 将在单击后休眠 200 毫秒。
- ClickCount :点击多少次。默认值为 1。
- 选项 :其他 ControlClick 选项(请参阅 AHK 文档)。
ShowContextMenu()
Find/Wait 方法
这些元素可用于从起始点元素获取下一个元素(请参阅本 Wiki 的“UIA 树”部分)。
- 若要查找一个元素,请使用具有适当条件的 FindElement 方法(请参阅本 Wiki 中的“条件”)。例如,要从根元素中找到名称为“Skype”的第一个元素,我们可以简单地执行 .
UIA.GetRootElement().FindElement({Name:"Skype"}) - 若要查找与条件匹配的所有元素,请使用 FindElements 方法。
- 若要等待元素存在,请使用 WaitElement 方法。如果找到元素,则该方法也会返回该元素,因此可以执行 。
if (foundElement := element.WaitElement({Name:"Skype"})) { ... - 若要等待当前元素不存在,请使用 WaitNotExist。
- 要获取相对于 UIA 树中位置的元素,请使用 ElementFromPath、WalkTree 或 TreeWalkers(请参阅本 Wiki 的“TreeWalkers”部分)。 返回下一个同级元素,即上一个同级的上一个同级,第二个子元素,父级的父级。
element.WalkTree("+1")element.WalkTree("-2")element.WalkTree("2")element.WalkTree("P2")
查找元素
FindElement(condition, scope:=4, index:=1, order:=0, startingElement:=0, cacheRequest:=0)
检索与指定条件匹配的第一个子元素或后代元素。如果未找到任何元素,则引发 TargetError。
- condition :用于筛选的条件或回调函数。condition 对象还支持命名参数(例如 .如果提供了回调函数,则使用 TreeWalker 遍历树,这将非常慢:通常最好将回调与 FindCachedElement 一起使用。
{Type:"Button", scope:"Children"} - scope:可选的 TreeScope 值:Element、Children、Family (Element+Children)、Descendants、Subtree (=Element+Descendants)。默认值为 Descendants。
- index :查找与条件匹配的第 n 个元素
- order:可选。自定义树导航顺序,UIA 之一。TreeTraversalOptions 值 [需要 Windows 10 版本 1703+]
- startingElement :可选。用于开始搜索的元素 [需要 Windows 10 版本 1703+]
- cacheRequest :可选。缓存请求对象
FindElements(condition, scope := 4, order:=0, startingElement:=0, cacheRequest:=0)
返回满足指定条件的所有 UI 自动化元素。如果未找到任何元素,则返回一个空数组。
元素存在
ElementExist(condition, scope:=4, index:=1, order:=0, startingElement:=0, cacheRequest:=0)
这与 FindElement 相同,但如果未找到元素,则返回 0 而不是引发错误。
WaitElement
WaitElement(condition, timeout := -1, scope := 4, index := 1, order := 0, startingElement := 0, cacheRequest := 0)
调用 FindElement,直到找到该元素,并具有可选的超时值(以毫秒为单位)。默认值为无限期等待。
WaitElementNotExist
WaitElementNotExist(condition, timeout := -1, scope := 4, index := 1, startingElement := 0, order := 0, cacheRequest := 0)
等待元素消失:startingElement.WaitElementNotExist({Name:"TargetElement"})
ElementFromPath
ElementFromPath(路径1[, 路径2, …])
尝试从路径中获取元素。如果未找到任何元素,则会引发错误。
路径可以是:
- 逗号分隔的数字路径,用于定义在树中向下移动的路径。除了整数值之外,或者 TypeN,它选择 Type 的第 n 次出现。 例如。Element.ElementFromPath(“3,2”) => 选择元素 第三个子 第二个孩子 Element.ElementFromPath(“Button3,2”) => 选择 Button 类型的第三个子元素,然后选择其第二个子元素
- 从 UIAViewer 复制的 UIA 路径。 例如。Element.ElementFromPath(“bAx3”)
- 一个或多个条件。在这种情况下,提供的条件定义树遍历的路由,默认情况下使用范围子项。 例如。Element.ElementFromPath({Type:“Button”}, {Type:“List”}) => 查找 Element 的第一个 Button 类型子元素,然后查找该元素的第一个 List 类型子元素
元素FromPathExist
与 ElementFromPath 相同,但如果未找到任何元素,则返回 0。
WaitElementFromPath
WaitElementFromPath(path1[, path2, …, 超时])
等待元素出现在路径上。最后一个参数可以选择是以毫秒为单位的超时(默认值为无限期等待)。
路径可以是:
- 逗号分隔的数字路径,用于定义在树中向下移动的路径。除了整数值之外,或者 TypeN,它选择 Type 的第 n 次出现。 例如。Element.WaitElementFromPath(“3,2”, 2000) => 等待 Elements 第三个孩子第二个孩子,超时 2 秒 Element.WaitElementFromPath(“Button3,2”) => 等待 Button 类型的第三个子元素,然后是第二个子元素
- 从 UIAViewer 复制的 UIA 路径。 例如。Element.WaitElementFromPath(“bAx3”)
- 一个或多个条件。在这种情况下,提供的条件定义树遍历的路由,默认情况下使用范围子项。 例如。Element.WaitElementFromPath({Type:“Button”}, {Type:“List”}) => 等待 Element 的第一个 Button 类型子元素,然后是该元素的第一个 List 类型子元素
WalkTree(沃克树酒店)
WalkTree(searchPath, filterCondition?)
纯粹使用使用可选筛选条件(默认为 TrueCondition)创建的 TreeWalker 遍历树
searchPath 是一个逗号分隔的路径,用于定义树遍历的路由:
可以选择提供 filterCondition:树遍历的条件,仅选择与条件匹配的元素。
示例:Element.ElementFromPath(“p,+2,1”) =>获取 Element 的父级,然后是父级的第二个同级,然后是该同级的第一个子级。
WaitNotExist(等待不存在)
WaitNotExist(timeOut:=-1)
等待此元素不存在。
FindCachedElement
FindCachedElement(condition, scope:=4, index:=1, order:=0, startingElement:=0)
FindCachedElement 可用于在缓存树中查找元素,仅使用缓存属性。Condition 也可以是回调函数。如果未找到匹配的元素,则会引发错误。
CachedElementExist
CachedElementElement(condition, scope:=4, index:=1, order:=0, startingElement:=0)
这与 FindCachedElement 相同,但如果未找到任何元素,则返回 0。
FindCachedElements
FindCachedElements(condition, scope:=4, order:=0, startingElement:=0)
返回缓存树中满足指定条件的所有 UI 自动化元素,仅检查缓存的属性。 这不是 UIA 本机方法:确保缓存的树相当小,否则性能会受到影响。
属性方法
GetClickablePoint
GetClickablePoint()检索元素上可单击的点的物理屏幕坐标。并非每个元素都是可点击的,某些元素可能具有模仿“可点击”的机制(例如,在网页中,Javascript 可用于使文本可点击),但没有可用的可点击点。
GetWinId
GetWinId()从元素获取父窗口句柄。
GetPos的
GetPos(relativeTo="")返回一个对象,其中包含元素的 x、y 坐标以及宽度和高度:{x:x coordinate, y:y coordinate, w:width, h:height}。relativeTo 可以是 client、window 或 screen,默认值为 A_CoordModeMouse。
GetPropertyValue
GetPropertyValue(propertyId)检索此元素的属性的当前值。这很少使用,因为也是如此。Element.Property
GetPattern
GetPattern(pattern)检索此元素上指定控件模式的 Pattern 对象。这很少使用,因为这样做也是如此(需要以“模式”一词结尾,例如 )。Element.SomePatternElement.ValuePattern
其他方法
高亮
Highlight(showTime:=unset, color:="Red", d:=2)在元素边框周围绘制一个矩形,该矩形可用于调试目的。 showTime 可以是以下值之一: 未设置 – 如果存在突出显示,则删除突出显示,否则突出显示 2 秒钟。这是默认值。 0 – 无限高亮显示 正整数(例如 2000) – 将突出显示并暂停指定的时间(以毫秒为单位) 负整数 – 将在指定的时间(以毫秒为单位)内突出显示,但脚本将继续执行 “clear” – 无条件删除突出显示
转 储
Dump(scope:=1, delimiter:=" ", maxDepth:=-1)
返回有关元素的信息:ControlType、Name、Value、LocalizedControlType、AutomationId、AcceleratorKey。
- scope :可选 UIA。TreeScope 值:Element、Children、Family、Descendants、Subtree (=Element+Descendants)。默认值为 Element。
- delimiter :可选分隔符,用于分隔返回的属性。默认值为空格。
- maxDepth :可选的树级别遍历的最大深度。默认值为无限制。
转储全部
DumpAll(delimiter:=" ", maxDepth:=-1)
从此元素开始对整个子树调用 Dump。
05. 条件
在上一节中,我们列出了一些从 UIA 树中访问元素的方法。要使用这些方法中的任何一个(如 FindElement、WaitElement),我们还需要提供用于在树中搜索元素时进行过滤的条件。这是有条件的。
FindElement (s) 和 WaitElement 条件
条件对象必须是 Object 或 Array。
- 单个属性条件由一个对象组成,其中键是属性名称,value 是属性值:=> 创建一个条件,其中 Name 属性必须与“Test”完全匹配
{Name:"Test"} - {} 中的所有内容都是“and”条件 => Name 必须与 “Something” 匹配,并且 ControlType 必须为 Button
{Type:"Button", Name:"Something"} - [] 中的所有内容都是“或”条件 名称必须与“测试”匹配,或者名称必须与“某物”匹配
[{Name:"Test"}, {Name:"Something"}] - 对象键“not”创建 not 条件
- matchmode 键(缩写形式:mm)可以是 UIA 之一。MatchMode 值并定义 MatchMode StartsWith=1,子字符串=2,Ex = 3
- casesense 键(缩写形式:cs)定义区分大小写(默认值:区分大小写/True):True=区分大小写;False = 不区分大小写
例子:
{Name:"Test"}=> 名称必须与“Test”完全匹配,区分大小写{Type:"Button", or:[{Name:"Something"}, {Name:"Else"}]}=> 名称必须与“Something”或“Else”匹配,并且 ControlType 必须为 Button。替代方案是{Type:"Button", Name:["Something", "Else"]}{Name:"Test", cs:0, mm:2}=> 名称必须包含“Test”,并且不区分大小写。长格式将是{Name:"Test", casesense:0, matchmode:"Substring"}
UIAViewer 为对象条件创建速记符号,以使 UIA 路径更加紧凑。在表示法中,T 代表 Type,A 是 AutomationId,N 是 Name,CN 是 ClassName。Type value 是枚举值减去 50000(因为所有 Type 枚举都在 50000 中)。 相当于 等于 。{T:0}{Type:50000}{Type:"Button"}
TreeWalker 条件
由于 UIAutomation 框架不支持匹配模式 StartsWith 和 RegEx,因此这两者不可用。除此之外,对象的语法是相同的。
内置条件
一些条件已经作为UIA类属性提供给我们。
TrueCondition (真条件)
国际律师协会。TrueCondition 始终为 true,并且与每个元素匹配。这与提供空对象作为条件相同。
RawViewCondition
国际律师协会。RawViewCondition 包括所有 UIAutomation 元素。单独使用时,此条件在功能上与 TrueCondition 相同。
ControlViewCondition
国际律师协会。ControlViewCondition 仅包含作为控件的元素。
ContentViewCondition
国际律师协会。ContentViewCondition 仅包含包含内容的元素。
高级部分
这里解释了用于从上述对象创建条件的所有基础方法。您很可能可以跳过阅读本节。
创造条件
可以使用 CreateTrueCondition、CreateFalseCondition、CreatePropertyCondition、CreatePropertyConditionEx 和 CreateCondition 从 UIA 类创建条件。
CreateTrueCondition
创建新的 TrueCondition。UIA.ahk 库不需要这样做,因为 UIA.TrueCondition 使用它并存储该值。
CreateFalseCondition
创建一个始终为 false 的条件。此方法是无用的,它仅用于与 CreateTrueCondition 的对称性。它不能与任何其他条件有效结合。
创建条件
这是创建 UIA 条件的最灵活方法。
CreateCondition(conditionObject)从 Condition 对象创建条件。
CreateCondition(property, value, flags?)从属性和属性值对创建条件。如果仅提供属性和值,则调用 CreatePropertyCondition。如果还提供了标志,则调用 CreatePropertyConditionEx。
例子:
CreateCondition({Name:"SomeName"}) == CreatePropertyCondition(UIA.Property.Name, "SomeName") == CreatePropertyCondition(30005, "SomeName")
CreateCondition("Name", "SomeName", "CaseSensitive") == CreatePropertyConditionEx(30005, "SomeName", 1)
CreatePropertyCondition
CreatePropertyCondition(propertyId, value)创建一个条件,用于筛选具有特定值的属性。 propertyId 必须是 UIA 中的数字。属性枚举。例如,要创建一个条件以仅筛选名称为“test”的元素,请使用 .UIA.Property.Name 可以替换值 30005。UIA.CreatePropertyCondition(UIA.Property.Name, "test")
CreatePropertyConditionEx
CreatePropertyConditionEx(propertyId, value, flags=0)工作方式与 CreatePropertyCondition 相同,但还可以添加一些标志。 flags 可以是 UIA 之一。PropertyConditionFlags: 国际律师协会。PropertyConditionFlags.None := 0x0 国际律师协会。PropertyConditionFlags.IgnoreCase := 0x1 国际律师协会。PropertyConditionFlags.MatchSubstring = 0x2 默认标志为 None。
CreateNotCondition
CreateNotCondition(c)返回所提供条件的负数(条件不得匹配)。
组合条件
条件还可以与 CreateAndCondition 和 CreateOrCondition 结合使用。
创建AndCondition
CreateAndCondition(c1,c2)采用两个条件并返回一个新条件,其中 C1 和 C2 都需要匹配。
CreateOrCondition
CreateOrCondition(c1,c2)采用两个条件并返回一个新条件,其中 C1 或 C2 需要匹配。
条件的属性
IUIAutomationBool条件
BooleanValue
IUIAutomationPropertyCondition
IUIAutomationAndCondition
ChildCount
IUIAutomationOrCondition
ChildCount
条件的方法
IUIAutomationAndCondition
GetChildren()返回 AndCondition 包含的条件数组。条件的类型可以通过 Type(condition) 来确定
IUIAutomationOrCondition
GetChildren()返回 OrCondition 所包含的条件数组。条件的类型可以通过 Type(condition) 来确定
IUIAutomationNotCondition
GetChild()返回从中创建 NotCondition 的条件。条件的类型可以通过 Type(condition) 来确定
06. 树行者
介绍
到目前为止,我们已经研究了 FindElement(s) 方法,它可以从起始元素的“下面”返回元素,这意味着它可以搜索其子元素和后代元素。但是 FindElement 不能在树中“横向”移动,也不能“向上”移动,这意味着它不能返回任何同级元素或父元素。 要访问这些其他元素,我们需要使用 WalkTree 方法或 TreeWalkers。
ElementFromPath
ElementFromPath(path1[, path2, ...])
ElementFromPath 通过起始元素的相对“路径”获取元素。这条路只能“向下”。 如果在路径中找不到任何元素,则会引发 IndexError。
路径可以是:
- 逗号分隔的数字路径,用于定义在树中向下移动的路径。除了整数值之外,或者 TypeN,它选择 Type 的第 n 次出现。 例如。Element.ElementFromPath(“3,2”) => 选择元素 第三个子 第二个孩子 Element.ElementFromPath(“Button3,2”) => 选择 Button 类型的第三个子元素,然后选择其第二个子元素
- 从 UIAViewer 复制的 UIA 路径。 例如。Element.ElementFromPath(“bAx3”)
- 一个或多个条件。在这种情况下,提供的条件定义树遍历的路由,默认情况下使用范围子项。 例如。Element.ElementFromPath({Type:“Button”}, {Type:“List”}) => 查找 Element 的第一个 Button 类型子元素,然后查找该元素的第一个 List 类型子元素
元素FromPathExist
ElementFromPathExist(path1[, path2, ...])
这与 ElementFromPath 相同,但如果在路径中找不到任何元素,则返回 0 而不是引发 IndexError。
WalkTree(沃克树酒店)
WalkTree(searchPath, filterCondition?)
纯粹使用使用可选筛选条件(默认为 TrueCondition)创建的 TreeWalker 遍历树
searchPath 是一个逗号分隔的路径,用于定义树遍历的路由:
可以选择提供 filterCondition:树遍历的条件,仅选择与条件匹配的元素。
示例:Element.ElementFromPath(“p,+2,1”) =>获取 Element 的父级,然后是父级的第二个同级,然后是该同级的第一个子级。
树行者
TreeWalker 用于通过为它提供起点元素和选择元素的条件,逐步向任何方向“遍历”UIA 树。WalkTree 只是使用 TreeWalkers 的一种简单方法,它在后端使用它们。
获取 TreeWalkers
内置 TreeWalkers
树行者真
UIA.TreeWalkerTrue匹配每个元素。
RawViewWalker(原始视图步行者)
UIA.RawViewWalker匹配所有 UIAutomation 元素,并且在功能上等效于 TreeWalkerTrue。
ControlViewWalker
UIA.ControlViewWalker仅匹配作为控件的元素。
内容视图沃克
UIA.ControlViewWalker仅匹配包含内容的元素。
创建新的 TreeWalker
UIA.CreateTreeWalker(condition)接受一个条件并返回一个新的 IUIAutomationTreeWalker 对象。
TreeWalker 属性
TreeWalker.Condition返回创建 TreeWalker 时使用的条件。
TreeWalker 方法
GetParentElement
TreeWalker.GetParentElement(e)获取元素 e 并返回父元素(使用创建 TreeWalker 时使用的条件)。
GetFirstChildElement
TreeWalker.GetFirstChildElement(e)获取元素 e 并返回第一个子元素(使用创建 TreeWalker 时使用的条件)。
GetLastChildElement
TreeWalker.GetLastChildElement(e)获取元素 e 并返回最后一个子元素(使用创建 TreeWalker 时使用的条件)。
GetNextSiblingElement
TreeWalker.GetNextSiblingElement(e)接受一个元素 e 并返回下一个同级元素(使用创建 TreeWalker 时使用的条件)。
GetPreviousSiblingElement
TreeWalker.GetPreviousSiblingElement(e)获取一个元素 e 并返回上一个同级元素(使用创建 TreeWalker 时使用的条件)。
NormalizeElement
TreeWalker.NormalizeElement(e)采用元素 e,首先检查 e 是否与条件匹配,否则返回与条件匹配的第一个父元素。this 和 GetParentElement 之间的区别在于 NormalizeElement 也可以返回原始元素。
例
使用 TreeWalkerTrue 获取下一个同级元素。
TreeWalker 也可以连续多次使用。 例如,获取第二个兄弟姐妹:这相当于
07. 模式
介绍
模式提供了一种以特定于模式的方式与元素交互的方法。例如,将 InvokePattern 用于可调用的控件(如按钮),将 ScrollPattern 用于具有滚动条的控件(如列表框、列表视图或组合框)。一个元素可以有多个可用的模式,子元素可能不具有与父元素相同的模式。
在本文中,我们有一个非详尽的可用模式列表。有关更全面的信息,请参阅 Microsoft 文档和 UIAutomationclient 标头。
模式的示例是 Examples 文件夹中的示例 9-16。
模式列表:
InvokePattern、SelectionPattern、ValuePattern、RangeValuePattern、ScrollPattern、ExpandCollapsePattern、GridPattern、GridItemPattern、MultipleViewPattern、WindowPattern、SelectionItemPattern、DockPattern、TablePattern、TableItemPattern、TextPattern、TogglePattern、TransformPattern、ScrollItemPattern、LegacyIAccessiblePattern、ItemContainerPattern、VirtualizedItemPattern、SynchronizedInputPattern、ObjectModelPattern、AnnotationPattern、StylesPattern、SpreadsheetPattern、SpreadsheetItemPattern、TextChildPattern、DragPattern、DropTargetPattern、TextEditPattern、CustomNavigationPattern
访问模式
此 UIA 库尝试自动检测哪些模式可用于该元素,然后尝试自动访问该模式中的属性或方法。这意味着,例如,如果该元素是 CheckBox 类型元素,并且具有可用的 TogglePattern(在 Accessibility Insights 或 UIAViewer 中),则会自动检测到它需要使用 TogglePattern 并从那里调用该方法。Element.Toggle()
在某些情况下,这可能会失败:例如,LegacyIAccessiblePattern 和 SelectionItemPattern 都有可用的 Select() 方法,但如果这两种模式都受支持,则无法知道使用哪一种模式,而是随机选择一种模式。要强制使用特定模式,请使用 获取模式对象,并从那里访问属性/方法方法: 将使用 SelectionItemPattern 来 Select()。Element.SomePatternElement.SelectionItemPattern.Select()
值模式
ValuePattern 提供对控件的访问,该控件包含不跨越范围且可以表示为字符串的值。此字符串可能是可编辑的,也可能是不可编辑的,具体取决于控件及其设置(SetValue 可能不可用)。
性能
- 值:这可用于获取和设置值。
- IsReadOnly
方法
- SetValue(value) :等效于将 value 属性设置为
Element.Value := "test"
调用模式
InvokePattern 允许调用控件(通常为按钮)的操作。通常,如果 Invoke 启动或执行单个明确的操作,并且在激活时不保持状态,则使用 Invoke。
性能
调用模式没有任何属性
方法
- 调用()
切换模式
TogglePattern 可用于循环显示控件的一组状态,这些状态通常是选中或取消选中复选框。
性能
- ToggleState:0 = 未切换/未选中,1 = 已切换。ToggleState 还可用于将切换状态设置为所需的值。
方法
- 切换()
LegacyIAccessible 模式
LegacyIAccessiblePattern 公开 MSAA/Acc(UIA 的前身)的方法和属性。
性能
- 儿童 ID
- 名字
- 价值
- 描述
- 角色
- 州
- 帮助
- 键盘快捷键
- 默认操作
方法
- 选择(flags=3)
flags 需要是 SELFLAG 的组合。默认值为 SELFLAG_TAKESELECTION 和 SELFLAG_TAKEFOCUS。
- DoDefaultAction()
- SetValue(值)
- GetCurrentSelection()
- GetIAccessible()
此方法目前不起作用,但理论上应该返回 Acc 对象。
滚动模式
ScrollPattern 可用于滚动元素。
性能
- HorizontalScrollPercent
- VerticalScrollPercent
- HorizontalViewSize
- VerticalViewSize
- 水平滚动
- 垂直滚动
方法
- 滚动(水平=-1,垂直=-1)
- SetScrollPercent(水平=-1,垂直=-1)
水平和垂直需要是 UIA 之一。ScrollAmount 枚举:
ScrollItem 模式
ScrollItemPattern 可用于将可滚动元素(例如组合框项)的子元素滚动到视图中。
性能
ScrollItem 没有任何属性。
方法
- ScrollIntoView()
网格图案
GridPattern 提供对控件的访问,该控件充当子控件集合的容器,这些子控件以二维逻辑坐标系进行组织,可按行和列遍历。此元素的子元素支持 GridItemPattern 接口。
性能
- 行计数
- 列计数
方法
- GetItem(row,column),其中行和列使用从 0 开始的索引(0 = 第一行/列)
GridItem 模式
GridItemPattern 提供对支持 GridPattern 接口的网格样式容器中的子控件的访问。
性能
- 包含网格
- 排
- 列
- 行跨度
- 列跨度
方法
GridItem 没有任何方法。
表模式
TablePattern 提供对控件的访问,该控件充当子元素集合的容器。此元素的子元素支持 TableItemPattern,并组织在可按行和列遍历的二维逻辑坐标系中。
性能
- RowOrColumnMajor
方法
- GetCurrentRowHeaders() 返回一个元素数组
- GetCurrentColumnHeaders() 返回一个元素数组
TableItem 模式
TableItemPattern 提供对支持 TablePattern 的容器中的子元素的访问。
性能
TableItem 没有任何属性
方法
- GetCurrentRowHeaderItems() 返回一个元素数组
- GetCurrentColumnHeaderItems() 返回一个元素数组
MultipleView 模式
MultipleViewPattern 提供对控件的访问,该控件可以在同一信息或子控件集的多个表示形式之间切换。
性能
- 视图
方法
- GetViewName(视图)
- SetView(视图)
- GetSupportedViews() 返回一个视图数组
视图是特定于控件的,因此请使用 GetSupportedViews() 访问支持的视图,然后使用 GetViewName 获取视图的名称。
选择模式
SelectionPattern 提供对包含可选子项的控件的访问。此元素的子元素支持 SelectionItemPattern。
性能
- CanSelectMultiple(CanSelectMultiple)
- IsSelection必需
SelectionPattern2 属性
- FirstSelectedItem
- 上一个选择项目
- 选定项
- ItemCount
方法
- GetSelection() 返回一个元素数组
SelectionItem 模式
SelectionItemPattern 提供对支持UIA_SelectionPattern的容器控件的可选子项的访问。
性能
- IsSelected(已选)
- SelectionContainer 返回一个元素
方法
- 选择()
- AddToSelection()
- RemoveFromSelection()
窗口图案
WindowPattern 提供对窗口基本功能的访问。
性能
- CanMaximize(最大化)
- Can最小化
- IsModal(伊斯莫代尔酒店)
- IsTopmost
- WindowVisualState :UIA 之一。WindowVisualState 值 (正常 = 0,最大化 = 1,最小化 = 2)
- WindowInteractionState :UIA 之一。WindowInteractionState 值 (Running = 0, Closing = 1, ReadyForUserInteraction = 2, BlockedByModalWindow = 3, NotResponding = 4)
方法
- 关闭()
- WaitForInputIdle(毫秒)
- SetWindowVisualState(state) :状态可以是 UIA 之一。WindowVisualState 枚举(正常 = 0,最大化 = 1,最小化 = 2)
转换模式
TransformPattern 提供对可移动、调整大小或旋转的控件的访问。
性能
- CanMove的
- 可以调整大小
- CanRotate(康旋转)
方法
- 移动(x, y)
- 调整尺寸(宽、高)
- 旋转(度)
TextPattern 和 TextRange
文本模式
TextPattern 提供对包含文本的控件的访问。TextPattern 不能用于更改文本,因此您需要使用 ValuePattern 或 AutoHotkeys Send 函数。
性能
- DocumentRange 返回一个新的 TextRange 对象,该对象包含文档的正文。
- SupportedTextSelection
方法
- RangeFromPoint(x, y) 检索最接近指定屏幕坐标的空 TextRange
- RangeFromChild(child) 检索包含子元素(如图像、超链接、Microsoft Excel 电子表格或其他嵌入对象)的 TextRange。
- GetSelection() 将当前选定的文本作为 TextRanges 数组返回
- GetVisibleRanges() 从基于文本的控件中检索不相交文本范围的数组,其中每个文本范围表示可见文本的连续范围
TextPattern2 方法
- RangeFromAnnotation(annotation) 返回一个 TextRange
- GetCaretRange(ByRef isActive=“”) 检索属于基于文本的控件的插入符号位置处的零长度文本范围。如果包含插入符号的基于文本的控件具有键盘焦点,则 isActive 设置为 True,否则设置为 False。
TextRange
性能
TextRange 没有任何属性
方法
- Clone() 返回 TextRange 的副本(检索与原始UIA_TextRange相同的新并继承原始属性的所有属性)。
- Compare(comparisonTextRange) 比较此 TextRange 是否具有与 comparisonTextRange 相同的终结点
- CompareEndPoints(srcEndPoint, comparisonTextRange, targetEndPoint) 检索一个值,该值指定此文本范围的起始端点或结束端点是否与 comparisonTextRange 的起始端点或结束端点相同。如果调用方的终结点在文本中出现的时间早于目标终结点,则返回负值;如果调用方的终结点与目标终结点位于同一位置,则为 0;如果调用方的终结点在文本中出现的时间晚于目标终结点,则为正值。srcEndPoint 和 targetEndPoint 必须是 UIA。TextPatternRangeEndpoint 枚举 (Start = 0, End = 1) 。
- ExpandToEnclosingUnit(unit:=6) 按指定的文本单位规范化文本范围。如果小于指定单位,则扩大范围,如果大于指定单位,则缩短范围。unit 必须是 UIA。TextUnit 枚举 (字符 = 0,格式 = 1,Word = 2,行 = 3,段落 = 4,页 = 5,默认值为 Document = 6)
- FindAttribute(attr, val, backward:=False) 检索具有指定文本属性值的文本范围子集。attr 必须是 UIA。TextAttribute 枚举,并将 val 为所需值(有些可以是字符串,有些可以是文本属性枚举,例如 UIA。BulletStyle 枚举)
- FindText(text, backward:=False, ignoreCase:=False) 检索包含指定文本的文本范围子集。
- GetAttributeValue(attr) 检索整个文本范围内指定文本属性的值。attr 需要是UIA_TextAttributeId枚举。
- GetBoundingRectangles() 为文本范围中每行完全或部分可见的文本返回一个边界矩形对象数组 {x:top left X-coord,y:top left Y-coord,w:width,h:height}。
- GetEnclosingElement() 返回包含文本范围的最内层的 UI 自动化元素。
- GetText(maxLength=-1) 返回文本范围的纯文本。maxLength 是要返回的字符串的最大长度,如果不需要限制,则为 -1。
- Move(unit, count) 将文本范围向前或向后移动指定数量的文本单位。unit 必须是 UIA。TextUnit 枚举 (字符 = 0,格式 = 1,单词 = 2,行 = 3,段落 = 4,页面 = 5,默认值为 Document = 6)。
- MoveEndpointByUnit(endpoint, unit, count) 将文本范围的一个终结点移动到文档范围中指定数量的文本单位。endpoint 必须是 UIA。TextPatternRangeEndpoint 枚举 (Start = 0, End = 1) 。unit 必须是 UIA。TextUnit 枚举 (字符 = 0,格式 = 1,单词 = 2,行 = 3,段落 = 4,页面 = 5,默认值为 Document = 6)。
- MoveEndpointByRange(srcEndPoint, range, targetEndPoint) 将当前文本范围的一个终结点移动到第二个文本范围的指定终结点。srcEndPoint 和 targetEndPoint 必须是 TextPatternRangeEndpoint 枚举。
- Select() 选择与此文本范围相对应的文本范围,并删除任何先前的选择。
- AddToSelection() 将文本范围添加到支持所选文本的多个不相交跨度的控件中的选定文本范围的集合中。
- RemoveFromSelection() 从支持多个不相交选择的文本容器中所选文本的现有集合中删除文本范围。
- ScrollIntoView(alignToTop) 使文本控件滚动,直到文本范围在视口中可见。alignToTop 是一个布尔值。
- GetChildren() 返回一个属于文本范围内的元素数组。
TextRange2 方法
- ShowContextMenu()
TextRange3 方法
- GetEnclosingElementBuildCache(cache请求)
- GetChildrenBuildCache(缓存请求)
- GetAttributeValues(attributeIds, attributeIdCount) 返回属性值数组
08. 常见陷阱;技巧和窍门
序言
使用 UIA 有时会非常棘手,并且可能会遇到错误或不可预见的不稳定行为。这有多种原因:
- UIA 的用户群(包括这个库和 UIAutomation 本身)是小众的,而且测试它的人数也很少,所以更有可能出现错误。
- 最初,UIA 是创建辅助功能(有视力或听力问题的人),因此 UIA 的某些部分比其他部分受到更多关注:模式有时无法按预期工作,ElementFromHandle 或 TreeWalkers 等方法可能并不总是给出预期的结果等。
- UIA 属性/方法有时需要由程序创建者自己实现,他们可能不太(或任何)关注可访问性。大多数常用控件(按钮、复选框等)工作正常,但专用控件可能根本无法访问。此外,某些类型的窗口有时很难访问,例如 Qt 窗口。 如果您遇到任何奇怪的错误或问题,请务必在此 GitHub 页面或 AutoHotkey 论坛帖子上提出问题。
常见陷阱
窗口不可见
- 如果窗口最小化,则UIA无法访问它,因此请考虑为此添加检查(使用WinGet)。
- 当窗口不可见时,某些程序会隐藏其 UIA 树以节省内存。Chromium 应用程序尤其会执行此操作,因此在使用 UIA 调用之前要小心激活窗口。
Chromium 窗口
有时,基于 Chromium 的窗口(例如 Chrome、Microsoft Teams、Skype、Discord)无法像正常使用 ElementFromHandle 一样访问,并且无法访问内容。在这种情况下,您将需要使用 ElementFromChromium:
如果 Window Spy 显示ahk_class或内容,您就知道您正在处理 Chromium 窗口。
ahk_class Chrome_WidgetWin_1ClassNN Chrome_RenderWidgetHostHWND1
此外,默认情况下,Chromium 可能未启用辅助功能,这意味着常规 ElementFrom…方法可能不起作用,并且应用的内容可能不会显示。我们可以通过向 Chromium 发送特殊消息(WM_GETOBJECT 到 Chrome_RenderWidgetHostHWND1)来向 Chromium 发送可访问性信号,这会激活 UIA 并使内容可访问。国际律师协会。元素从…方法(ElementFromHandle 等)默认执行此操作,因为 Chromium/Electron 应用程序太多了,但为了获得最佳性能,可以通过将 activateChromiumAccessibility 设置为 False 来关闭它(例如)。UIA.ElementFromHandle("A",, False)
技巧和窍门
我感兴趣的元素没有任何特征来找到它
通常,可以使用 Name、ControlType、AutomationId、ClassName 或这些元素的组合来查找元素。例如,可能有多个名称为“Username”的元素,但只有一个具有该名称的 Edit 字段,因此可以使用 FindElement({Name:“Username”, Type:“Edit”})。 但是,在某些情况下,该元素实际上没有任何可辨别的东西。在这些情况下,有几种选择:
- 首先找到一个“引用”元素,然后使用 WalkTree 在树中移动到感兴趣的元素。例如,如果网页具有名为“Username:”的 Text 元素,但相应的 Edit 字段没有唯一名称,则如果 Edit 元素是 UIA 树中 Text 元素的下一个同级元素,请使用 .
element.FindElement({Name:"Username", Type:"Edit"}).WalkTree("+1") - 在主元素中查找一个容器元素,FindElement 将在其中返回您感兴趣的元素。例如,一个窗口可能有许多名为“Username:”的元素,但如果感兴趣的元素位于名为“Login fields”的容器内,则首先找到该容器,然后在该容器上使用 FindElement 而不是 window 元素。
- 使用 ElementFromPath 按路径查找元素。您可以使用 UIAViewer 获取 UIA 路径或条件路径。请注意,如果窗口的结构发生变化(例如,软件更新,或者用户更改了软件),则路径也会更改。
速度改进
UIA 通常比 MSAA/Acc 慢,但如果使用得当,它应该比人类快。这里的主要建议是尽可能限制对当前(实时)元素的搜索,这意味着通过批处理条件和使用缓存来限制 FindElement 和 FindElements 调用的数量。
- 如果只查找 1-2 个元素,请使用 FindElement,但如果搜索 3+ 个元素,请考虑将 FindElements 与条件批处理一起使用。避免不必要地使用 FindElements,因为它通常会查看整个树,而 FindElement 会在找到匹配项后停止搜索。
- 请考虑使用 FindElements 和批处理条件,而不是多次 (3+) FindElement 调用,以便通过一次调用返回所有所需元素,然后可以由其属性确定各个元素。例如,如果搜索名为“Username”和“Password”的字段,则不要做 和 ,而是 do 和 。由此获得的速度改进受元素在树中的位置的影响。如果 Username 和 Password 位于树的末尾,则一个 FindElements 调用将与一个 FindElement 调用一样快,因此速度是原来的两倍(因为我们只执行一次调用而不是两次调用)。如果元素位于树的开头,则执行两个 FindElement 调用可能会更快。一般来说,如果寻找 3+ 匹配项,最好使用 FindElements。
user := FindElement({Name:"Username"})pass := FindElement({Name:"Password")els := FindElements([{Name:"Username"}, {Name:"Password"}])user := els[1].Name = "Password" ? els[2] : els[1] - 使用较小的搜索范围。默认值为 TreeScope.Descendants (= 4),但在某些情况下,这可能非常慢。如果树的第一个分支很大,但后面的分支非常小,并且您感兴趣的元素位于后面的分支中,则最好先使用 FindElement TreeScope.Children 获取后面的分支,然后从该分支开始使用 FindElement。例如,在Firefox中,每个标签页的内容都显示在UIA树中,因此除非搜索范围受到限制,否则Firefox中的搜索可能会变得非常慢(它们会搜索所有标签页!在Firefox的案例中,搜索可以限制在活动选项卡上,然后使用.这里的关键是搜索范围“子”,它避免在查找活动选项卡面板时浏览任何选项卡内容。
activeTab := firefox.FindElement({IsOffscreen:0, AutomationId:"panel-", mm:2, scope:"Children"})activeTab.FindElement(...) - 根据元素在树中的位置,设置 FindElement 的“order”参数也可能加快搜索速度。例如,如果元素位于树的末尾,则将其设置为“LastToFirstOrder”(或者将索引设置为 -1),以便搜索将从树的末尾开始。
- 如果需要多次搜索,缓存可以显着提高搜索速度,因为可以使用搜索函数的“缓存”变体(例如 FindCachedElement)进行搜索,它比常规函数快得多。如果您不需要与元素交互,请使用 UIA。AutomationElementMode.None 作为 CacheRequest 模式将进一步加快搜索速度。国际律师协会。AutomationElementMode.None 将只提取元素的一小部分(CacheRequest 中定义的属性),而如果没有它,将返回整个元素(这很慢)。
- 对于多个搜索,请考虑使用“startingElement”参数。通过设置该参数,搜索将从该元素开始,而不是从树的开头开始。例如,如果您已经找到了“Username”元素,并且想要获取“Password”元素,请从之前找到的元素开始搜索:
WindowEl.FindElement({Name:"Password", startingElement:usernameElement})
调试
元素是否可访问?
使用 UIAViewer 或辅助功能见解,确保 UIA 确实可以访问该元素,并检查它有哪些可用的属性、方法和模式。
你得到正确的元素了吗?
- 使用 UIAViewer 确保您拥有适合搜索条件的正确数据:例如,在按名称查找时,“值”与末尾有空格的“值”不同。
- use 元素。Dump()、DumpAll() 或 Highlight() 方法检查您得到的元素是否正确
- 如果使用模式,请通过检查模式的属性来确保实际获得模式。
是否可以从控件访问元素?
有时,只有在控件句柄上使用元素时才会显示元素,而不是在主窗口本身上使用元素。您可以通过使用 UIATreeViewer 并展开左侧的窗口控件树来检查这一点。如果元素确实位于控件 UIA 树中,则 use 获取控件的句柄并在 中使用它。ElementFromHandleControlGetHwndElementFromHandle
该模式有效吗?
如果尝试使用模式方法(如 InvokePattern Invoke()),请确保该方法确实使用 Accessibility Insights 或 UIAViewer 与元素一起使用。有时,该模式显示为“可用”,但未正确实现,实际上不起作用。
事件
使用事件时,请使用辅助功能见解检查元素及其父元素,以查看目标事件是否实际触发。例如,PropertyChangedEvent 实际上不是由程序发送的,而 StructureChanged 事件可能会发送,这是相对常见的。这意味着您必须改用 StructureChanged。 在 Accessibility Insights 中,首先检查目标元素,然后单击“…”按钮打开侦听事件:
09. 高级:活动
介绍
UIA 事件可用于为用户界面中的各种更改设置侦听器。
通常处理事件侦听器/处理程序,我们需要遵循三个步骤:
- 创建一个事件处理程序,它指向我们希望事件触发的函数
- 将处理程序注册到自动化事件侦听器
- 完成后,删除事件侦听器
事件类型
Microsoft 文档中提供了有关事件类型的更全面概述。
属性更改
当 UIA 元素或控件模式的属性发生更改时引发。例如,这些类型的事件侦听器可用于监视 TogglePattern ToggleState 上的属性更改,因此当复选框的状态发生更改(切换)时,将引发此事件。
元素操作
当 UI 中的更改由用户或编程活动导致时引发,例如,当通过 Invoke 模式单击或调用按钮时。
结构变化
当 UIA 树的结构发生更改时引发,例如,当新的 UI 项变得可见、隐藏或删除时。
全局桌面更改
当发生全局关注的操作时引发,例如当焦点从一个元素转移到另一个元素时,或者当窗口关闭/打开时。
通知
当应用专门引发通知事件时引发(例如,Edge 在页面重新加载、页面加载完成和许多其他情况下引发此事件)。NotificationKind 指示通知的类型。
创建事件侦听器
创建处理程序
可以使用 创建新的事件处理程序,以返回新的处理程序对象。UIA.Create...EventHandler(callback)
- funcName:事件发生时接收调用的函数
“……”取决于处理程序将与之一起使用的事件类型。例如,如果使用 in ,则使用 创建处理程序。UIA.AddAutomationEventHandlerUIA.CreateAutomationEventHandler
根据处理程序的类型,回调函数需要接受一定数量的参数:
- HandleAutomationEvent(sender, eventId) <—这是使用 AddAutomationEventHandler 创建的最常见的处理程序类型,并且处理程序函数需要恰好有两个参数:sender(发送事件的元素)和 eventId。
- HandleFocusChangedEvent(发送方)
- HandlePropertyChangedEvent(发件人、propertyId、newValue)
- HandleStructureChangedEvent(发送方、更改类型、运行时 ID)
- HandleTextEditTextChangedEvent(发送者、更改类型、事件字符串)
- HandleChangesEvent(发送者、uiaChanges、changesCount)
- HandleNotificationEvent (发件人, notificationKind, notificationProcessing, displayString, activityId)
例如,最常见的事件处理程序是 AddAutomationEventHandler。对于这种类型的处理程序,您只需要指定一个函数名称,该函数将在事件发生时调用,并且该函数需要有两个参数:
添加事件处理程序
- AddAutomationEventHandler(handler, element, eventId, scope:=0x4, cacheRequest:=0),其中 eventId 必须是 UIA 之一。事件值
- AddPropertyChangedEventHandler(handler, element, propertyArray, scope:=0x4, cacheRequest:=0)
- AddStructureChangedEventHandler(handler, 元素)
- AddFocusChangedEventHandler(handler, cacheRequest=0)
- AddTextEditTextChangedEventHandler(处理程序,元素,textEditChangeType,范围:=0x4,cacheRequest:=0)
- AddChangesEventHandler(处理程序, 元素, changeTypes, 范围:=0x4, cacheRequest:=0)
删除事件处理程序
每个添加…EventHandler 具有相应的 Remove…事件处理程序。例如,AddAutomationEventHandler 和 RemoveAutomationEventHandler。
- RemoveAllEventHandlers()
- RemoveAutomationEventHandler(handler, 元素, eventId)
- RemovePropertyChangedEventHandler(handler, 元素)
- RemoveStructureChangedEventHandler(handler, 元素)
- RemoveFocusChangedEventHandler(处理程序)
- RemoveTextEditTextChangedEventHandler(handler, 元素)
- RemoveChangesEventHandler(handler, 元素)
最简单的方法是设置一个 OnExit() 函数并在退出之前调用以释放所有事件处理程序。UIA.RemoveAllEventHandlers()
例子
FocusChanged 事件
请参阅 Example7_FocusChangedEvent.ahk
选择事件
请参阅 Example8_SelectionEventHandler.ahk
TextChanged 事件
请参阅 Example18_TextRangeTextChangedEvent.ahk
PropertyChanged 事件
请参阅 Example19_PropertyChangedEvent.ahk
StructureChanged 事件
请参阅 Example20_StructureChangedEvent.ahk
通知事件
请参阅 Example21_NotificationEvent.ahk
10. 高级:缓存
介绍
通常,从 UIA 获取数据的步骤如下:
- 我们向 UIA 发送请求,例如元素。Name 或 FindElement。发送此调用的速度非常快。
- UIA 对数据的实际窗口/进程执行跨进程调用。这个动作很慢。
- UIA将结果返回给我们。同样,这发生得很快。
在对属性或模式进行多次调用时,发生跨进程调用的第二步可能会导致长时间的延迟,因此我们希望尽可能避免这样做。一种方法是通过创建一个条件,将 Find 调用批处理为一个,该条件一次返回我们感兴趣的所有元素。例如,如果我们需要同时使用“用户名”和“密码”文本框,则可以使用 .FindElement({Type:"Edit", Name:"Username"})FindElement({Type:"Edit", Name:"Password"})FindElements({Type:"Edit", or:[{Name:"Username"}, {Name:"Password"}]})
另一种方法是使用缓存,这意味着预取数据。这意味着 UIA 将预取仅具有感兴趣属性的元素,然后我们可以更快地搜索这些元素,因为无需进一步的跨进程通信即可访问数据(快速)。缓存通常用于批量检索属性和控件模式,然后根据需要从缓存中检索信息。
在 Microsoft 的文档中阅读有关缓存的更多信息。
使用缓存
- 使用 创建一个新的缓存请求,这将返回一个新的 CacheRequest 对象
cacheRequest := UIA.CreateCacheRequest(properties?, patterns?, scope?, mode?, filter?)
- properties 可以是属性名称的数组,也可以是 UIA。属性值
- patterns 可以是模式名称或 UIA 的数组。模式值
- scope 可以是 UIA。TreeScope 值,这定义了要缓存的元素的 TreeScope
- mode 可以是 UIA。AutomationElementMode 值。这定义了是否使用对元素的完整引用 (UIA.AutomationElementMode.Full,这意味着也可以访问当前值,并且可以正常使用模式),或者不引用基础元素 (UIA.AutomationElementMode.None,表示无法访问当前值,也无法使用模式方法;这通常提供 ~1.5-2 倍的速度优势)
- filter 可以是条件对象,用于选择要缓存的元素
- 例如,通过提供带有 CacheRequest 的 Find 或 TreeWalker 方法来生成缓存
cachedElement := FindElement(condition,,,, cacheRequest) - 现在可以访问缓存的属性(例如)、模式(例如)和子属性()。
cachedElement.CachedNamecachedElement.CachedWindowPatterncachedElement.GetCachedChildren()
您还可以使用 或 将要缓存的属性和模式添加到 CacheRequest 中,指定范围 (UIA.TreeScope) 的缓存请求,AutomationElementMode 和 TreeFilter。CacheRequest.AddPattern(pattern)CacheRequest.AddProperty(property)CacheRequest.TreeScope := scopeCacheRequest.AutomationElementModeCacheRequest.TreeFilter
缓存树
使用缓存时,UIA 实质上包含两棵树:一棵树用于当前元素(“活动”元素),另一棵树用于缓存元素。这些树可能看起来相同,也可能完全不同,具体取决于所使用的 TreeFilter。例如,如果使用,则树将仅包含 Button 类型的元素。CacheRequest.TreeFilter := {Type:"Button"}
这也意味着我们不能同时在两棵树中寻找元素。FindElement(s) 是用于查找 Current 元素的搜索方法,它不会使用 Cached 属性来执行此操作。另一方面,FindCachedElement (s) 将仅使用 Cached 属性,如果 Cached 属性不可用,则会引发错误。
缓存的范围和筛选
可以通过在激活请求之前使用或在创建 CacheRequest 时设置 scope 参数来指定要缓存其属性和模式的元素。作用域与请求处于活动状态时检索的元素相关:例如,如果仅设置 UIA。TreeScope.Children,然后检索一个元素,则缓存该元素的子元素的属性和模式,但不缓存元素本身的属性和模式,也不缓存作为子元素的元素的属性和模式。无法将范围设置为“父级”或“上级级”。CacheRequest.TreeScope := scope
缓存的范围也受该属性的影响。默认情况下,仅对出现在 UIA 树的控件视图中的元素执行缓存。但是,您可以更改此属性,以将缓存应用于所有元素,或仅应用于与条件匹配的元素。CacheRequest.TreeFilterCacheRequest.TreeFilter := condition
元素参考的强度
检索元素时,默认情况下还可以访问该元素的所有 Current 属性和模式,包括未缓存的属性和模式。但是,为了提高效率,可以通过将 CacheRequest 的属性设置为 UIA,指定对元素的引用仅引用缓存的数据。在这种情况下,您无权访问检索到的元素的任何非缓存属性和模式。这意味着,如果没有“Cached”前缀,您将无法访问任何属性或模式。在缓存模式上,可以调用检索数组属性的方法(如 SelectionPattern.GetSelection),但不能调用对控件执行操作的任何方法(如 InvokePattern.Invoke)。CacheRequest.AutomationElementMode
屏幕阅读器是可能不需要对对象的完整引用的应用程序的一个示例,它将预提取窗口中元素的 Name 和 Type 属性,但不需要元素对象本身。
更新缓存
仅当 UI 中没有任何更改时,缓存才有效。应用程序负责更新缓存,通常用于响应事件。
如果在 CacheRequest 处于活动状态时订阅事件,则每当调用事件处理程序函数时,都会获取具有更新缓存的 Element 作为事件的源。 您还可以通过调用 来更新元素的缓存信息。BuildUpdatedCache 将返回一个包含更新的 Cached 属性的新元素。Element := Element.BuildUpdatedCache(cacheRequest)
例子
缓存转储
页脚
11. 与原始UIA的区别
介绍
这个库不是 Microsoft 的 UIAutomation 框架的直接包装器,而是在某些方面重新构想和简化它。它也不同于 thqby 的 AHK v2 原始 UIAutomation 库,后者密切关注 Microsoft 的实现。
条件
此库无需使用 UIA 条件创建函数(如 ),而是实现条件对象,这些对象通过搜索方法或使用 转换为 IUIAutomationCondition 对象。从本 Wiki 的 Conditions 部分阅读有关这些条件对象语法的更多信息。这些对象由最常用的方法(如 FindElement、FindFirst 和 CreateTreeWalker)自动检测。IUIAutomationConditions 也可以输入到相同的方法中。UIA.CreatePropertyConditionUIA.CreateCondition
参数顺序
缓存
对于所有 BuildCache 方法,第一个参数通常是 cacheRequest。而不是原来的 ,我们现在有了 . 一些自定义方法还具有可选的 cacheRequest 参数,在这种情况下,它通常是最后一个(或最后一个)参数。例:。IUIAutomationElement::FindFirstBuildCache(scope, condition, cacheRequestElement.FindFirstBuildCache(cacheRequest, condition, scope)Element.FindElement(condition, scope:=4, startingElement:=0, traversalOptions:=0, cacheRequest:=0)
树状体
TreeScope 参数 (scope) 通常按顺序向后推送,因为它很少需要从默认的 Descendants 更改。这意味着我们有.IUIAutomationElement7::FindFirstWithOptions(scope, condition, traversalOptions, root)Element.FindFirstWithOptions(condition, traversalOptions:=0, root:=0, scope:=4, cacheRequest:=0)
FindElement 是一个例外,因为它是多个不同 Find 方法的组合,因此必须支持可能不支持 FindFirstWithOptions 的不同版本的 Windows。
事件
在涉及具有处理程序对象的事件的所有方法中,处理程序是第一个参数。例如UIA.AddAutomationEventHandler(handler, *)
12. UIA_Browser
介绍
UIA_Browser.ahk 是 UIA.ahk 的一个附加组件,可以更轻松地自动化浏览器:它包含页面导航、页面加载检测、Javascript 注入等方法。目前UIA_Browser支持 Chrome 和 Edge,在较小程度上支持 Firefox。
开始
使用 启动新的 UIA_Browser 实例。这将“挂钩”到浏览器上,并将在浏览器窗口中预取一些常用元素(文档元素、URL 栏等)。cUIA := UIA_Browser(wTitle="")
可以使用 UIA_Chrome、UIA_Edge UIA_Mozilla启动特定浏览器的实例(参数与UIA_Browser的参数相同),但这通常不是必需的,因为浏览器类型是由UIA_Browser自动检测的。可以使用额外的 javascriptExecutionMethod 参数创建UIA_Mozilla:默认情况下,Javascript 注入将通过打开控制台并将代码粘贴到那里来完成,但这也可以设置为“书签”以允许通过 URL 栏执行。为此,您需要创建一个带有 URL “javascript:%s” 和关键字 “javascript” 的新书签。UIA_Mozilla(wTitle:="", javascriptExecutionMethod:="Console")
通过 UIA_Browser 对象,您可以访问浏览器元素、UIA 对象和UIA_Browser方法/属性。这意味着可以使用 来搜索页面元素,而更改 UIA 属性可以通过 或 来完成。cUIA.FindElementUIA.Property := valuecUIA.Property := value
UIA_Browser住宿
浏览器 Id
浏览器窗口的ahk_id
浏览器类型
“Chrome”、“Edge”、“Mozilla”或“未知”
BrowserElement(浏览器元素)
浏览器窗口元素(也可以通过仅从 UIA_Browser 调用元素方法(将在 BrowserElement 上调用 FindElement 方法)来访问cUIA.FindElementcUIA.BrowserElement.FindElement)
MainPaneElement
浏览器上部的元素,包含 URL 栏、选项卡、扩展等
URLEdit元素
地址栏的元素
UIA_Browser方法
GetCurrentMainPaneElement
GetCurrentMainPaneElement()刷新 UIA_Browser.MainPaneElement 并返回它
GetCurrentDocumentElement
GetCurrentDocumentElement()返回浏览器的当前文档/内容元素。
GetAllText
GetAllText()从浏览器元素获取所有文本(所有子元素的 Name 属性)
GetAll链接
GetAllLinks()从浏览器获取所有链接元素(返回 HyperLink 元素的数组)
WaitTitle更改
WaitTitleChange(targetTitle:="", timeOut:=-1)等待浏览器标题更改为 targetTitle(默认只是等待标题更改),timeOut 以毫秒为单位(默认为无限期等待)
WaitPage加载
WaitPageLoad(targetTitle:="", timeOut:=-1, sleepAfter:=500, titleMatchMode:=3, titleCaseSensitive:=True)等待浏览器页面加载到 targetTitle,默认 timeOut 为无限期等待,sleepAfter 在页面加载后额外休眠 500 毫秒。(可选)可以指定特定的 targetTitle 以提高可靠性。
返回
Back()按下“返回”按钮
向前
Forward()按下前进按钮
重新加载
Reload()按下重新加载按钮
家
Home()按下主屏幕按钮(如果存在)。
GetCurrentURL
GetCurrentURL(fromAddressBar:=False)获取当前 URL。fromAddressBar=True 直接从 URL bar 元素获取它,这不是一个非常好的方法,因为文本可能由用户更改,并且不以“http(s)://”开头。默认值 fromAddressBar=False 将导致获取真实 URL,但浏览器必须可见才能正常工作(如果不可见,窗口将自动激活)。
设置网址
SetURL(newUrl, navigateToNewUrl:=False)将 URL 栏设置为 newUrl,如果 navigateToNewUrl=True,也可以选择导航到该栏
导航
Navigate(url, targetTitle:="", waitLoadTimeOut:=-1, sleepAfter:=500)导航到 URL 并等待页面加载
新标签
NewTab()按“新建选项卡”按钮。
GetTab
GetTab(searchPhrase:="", matchMode:=3, caseSensitive:=True)返回一个 tab 元素,其中包含 searchPhrase 文本,如果为空,则返回当前选定的选项卡。如果未找到具有指定 searchPhrase 的选项卡,则会引发 TargetError。matchMode 遵循 SetTitleMatchMode 方案:1=选项卡名称必须以 tabName 开头;2=可以包含在任何地方;3=完全匹配;正则表达式
选项卡存在
TabExist(searchPhrase:="", matchMode:=3, caseSensitive:=True)检查是否存在文本为 searchPhrase 的 tab 元素:如果找到匹配的选项卡,则返回该元素,否则返回 0。matchMode 遵循 SetTitleMatchMode 方案:1=选项卡名称必须以 tabName 开头;2=可以包含在任何地方;3=完全匹配;正则表达式
GetTabs(获取选项卡)
GetTabs(searchPhrase:="", matchMode:=3, caseSensitive:=True)返回所有带有 searchPhrase 文本的选项卡元素,如果为空,则返回所有选项卡。matchMode 遵循 SetTitleMatchMode 方案:1=选项卡名称必须以 tabName 开头;2=可以包含在任何地方;3=完全匹配;正则表达式
GetAllTabNames
GetAllTabNames()获取选项卡的所有标题(返回数组)
选择选项卡
SelectTab(tabName, matchMode:=3, caseSensitive:=True)选择文本为 tabName 的选项卡。matchMode 遵循 SetTitleMatchMode 方案:1=选项卡名称必须以 tabName 开头;2=可以包含在任何地方;3=完全匹配;正则表达式
关闭选项卡
CloseTab(tabElementOrName:="", matchMode:=3, caseSensitive:=True)通过提供选项卡元素或选项卡名称来关闭选项卡。如果 tabElementOrName 留空,则当前选项卡将关闭。如果未找到指定名称的选项卡,则会引发 TargetError。
IsBrowserVisible
IsBrowserVisible()如果浏览器的 4 个角中的任何一个可见,则返回 True。
发送
Send(text)使用 ControlSend 将文本发送到浏览器。
GetAlertText
GetAlertText()从警报框中获取文本
关闭警报
CloseAlert()关闭警报框
JSExecute
JSExecute(js)使用地址栏执行 Javascript 代码
注意:在Firefox中,默认情况下,这是通过控制台完成的,这是一种缓慢且低效的方法。更好的方法是使用 URL“javascript:%s”和关键字“javascript”创建一个新书签。这允许使用“javascript alert(”hello“)”通过地址栏执行 javascript。要使 JSExecute 使用此方法,请创建 JavascriptExecutionMethod 设置为 “Bookmark” 的 UIA_Mozilla,或设置 cUIA.JavascriptExecutionMethod := “Bookmark”。默认值为“Console”。
JSReturnThrough剪贴板
JSReturnThroughClipboard(js)使用地址栏执行 Javascript 代码,并使用剪贴板返回代码的返回值(之后将其重置)
JSReturnThroughTitle
JSReturnThroughTitle(js, timeOut:=500)使用地址栏执行 Javascript 代码,并使用浏览器标题返回代码的返回值(之后将其重置)。这可能不可靠,因此建议改用剪贴板方法。
JSSetTitle
JSSetTitle(newTitle)通过地址栏使用 Javascript 更改浏览器标题
JSGetElementPos
JSGetElementPos(selector, useRenderWidgetPos:=False)使用 Javascript 的 querySelector 获取 Javascript 元素及其位置。useRenderWidgetPos=True 使用 Chrome_RenderWidgetHostHWND1 控件的位置来定位相对于窗口的位置元素,否则UIA_Browsers使用 CurrentDocumentElement 位置。
JSClick元素
JSClickElement(selector)使用 Javascript 的 querySelector 获取并单击 Javascript 元素
ControlClickJSElement
ControlClickJSElement(selector, WhichButton:="", ClickCount:="", Options:="", useRenderWidgetPos:=False)使用 Javascript 的 querySelector 获取 Javascript 元素,然后 ControlClick 该位置。useRenderWidgetPos=True 使用 Chrome_RenderWidgetHostHWND1 控件的位置来定位相对于窗口的位置元素,否则UIA_Browsers使用 CurrentDocumentElement 位置。
ClickJSElement (点击JSElement)
ClickJSElement(selector, WhichButton:="", ClickCount:=1, DownOrUp:="", Relative:="", useRenderWidgetPos:=False)使用 Javascript 的 querySelector 获取 Javascript 元素,然后单击该位置。useRenderWidgetPos=True 使用 Chrome_RenderWidgetHostHWND1 控件的位置来定位相对于窗口的位置元素,否则UIA_Browsers使用 CurrentDocumentElement 位置。


UIA v2有汉化版的么
看起来不错!