Skip to main content

UIElement：控件交互与属性类

UIElement 是对 Windows UI 控件的封装。当你通过 Selector 找到目标后，会得到一个 UIElement 实例，通过它可以实现点击、输入、截图及获取控件状态。

1. 导入模块​

通常 UIElement 是通过 Selector 查找返回的，但你也可以手动导入用于类型声明。

# 导入 UI 元素类
from ascript.windows.window import UIElement

2. 实例方法（动作交互）​

🖱️ 元素点击 click()​

触发控件的点击动作。

代码块：

# 执行点击操作
ui_element.click(simulate=False)

参数详解：

  • simulate (bool):
    • False: (默认/推荐) 尝试使用底层指令（Invoke/Toggle）直接触发。这种方式不移动鼠标，不干扰用户，且在窗口被遮挡时通常也有效。
    • True: 强制使用物理模拟。会将鼠标指针移动到元素中心并执行物理点击。

⌨️ 文本输入 input()​

向控件（如输入框）写入文字。

代码块：

# 向控件输入文本
ui_element.input(text, simulate=False)

参数详解：

  • text (str): 要输入的字符串内容。
  • simulate (bool):
    • False: (默认) 使用底层 ValuePattern 直接设置值，速度极快且不需要焦点。
    • True: 先模拟点击元素获取焦点，然后通过键盘敲击（SendKeys）方式输入文字。

📸 局部截图 capture()​

仅捕获该控件所在区域的画面。

代码块：

# 捕获控件截图
ui_element.capture(save_path=None)

参数详解：

  • save_path (str): 图片保存的本地路径（如 "C:/ele.png"）。若为 None 则不保存文件，直接返回 Pillow Image 对象。

3. 实例属性（状态查询）​

你可以通过 ui_element.属性名 直接获取控件的各项实时信息。

属性返回类型说明
namestr控件的名称 (Name)
typestr控件的类型名 (ControlTypeName)
valuestr获取控件当前显示的文本值或内容
res_idstr控件的资源 ID (AutomationId)
class_namestr控件的系统类名 (ClassName)
handleint控件的原生窗口句柄 (HWND)
centertuple元素中心点在窗口内的相对坐标 (x, y)
relative_recttuple相对窗口左上角的矩形区域 (left, top, right, bottom)
is_visiblebool控件当前是否在屏幕内可见
is_enabledbool控件是否处于启用（可交互）状态
is_clickablebool控件是否支持点击相关的底层协议
child_countint当前元素拥有的直接子节点数量
depthint该元素在 UI 树中所处的深度等级

💡 案例演示​

from ascript.windows.ui import Selector

# 1. 找到一个按钮并点击
btn = Selector(title="我的应用").name("登录").find()
if btn:
    # 优先尝试后台点击
    btn.click()

# 2. 找到输入框并读取/设置值
edit = Selector(title="我的应用").type("EditControl").find()
if edit:
    print(f"当前输入框内容是: {edit.value}")
    edit.input("新内容")

# 3. 截图并获取坐标
icon = Selector(title="我的应用").res_id("UserIcon").find()
if icon:
    icon.capture("icon.png")
    cx, cy = icon.center
    print(f"图标中心坐标: {cx}, {cy}")