Skip to main content

Selector：UI 元素定位器

Selector 类用于在 Windows 窗口的 UI 树中检索控件。它支持极具灵活性的链式调用：你可以先过滤属性，接着跳转层级，最后直接在链条末端触发动作。

1. 导入模块​

在使用选择器前，请确保已导入核心类：

# 导入选择器类
from ascript.windows.window import Selector

2. 初始化方法​

🔍 创建选择器 Selector()​

定义查找的起点。选择器会基于指定的窗口或标题开始构建 UI 树索引。

代码块：

# 初始化选择器实例
Selector(window=None, title=None, depth=0xFFFFFFFF)

参数详解：

  • window (Window): 目标窗口对象。若提供此参数，查找将限制在该窗口范围内。
  • title (str): 若 window 为 None，则根据此标题正则表达式查找并关联窗口。
  • depth (int): 初始搜索深度限制，默认搜索全层级。

3. 链式过滤方法​

用于筛选具有特定特征的控件。字符串参数均支持 正则表达式。

🏷️ 基础标识过滤​

.name()​

代码块： selector.name(val) 参数详解：

  • val (str): 匹配控件的 Name 属性。

.type()​

代码块： selector.type(val) 参数详解：

  • val (str): 匹配控件类型名（如 "ButtonControl", "EditControl"）。

.res_id()​

代码块： selector.res_id(val) 参数详解：

  • val (str): 匹配控件的 AutomationId（资源 ID）。

.class_name()​

代码块： selector.class_name(val) 参数详解：

  • val (str): 匹配控件的系统类名 ClassName。

.handle()​

代码块： selector.handle(val) 参数详解：

  • val (int): 匹配控件的原生窗口句柄。

⚙️ 状态与内容过滤​

.value()​

代码块： selector.value(val) 参数详解：

  • val (str): 匹配控件当前显示或持有的文本值。

.description()​

代码块： selector.description(val) 参数详解：

  • val (str): 匹配控件的 HelpText 描述信息。

.visible()​

代码块： selector.visible(val=True) 参数详解：

  • val (bool): 过滤当前是否在屏幕内显示的元素。

.enabled()​

代码块： selector.enabled(val=True) 参数详解：

  • val (bool): 过滤控件是否处于启用（非禁用）状态。

.clickable()​

代码块： selector.clickable(val=True) 参数详解：

  • val (bool): 过滤是否支持指令级点击模式的控件。

4. 链式跳转与动作方法​

在定位过程中改变搜索位置或直接触发交互。

⛓️ 关系跳转​

🌿 子级跳转 .child()​

代码块：

# 跳转到当前匹配节点的子节点
selector.child(index=None)

参数详解：

  • index (int/None): None 选取所有子元素；正整数 选取第 N 个（从 1 开始）；负整数 从后往前选取（如 -1）。

🌳 父级跳转 .parent()​

代码块：

# 向上跳回父级节点
selector.parent(n=1)

参数详解：

  • n (int): 向上跳转的层级数。例如 2 表示跳转到爷爷节点。

👬 兄弟跳转 .brother()​

代码块：

# 跳转到同级兄弟节点
selector.brother(index=None)

参数详解：

  • index (int): 目标兄弟节点在同级中的索引位置。

🖱️ 动作插值​

🖱️ 链式点击 .click()​

代码块：

# 在定位链条中直接执行点击
selector.click(simulate=False)

参数详解：

  • simulate (bool): False 尝试静默指令点击（不动鼠标）；True 强制物理模拟点击。

⌨️ 链式输入 .input()​

代码块：

# 在定位链条中直接输入文本
selector.input(msg)

参数详解：

  • msg (str): 要输入的字符串内容。

5. 执行与输出方法​

🎯 获取元素 find() / find_all()​

代码块：

# 返回找到的第一个 UIElement 对象
selector.find()

# 返回找到的所有满足条件的 UIElement 对象列表
selector.find_all()

🎄 获取 UI 树 get_uielement_tree()​

代码块：

# 解析并返回当前窗口的 UI 结构树
selector.get_uielement_tree(as_json=False)

参数详解：

  • as_json (bool): 为 True 时返回 JSON 字符串；为 False 返回嵌套的 UIElement 对象。

💡 案例演示​

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

# 1. 关联窗口
win = Window.find(process_name="notepad.exe")

# 2. 链式定位并点击
Selector(win).name("文件").type("MenuItem").click()

# 3. 跨层级跳转输入
# 找到“密码”文字 -> 跳到父级 -> 找子级中的输入框 -> 输入
Selector(win).name("密码").parent().child().type("EditControl").input("secret123")