Wingman

Appearance

API: UIA Button ​

按钮控件是最常见的 UI 元素，用于触发操作、提交表单、确认对话框等。

查找按钮 ​

按名称查找按钮 ​

说明：按按钮上显示的文本查找。这是最直观的方式，但可能因为界面改版或语言变化而失效。

函数签名：

python
find_button(name: str) -> UIElement | None
lua
find_button(name: string) -> UIElement | nil

参数：

  • name - 按钮上显示的文本（如"确定"、"取消"、"提交"）

返回：找到的按钮元素，未找到时返回 None/nil

python
from wingman import uia

# 查找名为"确定"的按钮
btn = uia.find_button("确定")
if btn:
    btn.click()

按 AutomationId 查找（推荐） ​

说明：使用开发者设置的唯一 ID 查找。这是最稳定的方式，不会因界面改版或语言变化而失效。

如何获取 AutomationId：参考 概述文档中的说明

函数签名：

python
find_by_id(id: str) -> UIElement | None
lua
find_by_id(id: string) -> UIElement | nil

参数：

  • id - 控件的 AutomationId（如"btnSubmit"、"btnOK"）
python
from wingman import uia

# 使用 AutomationId 查找（推荐）
btn = uia.find_by_id("btnSubmit")
if btn:
    btn["click"]()

操作按钮 ​

点击按钮 ​

说明：模拟鼠标点击按钮。这是最常见的操作，用于触发按钮关联的动作。

方法签名：

python
UIElement.click() -> None
lua
UIElement:click()
python
from wingman import uia

btn = uia.find_button("提交")
if btn:
    btn.click()
    print("已点击提交按钮")

双击按钮 ​

说明：模拟鼠标双击按钮。某些应用程序的双击按钮有特殊功能（如"运行"按钮可能双击会以调试模式启动）。

方法签名：

python
UIElement.double_click() -> None
lua
UIElement:double_click()
python
from wingman import uia

btn = uia.find_button("运行")
if btn:
    btn["double_click"]()
    print("已双击运行按钮")

检测按钮状态 ​

检查按钮是否启用 ​

说明：某些按钮在特定条件下会被禁用（如表单未填写完整时）。操作前检查状态可以避免失败。

获取状态的方式：通过 get_info() 方法获取按钮信息，其中 is_enabled 字段表示按钮是否可用。

python
from wingman import uia

btn = uia.find_button("提交")
if btn:
    # 获取按钮信息
    info = btn["get_info"]()

    # 检查是否启用
    if info.get('is_enabled', True):
        btn["click"]()
        print("已点击提交按钮")
    else:
        print("按钮已禁用，可能需要先完成其他操作")

等待按钮启用 ​

说明：某些按钮在加载过程中会被禁用，直到某些条件满足才启用。可以使用轮询方式等待按钮变为可用状态。

使用场景：

  • 等待异步操作完成
  • 等待表单验证通过
  • 等待数据加载完成
python
from wingman import uia, util

def wait_for_button_enabled(name, timeout=5000):
    """
    等待按钮启用

    参数:
        name: 按钮名称
        timeout: 超时时间（毫秒），默认 5 秒

    返回:
        启用的按钮元素，超时返回 None
    """
    start = util.get_time()
    while util.get_time() - start < timeout:
        btn = uia.find_button(name)
        if btn:
            info = btn["get_info"]()
            if info.get('is_enabled', True):
                return btn
        util.sleep(200)  # 每 200ms 检查一次
    return None

# 使用示例
btn = wait_for_button_enabled("确定", 10000)
if btn:
    btn["click"]()
    print("按钮已启用并点击")
else:
    print("等待超时，按钮仍未启用")

获取按钮信息 ​

查看按钮所有属性 ​

说明：get_info() 方法返回按钮的所有可用属性，包括名称、类型、状态等。这对于调试和理解按钮结构很有帮助。

常用属性：

  • name - 按钮显示文本
  • id - AutomationId（如果有）
  • className - 控件类名
  • role - 角色数值（int，Button = 2）
  • text - 控件文本
  • is_enabled - 是否启用
  • is_visible - 是否可见
  • bounds - 按钮的位置和大小（{x, y, width, height}）
python
from wingman import uia

btn = uia.find_button("确定")
if btn:
    info = btn["get_info"]()

    # 打印所有属性
    print(f"按钮名称: {info.get('name', '')}")
    print(f"id: {info.get('id', '')}")
    print(f"类名: {info.get('className', '')}")
    print(f"角色: {info.get('role', 0)}")
    print(f"是否启用: {info.get('is_enabled', True)}")
    print(f"是否可见: {info.get('is_visible', True)}")

    # 位置信息
    if 'bounds' in info:
        rect = info['bounds']
        print(f"位置: ({rect['x']}, {rect['y']})")
        print(f"大小: {rect['width']} x {rect['height']}")

完整示例 ​

表单提交场景 ​

python
from wingman import uia, util

def submit_form():
    """填写并提交表单的完整流程"""

    # 1. 填写用户名
    username = uia.find_edit("用户名")
    if username:
        username["set_value"]("player123")
        print("已填写用户名")

    # 2. 填写密码
    password = uia.find_edit("密码")
    if password:
        password["set_value"]("mypassword")
        print("已填写密码")

    util.sleep(500)

    # 3. 等待提交按钮启用
    submit_btn = wait_for_button_enabled("提交", 5000)
    if submit_btn:
        submit_btn["click"]()
        print("已点击提交按钮")
        return True
    else:
        print("提交按钮未启用")
        return False

# 执行
if submit_form():
    print("表单提交成功")
else:
    print("表单提交失败")

可用接口 ​

查找按钮 ​

Python 函数Lua 函数说明参数
find_button(name)find_button(name)按名称查找按钮name - 按钮显示文本
find_by_id(id)find_by_id(id)按 AutomationId 查找id - AutomationId
find_by_name(name)find_by_name(name)通用查找方法name - 元素名称

按钮操作 ​

Python 方法Lua 方法说明
click():click()点击按钮
double_click():double_click()双击按钮
get_info():get_info()获取按钮所有属性

按钮属性 ​

get_info() 返回键集：

属性类型说明
namestring按钮显示文本
idstringAutomationId（可能为空）
classNamestring控件类名
roleint角色数值（Button = 2）
textstring控件文本
is_enabledboolean是否启用
is_visibleboolean是否可见
has_focusboolean是否持有焦点
boundsobject位置和大小 {x, y, width, height}